Introduction

Tokens provides a way to authenticate services with OAuth providers. Please refer to OAuth documentation for detail description of OAuth protocol and further references. Here we will describe a practical aspect on how to obtain tokens within CMS environment.

There are multiple ways to obtain a token, either via oidc tools or by obtaining client's credentials and querying IAM provider. The former requires installation of oidc tools on your node and running oidc-agent, while latter can use standard tools like curl. Below we'll describe a process of obtaining token via client's credentials and curl tool.

Registration

To obtain IAM token via client's credentials you need to follow these steps:

• visit https://cms-auth.web.cern.ch/
• login via your X509 or CERN SSO, if necessary you'll need to register
• then, click on Self-service client registration
• provide proper fields in the main tab, these includes:
  • Client-Name, e.g. Test-WMAgent
  • Redirect URIs, e.g. https://cmsweb.cern.ch
  • Contacts, e.g. you may add some e-group which will handle the registration and access to tokens, for that I suggest to created admin group (we do follow that rule in CMSWEB, Monitoring groups) which will have only few members, like L2s or main developers. This group will receive emails or can be used to access to token afterwards
• go to Access tab and check all scopes your token will need, I chose compute.read, etc. which may be relevant for WMAgent
• THE MOST IMPORTANT: for Grant Types choose client credentials and for Response Types uncheck everything
• finally, return to main tab and click on Save. This will present you with client's credentials, configuration URI and registration access token. Save all of them in safe place (DO NOT SHARE). The client_id and client_secret will be used by this script and you'll need them to put in place on WMA node. While, registration token will be used if you'll later need to change something in your token configuration.

Getting the token

After you obtained your client_id and client_secret and saved them in some files you may run the provided script as following:

IAM_CLIENT_ID=./secrets/client_id IAM_CLIENT_SECRET=./secrets/client_secret bin/create-iam-token.sh

or, put your client_id and client_secret in different location. The script will generate token in /tmp/token which later you can use for access to OAuth protected sites and/or in your workflows.

If you prefer pure curl solution run the following command (which is executed within create-iam-token.sh):

curl -s -k -d grant_type=client_credentials \
            -u ${client_id}:${client_secret} \
            https://cms-auth.web.cern.ch/token

where client_id and client_secrets are your client id/secret values. or, put your client_id and client_secret in different location. The script will generate token in /tmp/token which later you can use for access to OAuth protected sites and/or in your workflows.

Validate your token

If you want to know what is stored in your token you may grab your token and visit jwt.io where you can paste it and see its attributes. We also provide decode-token tool which can be used as following:

# run client
./decode-token -token=$token

# if token is invalid you'll see the following message:
2022/02/22 13:49:38 The token is not valid
# otherwise the token attributes will be printed like this:

{
    "sub": "xxxx-yyyy-6251d28e94a1",
    "aud": "[https://wlcg.cern.ch/jwt/v1/any]",
    "iss": "https://cms-auth.web.cern.ch/",
    "username": "",
    "active": true,
    "session_state": "",
    "clientId": "xxxx-yyyy-51ee6a978680",
    "email": "",
    "scope": "address phone openid offline_access profile eduperson_scoped_affiliation eduperson_entitlement email wlcg",
    "exp": 1645557402,
    "clientHost": ""
}

This information is also visible from jwt.io web site when you will paste your token over there.

Managing IAM tokens in WMCore central services

Once you have valid token stored in a file you need to manage it accordingly since it will expire after some time. This can be done by running cronjob with create-aim-token.sh script which will store token in your desire location. Please refer to create-aim-token.sh script for more details which env variables to provide for this task.

Using tokens within WMCore codebase

To use your token from WMCore codebase, e.g. within your application or service, you need to define IAM_TOKEN environment variable to point either to your token value or to a file name which stores the token. Then, all calls which will be done via pycurl_manager module will use this token. If you will need to explicitly obtain token then you should do the following:

# load appropriate module
from Utils.TokenManager import getToken

# get token
token = getToken()

The getToken function by default uses IAM_TOKEN environment, but you can also provide to it a file name which stores the token, e.g.

# location of file which keeps token
fname = `/tmp/token`

# get token
token = getToken(fname)

Alternatively, you may use TokenManager class to manage your tokens

# load appropriate module
from Utils.TokenManager import TokenManager

# define manager to use specific location, in this case /tmp/token file
fname = `/tmp/token`
tmgr = TokenManager(fname)
token = tmgr.getToken()

# define/use HTTP headers
headers = {}
headers['Authorization'] = 'Bearer {}'.format(token)

# follow your code logic to use HTTP headers