Best Practices from Oracle Development's A‑Team

Implementing Custom Claims in IDCS

Olaf Heimburger
Workload Architect - Security


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:

  1. Your IDCS instance must be on a Standard license – If your IDCS instance is on Foundation license you can elevate the IDCS license to Standard in your Oracle Identity Cloud Service service console.
    NOTE: Once elevated you cannot switch back to Foundation license!
  2. Custom claims must be enabled for the IDCS instance – Custom Claims are feature flagged and are disabled by default. You have to open a Service Request to enable them. If Custom Claims are not enabled, your request will fail and a proper error message will include the reason.
  3. A confidential application – This application is required to create an IDCS Access Token which is required to call the IDCS Custom Claims REST API to create and enable Custom Claims. It needs the Identity Domain Administrator App Role granted.


Sample Use Case: Adding the email Claim

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.

Configure the Custom Claim

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' \ -d <payload> with a payload like this: { "schemas": [ "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim" ], "name": "email", "value": "$user.emails.1.value", "expression": true, "mode": "always", "tokenType": "BOTH", "allScopes": true } The attributes used in this request are these:

Attribute Description
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:
  • always – Always include the claim.
  • request – Include the claim on request, when the defined scope is part of the request.
  • never – Never include the claim in a token. This value can be used to deactivate the Custom Claim when needed (for example in a test scenario).
tokenType Can have these values:
  • AT – The claim will be added to the Access Token
  • IT – The claim will be added to the ID Token
  • BOTH – The claim will be added to Access and ID Token
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).


Test the Custom Claim

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 { "app_access_token":"<token_value>" } 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): { "user_tz":"Europe/Berlin", "sub":"<my_sub_value>", ... "email":"<my_email_address>", ... "iss":"https://identity.oraclecloud.com/", ... "tok_type":"AT", ... } and the ID Token looks like this (abbreviated): { "user_tz":"Europe/Berlin", "sub":"<my_sub_value>", ... "email":"<my_email_address>", ... "iss":"https://identity.oraclecloud.com/", ... "tok_type":"IT", ... }


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.



This article has been inspired by the works of my fellow team mates Andre Correa Neto and Johannes Murmann.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha