Retrieve_an_Authentication_Token.md

Retrieve an Authentication Token

Retrieve a token for authenticating to one of the API gateways, for the shasta realm.

The following are important properties of authentication tokens:

• Keycloak access tokens remain valid for 365 days.
• Secrets do not expire; they are persistent in Keycloak.
• Tokens and secrets can be revoked at any time by an administrator.

The API gateways use OAuth2 for authentication. A token is required to authenticate with one of the gateways.

There are multiple API gateways that are used to access services from the different networks.

• services-gateway accessible at api.nmnlb.SYSTEM_DOMAIN_NAME or api-gw-service-nmn.local
• customer-admin-gateway accessible at api.cmn.SYSTEM_DOMAIN_NAME
• customer-user-gateway accessible at api.can.SYSTEM_DOMAIN_NAME or api.chn.SYSTEM_DOMAIN_NAME

The appropriate token must be retrieved from the gateway to access services on that gateway.

Procedure

Some of the example commands pipe their output to python -mjson.tool. This is not required; it is simply used to format the output for readability.

1. Retrieve a token.

   Retrieving a token depends on whether the request is based on a regular user (as defined directly in Keycloak or backed by LDAP) or a service account.

   • Resource owner password grant (user account)

     In this case, the user account flow requires the username, password, and the client ID.

     In the example below, replace myuser, mypass, and shasta in the command with site-specific values. The shasta client is created during the CSM install process.

     curl -s -d grant_type=password \
             -d client_id=shasta \
             -d username=myuser \
             -d password=mypass \
             https://auth.cmn.SYSTEM_DOMAIN_NAME/keycloak/realms/shasta/protocol/openid-connect/token |
         python -mjson.tool

     Example output:

     {
         "access_token": "ey...IA",
         "expires_in": 300,
         "not-before-policy": 0,
         "refresh_expires_in": 1800,
         "refresh_token": "ey...qg",
         "scope": "profile email",
         "session_state": "10c7d2f7-8921-4652-ad1e-10138ec6fbc3",
         "token_type": "bearer"
     }

     Use the value of access_token to make requests.

   • Client credentials (service account)

     The client credentials flow requires a client ID and client secret.

     There are a couple of ways to use a service account:

     • By creating a new service account.
     • By using the Keycloak client that was generated by the CSM installation process.

       • The client ID is admin-client.

       • The client secret is generated during the install and put into a Kubernetes secret named admin-client-auth.

         (ncn-mw#) Retrieve the client secret from this secret as follows:

         echo "$(kubectl get secrets admin-client-auth -ojsonpath='{.data.client-secret}' | base64 -d)"

         Example output:

         2b0d6df0-183b-40e6-93be-51c7854388a1
         

       • (ncn-mw#) Given the client ID and secret, the user can retrieve a token by requesting one from Keycloak.

         In the example below, replace the string being assigned to client_secret with the actual client secret from the previous step.

         curl -s -d grant_type=client_credentials \
                 -d client_id=admin-client \
                 -d client_secret=2b0d6df0-183b-40e6-93be-51c7854388a1 \
                 https://auth.cmn.SYSTEM_DOMAIN_NAME/keycloak/realms/shasta/protocol/openid-connect/token |
           python -mjson.tool

         Expected output:

         {
             "access_token": "ey...DA"
             "expires_in": 300,
             "not-before-policy": 0,
             "refresh_expires_in": 1800,
             "refresh_token": "ey...kg",
             "scope": "profile email",
             "session_state": "ca8ab15c-2378-40c1-8063-7a522274fce0",
             "token_type": "bearer"
         }

         Use the value of access_token to make requests.

2. (linux#) Present the token.

   To present the access token on the request, put it in the Authorization header on the request as a Bearer token.

   For example:

   TOKEN=access_token
   curl -k -H "Authorization: Bearer ${TOKEN}" https://api-gw-service-nmn.local/apis/smd/hsm/v2/service/ready

   Example output:

   {"code":0,"message":"HSM is healthy"}