When a user or a computer program logs into Oracle's Identity Cloud Service (IDCS) using one of the three OpenID Connect flows an ID Token and an Access Token will be issued. Both tokens come with a number of required claims, i.e., attributes, and their respective values (see OpenID Connect Core 1.0, 2. ID Token for details). These required claims are implemented by IDCS.
However, some applications are designed to expect additional claims in the ID Token or in the Access Token that are not required but requestable standard claims (see OpenID Connect, 5.1 Standard Claims for details).
To support these applications, IDCS provides a feature called Custom Claims to implement any additional claim as required. This article describes how to create and use such a Custom Claim in your application.
Usage of Custom Claims is a paid feature and has these requirements:
Although the required claims are sufficient in most uses cases, some applications expect an additional email claim in the ID Token or Access Token. Adding such a claim to both tokens is quite easy.
To configure the Custom Claim we use IDCS's Custom Claims REST API:
curl -i -X POST https://tenant-base-url/admin/v1/CustomClaims \
-H 'Authorization: Bearer <idcs_access_token>' \
-H 'Cache-Control: no-cache' -H 'Accept:application/json' \
with a payload like this:
The attributes used in this request are these:
|name||The claim name|
|expression||Define how the value is used by IDCS. When set to true, the value is an expression which will be replaced by actual values taken from IDCS. A value of false indicates that the value will be used as specified.|
|value||Expression or static value. In our example we use an expression to get the worker email address.|
|mode||Can have three values:
|tokenType||Can have these values:
|allScopes||true or false – When set to true it will be added to any scope, or to a set of scopes defined in the optional scopes attribute|
|scopes||Optional – An array of scopes (not used here).|
To verify the setup of the Custom Claim, we need to request the required token from IDCS. For the Access Token, you can log into IDCS console, click on your user icon on the upper right corner to open the menu, select My Access Tokens, and click on the Download Token butten.
The provided file tokens.tok looks like this
Now open tokens.tok, copy the <token_value>, and paste it into the JWT Debugger.
Other options to create an Acesss Token are: 1) use the way you created the Access Token for the IDCS REST API call or 2) the OpenID Connect Authorization Code Flow to get both values.
The Access Token looks like this (abbreviated):
and the ID Token looks like this (abbreviated):
This short article showed how to setup and test IDCS Custom Claims. It is a nice feature that helps to improve the compatibility of client application REST APIs across different token issuers.