[Openid-specs-ab] OpenID Connect response objects specification

Mike Jones Michael.Jones at microsoft.com
Thu May 12 16:46:16 UTC 2011


As promised, Nat, John, and I spent time at the European Identity Conference (EIC) in Munich turning the decisions made at IIW into actual specification language.  The write-up for the OpenID Connect response objects structures follows.

                                                            -- Mike

OpenID Connect uses two kinds of responses:  The OpenID Token, which is returned directly, and the UserInfo Endpoint values, which are retrieved from the UserInfo Endpoint API.

The OpenID Token is a JWT, containing information about the identity of the user, session information, and information about the authentication that occurred.  The UserInfo Endpoint value is a set of claims about the user.

In the default case, the UserInfo Endpoint claims are returned in the response body as a bare JSON object.  All implementations MUST implement this functionality.

Claims MAY also be returned as a JWT, which enables them to be signed and/or encrypted.  In this case, the JWT (which utilizes a base64url encoded representation) is returned in the message body.  The two cases can be easily distinguished since in the default case, the first character of the response will always be "{", whereas when a JWT is returned, the first character will always be one of the 64 base64url encoding characters.  Implementing support for the UserInfo Endpoint returning claims in a JWT is OPTIONAL.

An example claims object returned from the UserInfo Endpoint is as follows:

{
  "name": {"givenName": "Jane", "familyName": "Doe"}
  "displayName": "Jane Doe",
  "emails": [{"value": "janedoe at example.com<mailto:janedoe at example.com>", "primary": true, "verified": true}],
  "photos": [{"value": "https://example.com/profiles/janedoe/photo.jpg", "type": "photo"},
               {"value": "https://example.com/profiles/janedoe/thumb.jpg", "type": "thumbnail"}]
}

Claims can be represented in one of three forms:
  - Normal claims:  Claims directly asserted by the IdP
  - Aggregated claims:  Claims asserted by a claims provider other than the IdP that are returned by the IdP
  - Distributed claims:  Claims asserted by a claims provider other than the IdP, where the IdP returns references enabling them to be retrieved

Support for the normal claims representation is REQUIRED.  Support for aggregated and distributed claims is OPTIONAL.

Normal claims are represented as members of the claims object, with the claim name being the member name, and the claim value being the member value.  The claims in the example above are all normal claims.

Both aggregated claims and distributed claims are represented using two distinguished members within the claims object.  These members are:
  "_claim_names":  A JSON object whose member names are additional claim names for either aggregated or distributed claims and whose values specify claim sources from which the claim values can be retrieved.  These values are indexes into the "_claim_sources" member.
  "_claim_sources":  A JSON object whose member names are referenced from the "_claim_names" member values, and whose values either contain sets of aggregated claims or reference locations from which sets of distributed claims can be retrieved.

An example using these members is as follows:

{
  "name": {"givenName": "Jane", "familyName": "Doe"}
  "displayName": "Jane Doe",
  "_claim_names":
    {
      "birthday": "src1",
      "eyeColor": "src1",
     "paymentInfo": "src2",
     "shippingAddress": "src2",
      "creditScore": "src3"
    }
  "_claim_sources":
    {
      "src1": {"JWT": "JWT_hdr.JWT_claims.JWT_crypto"},
      "src2": {"endpoint": "https://merchant.example.com/claimsource"}
      "src3": {"endpoint": "https://creditagency.example.com/claimshere", "access_token": "string"}
   }
}

In this example, the "name" and "displayName" claims are directly asserted by the IdP, the "birthday" and "eyeColor" come from a JWT containing these aggregated claims (perhaps from a department of motor vehicles), the "paymentInfo" and "shippingAddress" claims can be retrieved from the named merchant (which may require user authentication at retrieval time), and the "creditScore" claim can be retrieved from the named credit agency using the provided access token.

The "_claim_sources" member values are JSON objects with one of two formats:

1.  For aggregated claims, a "_claim_sources" value is a JSON object with these members:
               "JWT": "JWT value" (REQUIRED) - MUST contain the claims to be retrieved from that claim source, as listed in the associated "_claim_names" list
               Other members MAY be present, if understood by both parties

2.  For distributed claims, a "_claim_sources" value is a JSON object with these members:
               "endpoint": "Endpoint URL value" (REQUIRED) - MUST be a source of the claims to be retrieved from that claim source, as listed in the associated "_claim_names" list.  This URL is for an OAuth 2.0 resource endpoint.  The claims MUST be returned as a JWT.
               "access_token": "OAUTH2 access token" (OPTIONAL) - Access token enabling retrieval of the claims from the URL by using the OAuth 2.0 BEARER scheme.  Claims SHOULD be requested using the Authorization request header field and claims sources MUST support this method.
               Other members MAY be present, if understood by both parties

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-ab/attachments/20110512/011b5f24/attachment-0001.html>


More information about the Openid-specs-ab mailing list