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:

• verification sub-element: contains details on the procedure used to verify an individual’s identity and associate that specific identity data with a user account. Read more

• claims sub-element: contains the claims about the end-user which were verified by the process and according to the policies determined by the corresponding verification element. 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.

1. End user accesses a software application.

2. The client application requests authorization from the authorization server.

   The request contains a JSON-formatted claims parameter used to request a list of claims – data about the user the applicattion needs to have.

   Example claims parameter 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}
            }
         }
      }
   }
   

3. The authorization server redirects the user to the consent screen.

4. The user reviews the requested scopes and claims and approves client’s application access.

   After consent, the user is redirected back to the application.

5. The authorization server issues the authorization code and provides it to the client in the request response.

6. The application sends a request to the authorization server’s /token endpoint requesting an ID token.

7. The authorization server verifies the request

8. 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:

1. Obtain an access token with the openid scope 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.

2. Call the UserInfo API including the claims parameter with the requested verified claims.

   Example claims value:

   {
      "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"
    }
  }
}