Skip to content
Connect2id

Custom scopes for requesting OpenID claims

Client applications can use OpenID Connect to request claims (attributes) about the end-user by including specific OAuth 2.0 scope values in the authentication request.

The Connect2id server supports the standard scope values and lets you define custom scopes that request additional sets of claims.

Standard scopes for claims

OpenID Connect defines four scope values for requesting 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, a JSON object with members formatted, street_address, locality, region, postal_code and country
phone phone_number, phone_number_verified

For example, a client can request the user’s profile claims by including profile alongside the required openid scope value:

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

Configure custom scope mappings

To map a custom scope value to a set of claims, add an entry to:

/WEB-INF/customClaimsMap.properties

Each entry maps a scope value to a comma-separated list of claim names. For example, to let clients request roles, supervisor and employee_number with the scope https://myidp.com/scopes/org_details, add:

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

The backslash before the colon is required by the properties file format. See the note on escaping special characters.

You can also define or override a mapping with a Java system property. Prefix the scope value with op.claims.map.:

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

When passed directly as a JVM -D argument, the colon does not need to be escaped.

The server logs the configured mappings at 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]

Namespace custom scopes and claims to prevent collisions

Use a namespace under your organisation’s control for custom scope values and claim names. This reduces the risk of collisions with names defined by other identity providers or departments.

Common approaches include:

  • URI prefixes, such as https://myidp.com/scopes/ for scopes and https://myidp.com/claims/ for claims, or a URN prefix such as urn:myidp:scope:.
  • Reverse-domain prefixes, similar to Java package names, such as com.myidp.scopes. and com.myidp.claims..

For example, a namespaced claim name could be https://myidp.com/claims/employee_number or com.myidp.claims.employee_number.

If you use URLs as scope values or claim names, you can optionally serve documentation at those URLs to explain their meaning. The URLs serve as identifiers; they do not need to point to an accessible web page or service.

Escape special characters

The custom claims map uses the java.util.Properties file format. In a property key, escape colons (:) and equals signs (=) with a backslash (\) so they are not interpreted as key-value separators. Whitespace also terminates a property key, although OAuth 2.0 scope values cannot contain whitespace.

Colons and equals signs in property values do not need to be escaped. For example, the colon in the scope URL on the left must be escaped, while the colons in the claim URLs on the right can remain unchanged:

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