OIDC Identity Assurance Explained
Learn how client applications (relying parties) can get verified claims about end users.
What Identity Assurance Is
OpenID Connect for Identity Assurance 1.0 builds upon the OpenID Connect Core specification. It outlines how relying parties (client apps) can obtain verified identity data regarding the end user.
The Identity Assurance extension caters to scenarios that require rigorous validation of user data, such as in eHealth or eFinancial settings. To achieve that, the specification defines a technical mechanism enabling client applications to request a minimal data set it needs in a form of verified claims and identity providers/authorization servers to provide the applications with such data.
Verified Claims Explained
Verified claims are used to provide the relying parties with verified data about the end user. Technically, it is a JSON container element added to the JSON-based assertion. See example:
{
"verified_claims": {
"verification": {
"trust_framework": "eidas",
"assurance_level": "substantial",
"evidence": [
{
"type": "document",
"method": "pipp",
"time": "2012-04-22T11:30Z",
"document_details": {
"type": "idcard",
"issuer": {
"name": "Paris",
"country": "FRA"
},
"document_number": "53554554",
"date_of_issuance": "2010-03-23",
"date_of_expiry": "2020-03-22"
},
}
]
},
"claims": {
"given_name": "Jean",
"family_name": "Paul",
"nationalities": [
"FRA"
]
}
}
}You can see that verified_claims is a single Object (or an array of objects), where each object is constructed with:
verificationsub-element: contains details on the procedure used to verify an individual's identity and associate that specific identity data with a user account. Read moreclaimssub-element: contains the claims about the end-user which were verified by the process and according to the policies determined by the correspondingverificationelement. Read more
In the example JSON above, you can see that the client application would receive information about Jean Paul, a citizen of France, whose data was verified using the eIDAS trust framework and Jean Paul's ID document.
How Identity Assurance Works
Verified claims are delivered to client applications by adding them to the OpenID Connect UserInfo API response or by including them as a part of the ID token.
ID Tokens with Verified Claims
The below diagram and section describes how verified claims are requested to be included in an ID token using the OAuth Authorization Code Flow, but the OIDC's Hybrid Flow can also be used.
End user accesses a software application.
The client application requests authorization from the authorization server.
The request contains a JSON-formatted
claimsparameter used to request a list of claims -- data about the user the applicattion needs to have.Example
claimsparameter value:{ "id_token": { "email": null, "preferred_username": null, "picture": null, "verified_claims": { "verification": { "trust_framework": null, "time": null, "verification_process": null, "evidence": [ { "type": { "value": "document" }, "method": null, "time": null, "document_details": { "type": null, "issuer": { "name": null, "country": null }, "document_number": null, "date_of_issuance": null, "date_of_expiry": null } } ] }, "claims": { "given_name": {"essential": true}, "family_name": {"essential": true}, "birthdate": {"essential": true} } } } }The authorization server redirects the user to the consent screen.
The user reviews the requested scopes and claims and approves client's application access.
After consent, the user is redirected back to the application.
The authorization server issues the authorization code and provides it to the client in the request response.
The application sends a request to the authorization server's /token endpoint requesting an ID token.
The authorization server verifies the request
The authorization server issues an ID token and an access token.
Example ID Token with
verified_claims:{ "iss": "https://server.example.com", "sub": "24400320", "aud": "s6BhdRkqt3", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970, "auth_time": 1311280969, "acr": "urn:mace:incommon:iap:silver", "email": "jeanpaul@example.com", "preferred_username": "j.paul", "picture": "http://example.com/jeanpaul/me.jpg", "verified_claims": { "verification": { "trust_framework": "eidas", "assurance_level": "substantial", "evidence": [ { "type": "document", "method": "pipp", "time": "2012-04-22T11:30Z", "document_details": { "type": "idcard", "issuer": { "name": "Paris", "country": "FRA" }, "document_number": "53554554", "date_of_issuance": "2010-03-23", "date_of_expiry": "2020-03-22" }, } ] }, "claims": { "given_name": "Jean", "family_name": "Paul", "birthdate": "1990-03-15" } } }
Requesting Verified Claims to UserInfo Endpoint
OIDC's UserInfo endpoint is where client applications can send a request to retrieve claims about the authenticated end user. These claims might include details such as the user's name, email, profile picture, and more.
The Identity Assurance specification makes it possible for client applications to request verified claims while calling the UserInfo API. To do so, the client application must:
Obtain an access token with the
openidscope from the authorization server.How the application obtains the access token is not relevant to the Identity Assurance process -- it can be done as a part of the authorization code flow, hybrid flow, or different.
Call the UserInfo API including the
claimsparameter with the requested verified claims.Example
claimsvalue:{ "userinfo": { "verified_claims": { "verification": { "trust_framework": null }, "claims": { "given_name": null, "family_name": null, "birthdate": null } } } }When the authorization server receives a request to the UserInfo API with claims requested, it includes the requested verified claims in the request response as well.
Example response with verified claims:
{ "sub": "248289761001", "email": "j.paul@example.com", "email_verified": true, "verified_claims": { "verification": { "trust_framework": "eidas" }, "claims": { "given_name": "Jean", "family_name": "Paul", "birthdate": "1990-03-15" } } }