Skip to content
Connect2id

Custom scopes for claims

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

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

https://c2id.com/login?
    response_type=code
    &scope=openid%20profile
    &client_id=000123
    &state=co7Eigha
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

OpenID Connect defines four such scope values that expand to 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

You can define your own scope value to OpenID claim expansions in this configuration file:

/WEB-INF/customClaimsMap.properties

For example, to let the custom https://myidp.com/scopes/org_details scope value request the claims roles, supervisor, employee_number add the following line to the file:

https\://myidp.com/scopes/org_profile=roles,supervisor,employee_number

The mapping can be alternatively set or overridden via a Java system property, by prefixing the scope value with op.claims.map..

For example:

-Dop.claims.map.https\://myidp.com/scopes/org_profile=roles,supervisor,employee_number

The configured mapping will be logged at server startup at INFO level under OP0080:

INFO main MAIN - [OP0080] Custom scope value - OpenID claims map:
INFO main MAIN - [OP0080] https://myidp.com/scopes/org_details=[roles,supervisor,employee_number]

Prefix custom scopes and claim names to prevent clashes

The best practise is to put custom scopes and claims in a name space to prevent collisions with those of other identity providers or departments. This can be done with a common prefix:

  • An URI, such as a URL or URN, for example https://myidp.com/scopes/ or 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 even allow simple queries to check their validity and description (and return HTTP status 404 if the scope value or claim name is invalid).

Escape 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