Service account token

Learn how to use the service account token to connect with the License Service API server.

Service account token authentication provides flexible and customizable way to manage access to License Service APIs which is based on a role-based access control (RBAC).

The following article describes basic configuration. For more advanced configuration, see Using RBAC Authorization in Kubernetes documentation.

• Limitations
• Authentication and authorization
• Default configuration
• Custom configuration
• Using the API token

Limitations

Service account token is provided via http header. Because of that to retrieve the licensing data via the APIs from your browser, you must use the simplified License Service interface which is available under License Service URL. For more information, see Obtaining the License Service URL.

Authentication and authorization

• Authentication - Checks whether the provided service account token is correct for the service account on a cluster where License Service is deployed.
• Authorization - Checks whether the service account has a binding to License Service API endpoints.

Default configuration

By default, after installation, the ibm-licensing-default-reader service account is created in the namespace where License Service is deployed.

This service account has a binding to the cluster role that gives access to License Service APIs.

Obtaining the token for ibm-licensing-default-reader

By using the CLI

Complete the following steps to get the service account token by using kubectl:

Note: The commands assume that the IBM Cloud Pak foundational services are installed in ibm-common-services namespace. If IBM Cloud Pak for Multicloud Management installs services in a different namespace, adjust the commands.

1. Get the name of your Kubernetes secret object. Secrets are used to store access credentials.

   kubectl get secret -n ibm-common-services | grep ibm-licensing-default-reader-token | head -n 1
   

   Note:

   • ibm-licensing-default-reader-token-xxxxx can be either ibm-licensing-default-reader-token without any hash or with some hash. For example,ibm-licensing-default-reader-token-btjdk.

   • If there are no tokens found, then you might have kubernetes 1.24+ and not updated License Service, you can either update License Service or just create token:

      apiVersion: v1
      kind: Secret
      type: kubernetes.io/service-account-token
        metadata:
         name: ibm-licensing-default-reader-token
         namespace: ibm-common-services
         annotations:
           kubernetes.io/service-account.name: "ibm-licensing-default-reader"
     

   After creating this secret if ibm-licensing-default-reader service account exists kubernetes should add data.token in this secret, containing bearer token for this service account.

2. Retrieve the ibm-licensing-default-reader token.

   • For Linux and OSX run the following commands.

     • Linux:

       kubectl get secret ibm-licensing-default-reader-token-xxxxx -o jsonpath={.data.token} -n ibm-common-services | base64 -d
       

     • OSX:

        kubectl get secret ibm-licensing-default-reader-token-xxxxx -o jsonpath={.data.token} -n ibm-common-services | base64 -D
       

       The value that you get in the response is your API token.

   • For Windows run the following command.

     • Windows:

       kubectl get secret ibm-licensing-default-reader-token-xxxxx -o jsonpath={.data.token} -n ibm-common-services`
       

       Decode the returned base64 value to reveal your API token.

By using the OpenShift console

1. Log in to the OpenShift console of the cluster where you deployed License Service.
2. Go to Workloads > Secrets.

3. Find the ibm-licensing-default-reader-token-xxxxx secret and select it.

   Note: If more than one secret is listed, select any of these secrets.

4. Scroll to the Data section, and copy the token by clicking the Copy to Clipboard icon.

Custom configuration

You can create and use a different service account that has a binding to a proper cluster role to access License Service API. For more information, see Using RBAC Authorization in Kubernetes documentation.

Cluster role configuration

Configure a cluster role with the following content:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: <role name>
rules:
  - nonResourceURLs:
      - "/products"
      - "/snapshot"
      - "/bundled_products"
      - "/services"
      - "/health"
      - "/status"
    verbs:
      - "get"

where

nonResourceURLs is a list of the APIs to which the service account should have access. You can customize this list to met your requirements.

The list of available nonResourceURLs:

Important: This list might change in the future if new APIs are added. Monitor the list to make sure that you update the cluster role with access have access to all APIs.

Creating cluster role bindings

Create a cluster role binding for your custom service account with the following content:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: <binding name>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: <custom role name>
subjects:
  - kind: ServiceAccount
    name: <service account name>
    namespace: <service account namespace>

Creating service account token if needed

If you have kubernetes 1.24 or higher, then after creating your service account, the secret with bearer token would not be created by default. You need to create it manually:

apiVersion: v1
kind: Secret
type: kubernetes.io/service-account-token
metadata:
  name: <your_service_account_name>-token
  namespace: <namespace_where_you_have_your_service_account>
  annotations:
    kubernetes.io/service-account.name: "<your_service_account_name>"

Adding such annotations will make Kubernetes add token inside this secret in data.token. Then, you can retrieve your token in the same way as described in Step 2 of Obtaining token. But change the secret name and namespace to where you have it:

• For Linux, run the following commands:

   kubectl get secret <your_service_account_name>-token -o jsonpath={.data.token} -n <namespace_where_you_have_your_service_account> | base64 -d
  

• For OSX, run the following commands:

   kubectl get secret <your_service_account_name>-token -o jsonpath={.data.token} -n <namespace_where_you_have_your_service_account> | base64 -D
  

The value that you get in the response is your API token.

• For Windows, run the following command:

   kubectl get secret <your_service_account_name>-token -o jsonpath={.data.token} -n <namespace_where_you_have_your_service_account>
  

Decode the returned base64 value to reveal your API token.

Using the service account token

To connect to the API endpoint, you need to provide the secure authentication token. If you choose to use a service account token, you need to add it to the header for every API call.

The following example shows how to provide the service account token to access the License Service API.

curl -k -H "Authorization:Bearer <token>" <API URL>

The list of License Service APIs: