Using Resource Indicators in order to get downscaled Access Tokens

Several APIs require Access Tokens with the API Resource as the only audience in the aud claim. If a Client needs to

1. consume more than one API, and
2. at least one of these APIs requires it's audience as the only audience in the Access Token

then, the Client can utilize the Resource Indicator mechanism in order to get Access Tokens that only contain a specific audience in the aud claim. This is what´s called a downscaled Access Token.

The specification for this mechanism can be found in Resource Indicators for OAuth 2.0.

Example code, which demonstrates the use of this mechanism, can be found in our public GitHub repository.

How to request multiple APIs by using Resource Indicators

We give an example, with two APIs, both of which require Access Tokens with a single audience.

Authenticating the user and indicating resources

In the first request to the PAR endpoint, the Client must set the following values:

• In the resource parameters: indicate which API resources that it needs to request. The parameters must be equivalent to the audiences for each API.
• In the scope parameter: the scopes the Client will use in order to consume the APIs
• In the scope parameter: set the offline_access scope in order to get a Refresh Token in the response

Example request to the PAR endpoint:

 POST /connect/par HTTP/1.1
 Host: helseid-sts.nhn.no
 Content-Type: application/x-www-form-urlencoded

 resource=nhn:siffer-tjeneste&
 resource=nhn:tekst-tjeneste&
 scope=nhn:openid profile offline_access siffer-tjeneste/primtall nhn:tekst-tjeneste/bokstaver&
 client_id=973f132f-47e5-4fb2-b211-43c242b7fce0&
 ... other parameters ...

Requesting the first Access Token

When the Client retrieves the code from the Authorization endpoint, it can specify the resource for which it wants to retrieve an Access Token. In our case, this will be resource=nhn:siffer-tjeneste.

 POST /connect/token HTTP/1.1
 Host: helseid-sts.nhn.no
 Content-Type: application/x-www-form-urlencoded

 resource=nhn:siffer-tjeneste&
 grant_type=authorization_code&
 client_id=973f132f-47e5-4fb2-b211-43c242b7fce0&
 ... other parameters ...

The response from this request will contain an Access Token where the aud claim contains (only) the value nhn:siffer-tjeneste, and the scope claim contains the value nhn:siffer-tjeneste/primtall.

Requesting the next Access Token

The Client can now use the Refresh Token to get another Access Token with a different value in the aud claim:

 POST /connect/token HTTP/1.1
 Host: helseid-sts.nhn.no
 Content-Type: application/x-www-form-urlencoded

 resource=nhn:tekst-tjeneste&
 grant_type=refresh_token&
 client_id=973f132f-47e5-4fb2-b211-43c242b7fce0&
 ... other parameters ...

The response from this request will now return an Access Token where the aud claim contains (only) the value nhn:tekst-tjeneste, and the scope claim contains the value nhn:tekst-tjeneste/bokstaver.

Remember that both Access Tokens can be used for authorization against the APIs as long as their expiration time holds.