Claim mapping for a service provider involves mapping claims that are used by the service provider to the claims local to the WSO2 Identity Server. In situations where a service provider needs some information of the user from the Identity Server where the service provider authenticates, the claim mapping is useful. Once the user is authenticated, the service provider can use these received claim details to provide its service. See the Identity Server Architecture for more information on how claim mapping fits in to into the overall scheme of things.
To register a service provider, do the following.
- In the Claim Configuration form, select the claim mapping dialect by either choosing to use a local claim dialect or define your own custom claim dialect.
- If you choose to Use Local Claim Dialect, you need to fill in the following details.
- Fill in your requested claims by clicking the Add Claim URI button.
- Choose your Local Claim from the dropdowndrop-down. Select whether this claim is a Mandatory Claim for the Service Provider using the checkbox.
- If you choose to Define Custom Claim Dialect, you need to do the following.
Add a custom claim URI by clicking on the Add Claim URI button. Clicking this button again enables you to map more claims.
Add the Service Provider Claim and choose the corresponding Local Claim from the dropdowndrop-down. Select whether you want the claim to be a Requested Claim and whether this claim is a Mandatory Claim for the service provider, using the relevant checkboxes.
Warning Expand title Click to view vital information when configuring claims for an OpenID Connect Service Provider
Note: When mapping custom claims for a service provider configured with OpenID Connect, ensure to map the custom claims in the SP configuration as seen in the screenshot above AND also add the custom claims to a scope value in the oidc file.
Info title Why?
This is required because OpenIDConnect claim scopes are supported from WSO2 IS 5.2.0 onwards. This means that when you request for an OIDC token, you can specify a single scope value that is bound to a set of multiple claims. When that OIDC token is sent to the UserInfo endpoint, only the claims which are common in both the OIDC scope config file and the SP claim configuration (i.e., the intersection of claims in both these configurations) will be returned.
To do this,
- Click on Browse under Registry on the Main tab of the management console.
- Navigate to /_system/config/ and click on the oidc file. Expand the Properties section.
- Add the custom claims to the existing default scope openid by clicking on Edit. Alternatively, add a new scope for the custom claims by clicking on Add New Property and send it when getting the OIDC token along with the mandatory openid scope.
Warning Expand title Click to view vital information when configuring claims for an SAML2 Service Provider
Note: When mapping custom claims for a service provider configured with SAML2, ensure to select both "Enable Attribute Profile" and " Include Attributes in the Response Always" from the SAML2 service provider configuration as follows.
Info title Why?
This is required since Identity Server include user claims in the SAML2 response only if SAML2 attribute profile is enabled.
Info title Information on mapping claims
The Local Claim list includes a set of standard claim values which are local to the WSO2 Identity Server. When adding a service provider, it is necessary to map the values of the claims local to the service provider with those provided in this dropdown list which are local to the Identity Server. This should be done for all values in the service provider unless they use the same claim name.
Marking a claim as a Mandatory Claim would ensure that the WSO2 IS Identity Server will definitely send a value for this claim to the service provider. When a user logs into this service provider, if the identity provider does not provide a value for any of the mandatory claims, the user will be prompted to provide them at the time of login as shown in the image below.
Expand title Expand for steps to test out mandatory claims Tip title Testing mandatory claims
To test out mandatory claims,
Configure the travelocity sample application by following the steps in the Configuring Single Sign-On topic.
Configure a few claims and select the checkbox for mandatory claims.
Ensure that there are one or more claims which are missing in the user profile of the user you wish to login with.
Run the travelocity sample and try the SAML login.
- Enter the username and password Log in with the user credentials of the user who has a few mandatory claims missing, and click Submit.
- A claim request will be prompted, similiar similar to the image below. At this point, the mandatory claim rule is enforced and you cannot proceed without providing the necessary the claim values. Provide the necessary claim values and click Submit.
- You will be successfully logged in to the application.
Marking a mapped claim as a Requested Claim would ensure that the service provider definitely sends this claim to the Identity Server. This is useful particularly in cases where there are hundreds of claims and only specific ones need to be sent to the Identity Server.
Select the Subject Claim URI and the Role Claim URI (for custom claims) from the dropdowndrop-down. The claims you mapped are listed in the dropdown drop-down and you can choose among these claims.
- When the authentication request comes into the Identity Server, the value of the claim specified as the Subject Claim URI is added to the authentication request. To expand more, when the user logs into the Identity Server, it identifies the user store that the user belongs to. The value of the claim specified as the Subject Claim URI can be found in this user store. This value corresponding to the claim is sent along with the authentication request.The Role Claim URI is used to identify the claim that equates to the role of the user. This is linked to the permissions that you can apply for specific user rolesdefines the authenticated user identifier which will return with the authentication response to the service provider.
- Role Claim URI defines the role claim for the service provider. This is useful if you use a different claim as the role claim or if you define a custom claim mapping for the service provider.