Handling custom claims with OpenID Connect in WSO2 Identity Server
❔ What are “Claims”
A claim is a piece of information about a particular subject. It can be anything that the subject is owned by or associated with, such as name, group, preferences, etc. Claims are also used in identity propagation which is the replication of authenticated identities, by packaging the claims into one or more tokens. These tokens are then issued by an issuer.
The claim management in WSO2 Identity Server allows you to map a set of attributes from the underlying user store to a set of defined claims. The underlying user store can be either an internal or external JDBC user store, Active Directory or LDAP. Each claim can be uniquely identified within the claim dialect by the Claim URI. Claim URIs are independent of the user store and each claim URI can be mapped into any desired attribute in the user store.
❔ What are “Scopes”
The authorization and token endpoints allow the client to specify the scope of the access request using the “scope” query parameter.
OpenID Connect (OIDC) scopes are used by an application during authentication to specify the access privileges of the user. Each scope returns a set of user claims. The application decides the scopes based on the information it requires. When the user is authorized the claims relevant to the requested scopes are returned in the ID Token and will also be available via the userinfo endpoint.
OIDC requests must contain the openid scope value. Other scope values may also be present. Multiple scope values can be defined in the request by creating a space-delimited, case sensitive list of scope values.
WSO2 Identity Server supports following OIDC scopes out of the box and you can define your own scopes as well.
scope=openid profile email phone address💡 Now you know what are claims and what are scopes. Let’s see how you are going to retrieve a custom claim via an ID token by defining scopes in the request.
I’m using WSO2 Identity Server version 5.8.0 for this demonstration. That is the latest release by the time I’m writing this blog. (Early September 2019 😄 )
➕ Add a custom local claim
- Login to the Management Console of the Identity Server
2. In the Main menu, click Add under Claims.
3. Click Add Local Claim to add a new claim to the https://wso2.org/claims (local) claim dialect.
4. Let’s add a new claim called nationality. Fill the required information in the form and tick Supported by Default check-box to display the attribute on the user profile.
- Claim URI: http://wso2.org/claims/nationality
- Mapped Attributes: You need to map the new claim to an attribute that exists in the user store. Let’s map nationality to the country.
➕ Add a custom oidc claim
- In the Main menu, click Add under Claims.
- Click Add External Claim to add a new claim to external claim dialect.
- From the Dialect URI* drop down menu, select http://wso2.org/oidc/claim dialect.
- Enter the name of the new claim. Let’s add a claim nationality to the OIDC claim dialect too.
- Now, mapped the oidc claim to a local claim. I will map it to the new custom claim that I added previously.
🔍 Check the claims of openid scope
As I have mentioned above, WSO2 IS has openid, profile, email, phone and address claims by default. These scopes are bound to a set of claims. That means when you request a token with one or more of these scopes, the claims bound to the scope are returned.
Follow the below steps to see the claims that are included in each scope.
- In the Manage section of the Main menu, click on List under OIDC Scopes
- Click on Update button in front of each scope, the set of claim will be listed.
These are claims associated with the scopes
address: street_address, addressphone: phone_number_verified, phone_numberopenid: sub, street_address, country, zoneinfo, birthdate, gender, formatted, preferred_username, locale, updated_at, nickname, email, website, email_verified, address, profile, locality, groups, phone_number_verified, given_name, middle_name, picture, upn, name, phone_number, postal_code, region, family_nameprofile: website, zoneinfo, birthdate, gender, profile, preferred_username, given_name, middle_name, locale, picture, updated_at, name, nickname, family_nameemail: email_verified, email
🔧 Configure claims for the ID token
When the OIDC token is sent to the UserInfo endpoint, only the claims which are common in both the openid scope config file and the Service Provider claim configuration will be returned.
To try the scenario, let’s create an OIDC Service Provider with Password Grant Type. You can follow my previous blog for more details on OIDC flow. [1]
⭐️ Configure Service Provider
- Login to the WSO2 IS management console and click Add under Service Providers.
- Provide a name for the Service Provider and click Register.
- Expand Inbound Authentication Configuration.
- Expand OAuth/OpenID Connect Configuration and click on Configure
- Provide the Callback URL . You may unselect the grant types other than Code. Click Add to save the changes.
⭐️ Configure Claims
- Go to the Claim Configuration section of the service provider.
- Click on Add Claim URI for Requested Claims
- Select the required set of local claim URIs and tick the Mandatory Claim check-box.
Note: I selected the custom claim (http://wso2.org/claims/nationality) that is not included in the openid scope to show that it will not be included in the ID token.
👧 Update user profile
All these selected claims should have values in the user profile. Otherwise they will not be retrieved.
Therefore I created a user named “alice” and filled her personal details in the profile. You may refer the WSO2 documentation to see how to configure and update users in WSO2 Identity Server. [2]
✅ Validate the ID token
- Make an access token request to the token endpoint of the server with the scope openid. I’m using the Password grant type to obtain the access token.
Sample Request:
curl -u <client id>:<client secret> -k -d "grant_type=password&username=<username>&password=<password>" -H "Content-Type:application/x-www-form-urlencoded" https://localhost:9443/oauth2/token?scope=openidOnce the request is made, you will get the access toke, refresh token and the ID token. Here is the payload of the ID token I observed. I used jwt.io to decode my token.
{
"at_hash": "jBr8nEtZy-jlJ955WxC9EA",
"sub": "alice",
"country": "Sri Lanka",
"gender": "female",
"amr": [
"password"
],
"iss": "https://localhost:9443/oauth2/token",
"given_name": "Alice",
"aud": "toVatOcV_fDYOq0cXrIclNFMHBQa",
"nbf": 1568400008,
"azp": "toVatOcV_fDYOq0cXrIclNFMHBQa",
"exp": 1568403608,
"iat": 1568400008,
"email": "alice@gmail.com"
}In the payload, you can see that I have obtained all the claims that I requested other than the Nationality. It was not retrieved since that claim was not there in the list of claims of openid scope.
Let’s see how we can retrieve additional claims.
➕ Add a custom claim to ID token
There are two ways that you can obtain additional claims.
A. Using openid scope
In this method, we will add the new claim to the set of claims of the openid scope.
Steps to add the claim,
- In the Manage section of the Main menu, click on List under OIDC Scopes
- Click on Add Claims button in front of openid scope.
- Click on Add OIDC Claim.
- Select the claim Nationality from the drop-down menu.
B. Using a new scope
Here we will introduce a new scope with the custom claim that we require and add that scope to the token request.
Steps to add new claim,
- In the Manage section of the Main menu, click on Add under OIDC Scopes
- Give a name to the scope. I will give the name “sample”.
- Click on Add OIDC Claim.
- Select the claim Nationality from the drop-down menu.
✅ Validate the token,
Request,
curl -u <client id>:<client secret> -k -d "grant_type=password&username=<username>&password=<password>" -H "Content-Type:application/x-www-form-urlencoded" https://localhost:9443/oauth2/token?scope=openid+sampleID token payload,
{
"at_hash": "9SXsmWudq1QEGP9c96aVjg",
"sub": "alice",
"country": "Sri Lanka",
"gender": "female",
"amr": [
"password"
],
"iss": "https://localhost:9443/oauth2/token",
"given_name": "Alice",
"aud": "toVatOcV_fDYOq0cXrIclNFMHBQa",
"nbf": 1568402101,
"nationality": "Sri Lanka",
"azp": "toVatOcV_fDYOq0cXrIclNFMHBQa",
"exp": 1568405701,
"iat": 1568402101,
"email": "alice@gmail.com"
}📩 Wrap-up
From this blog, I showed you how to retrieve custom claim in an ID token with OpenID connect in WSO2 IS 5.8.0.
In brief, this requires the addition of a local claim, local claim to OIDC claim mapping, modifying the scopes and configuring required claims in the Service Provider. For the sample, I used the Password Grant type for token requests.
Thanks for reading and see you soon with an interesting topic in the IAM domain. 👋
[1]https://medium.com/@pamodaaw/try-out-oidc-authentication-with-wso2-identity-server-c5ed1b9fb3b7
