[Openid-specs-ab] OpenID Connect request object specification

Mike Jones Michael.Jones at microsoft.com
Thu May 12 16:45:53 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 request structure follows.

                                                            -- Mike

The OpenID Request object is used to provide OpenID request parameters that differ from the default ones.  Implementing support for the OpenID Request object is OPTIONAL.  Supporting it is necessary for implementations that need to request or provide sets of claims other than the default UserInfo claim set.

If present, the OpenID Request object is passed as the value of a "req=" OAuth 2.0 parameter and is represented as a JWT.  Parameters that affect the information returned from the UserInfo Endpoint are in the "inf" member.  Parameters that affect the information returned in the OpenID Token are in the "oit" member.

An example an OpenID request object is as follows:

{
  "inf":
    {
      "clm":
        {
          "name": null,
          "displayName": {"opt": true},
          "emails": null,
          "photos": {"opt": true},
        },
      "fmt": "sig"
    }
  "oit":
    {
      "clm":
        {
         "aat": null
        }
      "mxa": 86400
    }
}

The OpenID Request object is a JWT that MAY contain a set of members defined by this specification and MAY contain other members that are not defined by this specification.  The JWT MAY be signed or MAY by unsigned by using the JWT "sig":"none" convention in the header.  The members defined by this specification are:
               "inf" (UserInfo Endpoint request):  Requests affecting the values to be returned from the UserInfo Endpoint.  (OPTIONAL)  If not present, the UserInfo Endpoint behaves in the default manner.
               "oit" (OpenID Token request):  Requests affecting the values to be included in the OpenID Token.  (OPTIONAL)  If not present, the default OpenID Token contents are used.  If present, these parameters are used to request deltas to the default contents of the OpenID Token.

If signed, the OpenID Request object SHOULD contain the standard JWT "iss" and "aud" claims.

The structure of the "inf" (UserInfo Endpoint request) member is a JSON object that MAY contain the following members:
               "clm" (requested claims):  Set of requested claims from the UserInfo Endpoint.  (OPTIONAL)  If not present, the default UserInfo claims held by the IdP are returned.
               "fmt" (format):  The requested format for the UserInfo Endpoint information.  (OPTIONAL)  If not present, the format is an unsigned JSON object.

The "clm" member is a JSON object with a member for each requested claim.  The member names are the requested claim names.  The member values may be either:
               null:  This indicates that this claim is being requested in the default manner.  In particular, this is a required claim.
    or
               A JSON object:  This is used to provide additional information about the claim being requested.  All members of the "clm" object are OPTIONAL.
               The members of the JSON object value following a claim name defined by this specification are:
                              "opt":  If this is an optional claim, this member's value MUST be true, else, if present, its value MUST be false, which indicates that it is a required claim.
               Other members MAY be defined to provide additional information about the requested claim.
If the "clm" member is present in the "info" object, the claims requested within it override the default claim set that would otherwise be returned from the UserInfo Endpoint.

The "fmt" member of the "inf" object is used to specify the requested format of the UserInfo Endpoint contents.  Values defined are:
               "nor" (normal) - in which case the contents are an unsigned JSON object
               "sig" (signed) - in which case the contents are a signed JWT
               "enc" (encrypted) - in which case the contents are an encrypted and signed JWT

All members of the "inf" object are OPTIONAL.  Other members MAY be present and if so, SHOULD understood by both parties.

The structure and function of the "oit" (OpenID Token request) member of the OpenID Request object is similar to that of the "inf" member.  It also contains an optional "clm" member, with the same structure as that for the "oit" member.  If the "clm" member is present in the "oit" object, the claims requested within it modify the default claim set that would otherwise be returned in the OpenID Token.  Unlike for the "inf" member, typically these claims will augment, rather than override the default set.

This claim MAY be requested in the OpenID Token by specifying it in the "clm" member:
               "aat" (authenticated at):  Requests that the "aat" claim be present.  The claim value is the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time that the user authentication occurred.  (The "aat" claim semantically corresponds to the openid.pape.auth_time response parameter.)

In addition to the "clm" member, this additional member is defined within the "oit" member of the OpenID Request object:
               "mxa" (max authentication age):  (OPTIONAL)  If the request parameter "mxa" is present, it specifies that the user must be actively authenticated if any present authentication is older than the specified number of seconds.  (The "mxa" request parameter corresponds to the OpenID 2.0 openid.pape.max_auth_age request parameter.)

It is anticipated that additional "oit" parameters MAY be defined to request that additional properties hold for the authentication - for instance, that certain authentication policies be applied (in the same spirit of the OpenID 2.0 openid.pape.auth_policies values), or that the authentication conform to the policies defined by a specified trust framework.  These parameters MAY be defined by extension specifications.

All members of the "oit" object are OPTIONAL.  Other members MAY be present and if so, SHOULD understood by both parties.

All members of the OpenID Request object are OPTIONAL.  Other members MAY be present and if so, SHOULD be understood by both parties.

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


More information about the Openid-specs-ab mailing list