Blog »

Using OpenID Connect to make assertions about end-users

2014-08-03

OpenID Connect provides an excellent mechanism for issuing assertions, or claims (digitally signed statements) about end-users. Such assertions can for example be the end-user's name, contact details with verification status, organisational role, or reputation scores.

Example claims about an end-user, encoded in a simple JSON object:

{
   "sub"            : "alice",
   "name"           : "Alice Adams",
   "email"          : "[email protected]",
   "email_verified" : true,
   "reputation"     : 1500,
   "location"       : "Wonderland"
   "avatar"         : "http://example.com/alice.jpg"
 }

How claims are communicated in OpenID Connect

An OpenID Connect provider can communicate claims to client applications in two different ways:

  1. ID token
    The ID token is a signed object that asserts the user's identity, issuer and authentication time / strength / methods. The OpenID Connect provider may include additional claims in the ID token, such as geo-location, personal details, organisational roles, etc. The ID token is encoded as a JSON Web Token (JWT) signed by the provider and may optionally be encrypted for confidentiality. The only limitation is that ID tokens should not exceed 2000 characters in length as certain protocol flows (OpenID Connect is based on the OAuth 2.0 framework) return the ID token by means of URL redirection.

  2. OAuth 2.0 access token
    An OpenID Connect provider can also return an OAuth 2.0 bearer access token to let the client application access a UserInfo endpoint to release consented information about the end-user. That information is also represented as a JSON object and can be much larger in size as it doesn't suffer the ID token's limitation. In contrast to the ID token, the access token may also allow access to the UserInfo when the end-user is offline, by extending the access token's lifetime or by providing the client application with a refresh token.

Example ID token payload (after JWT decoding and signature verification):

{
  "iss"       : "https://openid.wonderland.net",
  "sub"       : "alice",
  "aud"       : "s6BhdRkqt3",
  "nonce"     : "n-0S6_WzA2Mj",
  "exp"       : 1311281970,
  "iat"       : 1311280970,
  "auth_time" : 1311280969,
  "acr"       : "urn:acr:2fa",
  "name"      : "Alice Adams",
  "email"     : "[email protected]",
  "roles"     : [ "admin", "audit" ]
}

Building a business model on premium claims

The Connect2id server can easily support business models where money is charged for providing claims of value about end-users to interested client applications. The server can handle multiple tiers of client applications, e.g. a fremium tier that can only receive basic assertions about the end-user and a premium tier with access to value-added assertions.

Differentiating between fremium and premium application subscriptions is as simple as setting a designated value in the scope field of the client application's registration details stored by the Connect2id server.

Pick your own claims source

The Connect2id server can pull assertions (claims) from any data source, supporting aggregation from multiple sources if required.

Example claims sources:

  • LDAP directories
  • SQL or NoSQL database
  • SCIM web service
  • HR system
  • XML file

We have defined a simple Java SPI for that. An LDAP claims source connector is provided out of the box that should satisfy most enterprises looking to provide assertions about their users to applications.