Obtaining an IAM access token from a CLI

A token can be obtained from a command-line interface (CLI) in two ways:

  • using oidc-agent
  • using scripts linked to this page, using the resource-owner password credentials flow or the OAuth device flow

In this section we recommend the installations of a set of tools that can help in managing tokens.

Obtaining a token using oidc-agent

oidc-agent is a useful tool to easily get and manage access tokens for command-line applications.

Installing oidc-agent

See oidc-agent installation instructions.

Quick CENTOS7 installation instructions

This recipe shows how to quickly install oidc-agent on CENTOS 7.

$ yum -y install epel-release $ yum -y install https://github.com/indigo-dc/oidc-agent/releases/download/v3.3.1/oidc-agent-3.3.1-1.el7.x86_64.rpm

Bootstrapping oidc-agent

The first thing to do is to start oidc-agent. This can be done issuing the following command:

$ eval $(oidc-agent) Agent pid 62088

Registering a client

In order to obtain a token out of IAM, a user needs a client registered. oidc-agent can automate this step and store client credentials securely on the user machine. This is a one-time operation, you do not need a new client every time you need a token.

A new client can be registered using the oidc-gen command, as follows:

$ oidc-gen -w device wlcg

The -w device instructs oidc-agent to use the device code flow for the authentication, which is the recommended way with IAM.

oidc-agent will display a list of different providers that can be used for registration:

[1] https://wlcg.cloud.cnaf.infn.it/ [2] https://iam-test.indigo-datacloud.eu/ ... [20] https://oidc.scc.kit.edu/auth/realms/kit/

Select one of the registered providers, or type a custom issuer (for IAM, the last character of the issuer string is always a /, e.g. https://wlcg.cloud.cnaf.infn.it/).

Then oidc-agent asks for the scopes, typing max (without quotes) allows to get all the allowed scopes.

oidc-agent will register a new client and store the client credentials and a refresh token locally in encrypted form (the agent will ask for a password from the user).

As mentioned, oidc-gen is meant to be used only once, when you need a client registered.

Managing oidc-agent account configurations

To see the list of locally configured accounts use the following command:

> oidc-add -l The following account configurations are usable: DEEP-ac XDC atlas ... cms-voms-importer escape escape-monitoring iam-test infn-cloud wlcg

You can then load an account in the agent again with the oidc-add command, as follows:

oidc-add wlcg

Once you’ve loaded the account, you can use oidc-token to get tokens for that account.

Getting tokens with oidc-token

Tokens can be obtained using the oidc-token command, as follows:

oidc-token wlcg

This will request a token with all the scopes requested at client registration time. To limit the scopes included in the token, the -s flag can be used, as follows:

oidc-token -s storage.read:/ wlcg

The token audience can be limited using the --aud flag,

oidc-token --aud example.audience -s storage.read:/ wlcg

Accessing oidc-agent client configuration

Often is useful to get details about the client configuration generated by oidc-agent. This can be done with the oidc-gen -p command, that is used to print a client configuration, as in the following example:

❯ oidc-gen -p wlcg Enter decryption password for account config 'wlcg':****** { "name": "wlcg", "client_name": "oidc-agent:wlcg", "issuer_url": "https://wlcg.cloud.cnaf.infn.it/", "device_authorization_endpoint": "https://wlcg.cloud.cnaf.infn.it/devicecode", "daeSetByUser": 0, "client_id": "*****", "client_secret": "*****", "refresh_token": "****.*****.", "cert_path": "", "scope": "storage.create:/ openid offline_access storage.read:/ eduperson_scoped_affiliation storage.modify:/ wlcg wlcg.groups eduperson_entitlement", "audience": "", "redirect_uris": ["edu.kit.data.oidc-agent:/redirect", "http://localhost:8080", "http://localhost:47947", "http://localhost:4242"], "username": "", "password": "", "client_id_issued_at": 1600444894, "registration_access_token": "****", "registration_client_uri": "https://wlcg.cloud.cnaf.infn.it/register/****", "token_endpoint_auth_method": "client_secret_basic", "grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"], "response_types": ["token"], "application_type": "web", "cert_path": "", "audience": "" }

Obtaining a token with the password flow

The password flow allows a user to get a token from the IAM by using the IAM local credentials (i.e. the username/password credentials setup at IAM registration time).

In order to use the password flow, a non-privileged user has to:

  1. register a client following the instructions given in [the client registration][client-registration] section
  2. Note down the client_id of the generated client and ask an IAM administrator to enable the password flow for such client
  3. Wait until the client as the password flow enabled
  4. Use a script similar to the one given here (or write your own following the recommendations of the RFC) to obtain a token out of the IAM

Obtaining a token with the device code flow

The device code flow allows a user to get a token from the IAM from a CLI interface while using an external browser for the authentication step. This is convenient since:

  • it does not require any authorization from administrators (the device code flow can be requested by the user at client registration time)
  • it allows the user to authenticate with any of the authentication mechanisms supported by the IAM
  • it does not expose the user credentials to the client application

For nitty and gritty details on how the flow works, see the RFC.

After having registered a client with the device flow enabled (see client registration section), the device code flow can be used to obtain a token using a script like the one here which does the following:

  • contacts the device flow endpoint to start a device flow authentication and authorization
  • prints code information on the terminal
  • waits for user input to proceed and obtain the token(s)
Last modified March 24, 2022: Fix broken links (3f1bfdd)