Custom map for requesting OpenID claims with scope values

OpenID Connect allows client applications (relying parties) to request claims (assertions) about the end-user by including special OAuth 2.0 scope values in the OpenID authentication request.

For example, a client can use the profile scope value to request access to these user attributes the IdP: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale and updated_at.

OpenID Connect defines four such scope values that expand to specific sets of claims.

Scope value Claims
profile name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at
email email, email_verified
address address.formatted, address.street_address, address.locality, address.region, address.postal_code, address.country
phone phone_number, phone_number_verified

This concept can be applied to other (custom) scope values and claims that the identity provider needs to support. To define such a map use the following configuration file:

/WEB-INF/customClaimsMap.properties

For example, to let the custom org_details scope value request the claims roles, supervisor, employee_number add the following line to the file:

org_profile: roles, supervisor, employee_number

Prefix your custom scopes and claim names to prevent clashes

It's good practise to put your custom scopes and claims in a name space to prevent collisions with those of other identity providers. The recommended way to do that is with a common prefix:

  • An URI, such as a URL or URN, e.g. https://myidp.com/scopes/, urn:myidp:com:scope

  • Pattern similar to the Java package system, e.g. com.myidp.scopes

If the custom scopes and claims are URLs they can potentially be managed by a simple registry service, which lists their mappings and allows simple queries to check their validity and description (and return HTTP status 404 if the scope value or claim name is invalid).

Escaping special characters

The custom claims map is parsed as java.util.Properties. That format recognises the following chars as delimiter between key and value:

  1. Colon: :

  2. Equals sign: =

If either delimiter is present in the property key, it must be escaped. For example:

https\://myidp.com/scopes/my_custom_scope : https://myidp.com/claims/my_custom_claim1, https://myidp.com/claims/my_custom_claim2, https://myidp.com/claims/my_custom_claim3