OpenID Artifact Binding 1.0 - Draft13

Abstract

OpenID Authentication 2.0 defines the method to move Authentication and associated extension requests among the User, Relying Party, and the OpenID provider through HTTP POST or GET, i.e., it defines the POST and GET binding for OpenID messaging. This specification defines the Artifact Binding that sends the OpenID message directly from the Relying Party to the OpenID Provider and passes only a small reference data called Artifact through the browser so that large payload can be moved between the Relying Party and the OpenID Provider without hitting the browser URL and HTTP header size limitation. It also has value that it is more secure. In addition, by requiring HTTPS for the direct communication, it removed the requirement for symmetric signature on the assertion as well as the DIffie-Hellman association that are required in OpenID Authentication 2.0 (POST/GET binding) making it dramatically simpler to implement. As higher security options, it introduces asymmetric signature and a variable to hold public key of the user so that it can also be used to send holder-of-key assertion. It also optionally encrypts the assertion for end-to-end security which is not always granted by SSL. If the relying party desires, it may also request other type of assertion.

Table of Contents

1.  Requirements Notation and Conventions
2.  Terminology
3.  Protocol Overview
4.  Parameters
5.  Data Formats
    5.1.  OpenID JSON Encoding
    5.2.  Request File
    5.3.  Positive Assertion
    5.4.  Signed Format
    5.5.  Encryption
6.  Communication Types
7.  Common Processing
    7.1.  Initiation
    7.2.  Normalization
    7.3.  Discovery
    7.4.  Association
8.  Protocol Flows
    8.1.  RP prepares an Request File
    8.2.  RP Obtains the URL of the Request File
    8.3.  RP sends a request to OP via redirect
    8.4.  OP Sends the user back to the RP
    8.5.  RP requests Assertion directly to the OP
    8.6.  RP receives Assertion in the response body
    8.7.  Verifying Assertion
    8.8.  Signed Assertion
    8.9.  Encrypted Assertion
    8.10.  Holder of Key
    8.11.  Other assertion types
9.  Extensions
10.  Security Considerations
    10.1.  Assertion manufacture/modification
    10.2.  Assertion disclosure
    10.3.  Assertion repudiation
    10.4.  Assertion redirect
    10.5.  Assertion reuse
    10.6.  Secondary authenticator manufacture
    10.7.  Secondary authenticator capture
    10.8.  Assertion substitution
    10.9.  Authentication Request Disclosure
    10.10.  Timing Attack
    10.11.  Authentication Process Threats
11.  IANA Considerations
    11.1.  OAuth Parameters Regitry
Appendix A.  Acknowledgements
12.  Normative References
§  Author's Address

1.  Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) .

Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value.

2.  Terminology

In addition to the terminology used in [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) , following terms are used.

Artifact

An Artifact is a small text associated with the larger payload that identifies the payload.

client identifier

An unique identifier that the client to identify itself to the authorization server.

client secret

A shared secret established between the authorization server and client.

end-user endpoint

The authorization server's HTTP endpoint capable of authenticating the end-user and obtaining authorization.

token endpoint

The authorization server's HTTP endpoint capable of issuing tokens.

OP Endpoints

end-user endpoint and token endpoint.

client registration endpoint

The authorization server's HTTP endpoint capable of issuing client identifiers and optional client secrets.

request registration endpoint

The authorization server's HTTP endpoint capable of registering the request file and return request_url.

user info endpoint

A protected resource that when presented with a token by the client returns authorized information about the current user.

3.  Protocol Overview

1. The Relying Party (RP) learns the OpenID Provider Endpoints (OP Endpoints) either out-of-band or through the discovery process defined elsewhere such as [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) . Exact mechanism for the discovery is out of scope of this specification.
2. The relying party prepares a file that contains all the request parameters and registered at a 'request_url'. OP may provide the service that allows the RP to register the file and obtain a OP accessible 'request_url' for the request. If the RP is not registered with the OP by then, the RP may register with the OP and obtain 'client_secret'.
3. The Relying Party redirects the end user's User-Agent to the end-user endpoint with the 'request_url' to obtain the end-user authorization.
4. The OP establishes whether the end user is authorized to perform OpenID Authentication and wishes to do so. The manner in which the end user authenticates to their OP and any policies surrounding such authentication is out of scope for this document.
5. The OP redirects the end user's User-Agent back to the RP with 'code' which stands for an Artifact of the Assertion.
6. The RP requests the assertion from the token endpoint through direct communication (Direct Assertion Request and Response) through HTTP POST.
7. The Relying Party verifies the information received from the OP. If the assertion is signed, the signature MUST be checked first. If the verified claimed_id belongs to the OP's domain, the assertion is deemed valid. Otherwise, a discovery MUST be performed at the 'claimed_id' to make sure that the OP really is delegated authoritatively.

Note that this specification does not use [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) type signature. The message integrity that [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) provides are provided by the TLS/SSL. Thus, in the most basic case, the assertion does not have to be signed at all. On the other hand, the messages MAY be signed using the OP's signing key that supports non-repudiation to mitigate the assertion-repudiation attack.

4.  Parameters

Followings are parameters used in this specification. Most of them are specific to a particular profile and optional.

• ns

  Value: "http://openid.net/specs/ab/1.0". Discovery of the Artifact Binding service is achieved via the mechanism described in [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.). This namespace SHOULD be listed as an <xrd:Type> child element of the <xrd:Service> element in the XRDS discovery document.

• type

  Value: The URI that expresses the class of the JSON message.

• id

  Value: Value of type xs:string that identifies the instance of the JSON message.

• mode

  Signifies the mode of this request / response.

  Value: "direct_assertion_req" / "direct_req" / "id_res" / "art_req" / "art_res" / "client_associate" / "req_reg" / "req_reg_res"

• request_url

  Value: (OPTIONAL) URL [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) of the Request File. Optionally, one can put the SHA256 [FIPS180‑2] (U.S. Department of Commerce and National Institute of Standards and Technology, “Secure Hash Signature Standard,” .)hash of the file after "#". "#" MUST be escaped.

• code

  Value: A unique short string less than 400 characters, also known as "Artifact".

• op_endpoint

  Value: The OP Endpoint URL.

• claimed_id

  Value: An URI that corresponds to the user in question. The value in the request is either user supplied identifier or the string "http://specs.openid.net/auth/2.0/identifier_select" which tells the OP to chose the identifier that belongs to the user.

  Type: A String of type xs:AnyURI.

• identity

  Value: The OP-Local Identifier, an identifier that corresponds to the user's Local Identifier at the OP. If a different OP-Local Identifier is not specified, the claimed identifier MUST be used as the value for identity.

• user_id

  Value: A unique HTTPS URI of the currently signed in user, from which one may obtain profile data.

• redirect_uri

  Value: URL to which the OP SHOULD return the User-Agent with the response indicating the status of the art_res.

  If this value is not sent in the request it signifies that the Relying Party does not wish for the end user to be returned. It used to be "return_to" in the OpenID 2.0. "return_to" MUST NOT be used.

• client_id

  Value: A unique identifier issued to the client to identify itself. It MUST be the domain name of the RP or the URL assigned by the party that the OP trusts. It SHOULD be the URL from which the metadata about this entity can be obtained.

• server_id

  Value: A unique identifier that identifies the OP. It SHOULD be the URL that the metadata about this entity can be obtained.

• client_secret

  Value: A token of type xs:String that can be used by the OP to identify and authenticate the RP.

• immediate

  Value: (OPTIONAL) "true" or "false". If set to "true", the authorization server MUST NOT prompt the end-user to process the request. If the OP does not support an immediate check or if it is unable to establish the end-user's identity or approval status, it MUST deny the request without prompting the end-user. Defaults to "false" if omitted. It overrides what was expressed in the request file.

• pubkey

  Value: Base 64 Encoding [RFC3548] (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” July 2003.) with URL and Filename Safe Alphabet (Base64url) encoded DER format X.509 Certificate without private key. (RFC1421 (Linn, J., “Privacy Enhancement for Internet Electronic Mail: Part I: Message Encryption and Authentication Procedures,” February 1993.) [RFC1421] - RFC1424 (Kaliski, B., “Privacy Enhancement for Internet Electronic Mail: Part IV: Key Certification and Related Services,” February 1993.) [RFC1424]) Format.

• certs_url

  Value: A URL from which one can retrieve PEM format X.509 certificate. One may add the sha256 hash of the content as a fragment to signify if the file has changed.

• certs_url_alt

  Value: Alternative 'certs_url'. If it is specified, this URL SHOULD be checked in the event of certs_url failing.

• state

  Value: (OPTIONAL) An opaque value used by the RP to maintain state between the request and callback. The OP includes this value when redirecting the user-agent back to the client.

• code

  Value: The Artifact value corresponding to the Assertion is created. The Artifact value MUST include the string constructed from a cryptographically strong random or pseudorandom number sequence RFC1750 (Eastlake, D., Crocker, S., and J. Schiller, “Randomness Recommendations for Security,” December 1994.) [RFC1750] generated by the OP.

  If the Request File (Request File) was invalid, it MUST be a string "INVALID".

• atype

  Value: Type of assertion to be returned at the end. Values are one of the following:

  • openid2json : (Default) OpenID Artifact Binding's default assertion format, which is JSON.
  • openid2jsonp : openid2json wrapped in "openidjsonp();" so that it will be a JSONP format.
  • openid2json-enc: openid2json assertion encrypted.
  • saml2: SAML ver.2 assertion.
  • wss : WS-Security assertion.

• proofkey

  Value: X.509 public key certificate presented by the user to the OP during authentication.

In addition, following OAuth 2.0 parameters are defined and MAY be used in the Assertion.

• grant_type

  Value: The access grant type included in the request. Value MUST be one of "authorization_code", "password", "assertion", "refresh_token", or "none".

• access_token

  Value: The access token issued by the OP.

• access_token_secret

  Value: The corresponding access token secret as requested by the client.

• issued_at

  Value: A unix timestamp of when this signature was created.

• expires_in

  Value: The duration in seconds of the access token lifetime.

• refresh_token

  Value: The refresh token used to obtain new access tokens using the same end user access grant as described in Section 4.

5.  Data Formats

5.1.  OpenID JSON Encoding

Key-Value form encoding is a special file format defined in defined in [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) section 4. It is used as a direct response in this specification. It SHOULD only contain the OpenID parameters. OpenID JSON Encoding is the embodiment of Key-Value form encoding parameters in JSON. The parameters are serialized into a JSON object as a sequence of name/value pairs. The JSON object is represented as the value of the "openid" name.

Following is a non-normative example.

{
    "openid": {
        "type": "http://openid.net/specs/ab/1.0#req",
        "mode": "direct_req",
        "redirect_uri": "https://example.com/rp/endpoint_url"
    }
}

5.2.  Request File

Request File is a UTF-8[RFC3629] (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] format file that captures the parameters that the RP would like to send to the OP to obtain an artifact.

Following is the list of OpenID variables to be sent:

• type - "http://openid.net/specs/ab/1.0#req"
• immediate - (OPTIONAL) "True" or "False". Default is "False".
• claimed_id - (OPTIONAL) The claimed_id as in OpenID 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0]
• identity - (OPTIONAL) The local id as in OpenID 2.0.
• server_id - (OPTIONAL) The intended recipient of this request.
• pubkey - (OPTIONAL) The base64url encoded DER format X.509 certificate of the RP.

Note that these are to be serialized into JSON and then represented as a value of the key "openid".

Following is the list of OAuth 2.0 variables to be sent:

• grant_type - value: "authorization_code".
• client_id - The client identifier recognized by the authorization server.
• redirect_uri - The absolute URI to which the OP asks the User-Agent to come back with an artifact ("code").

Any other extension and other variables can be included.

Following is a non-normative example.

{
  "openid": {
    "type": "http://openid.net/specs/ab/1.0#req",
    "server_id": "http://example.com/op/",
    "immediate": "true",
    "claimed_id":"http://specs.openid.net/auth/2.0/identifier_select",
    "identity": "http://specs.openid.net/auth/2.0/identifier_select",
    "ns.ax": "http://openid.net/srv/ax/1.0",
    "ax.mode": "fetch_request",
    "ax.type.fname": "http://example.com/schema/fullname",
    "ax.type.gender": "http://example.com/schema/gender",
    "ax.required": "fname,gender"
  },
  "redirect_uri": "https://example.com/rp/endpoint_url",
  "grant_type":"authorization_code",
  "cliend_id": "http://example.com/rp/"
}

5.3.  Positive Assertion

Positive Assertion is a set of data that an OP sends out to the RP on successful Authentication. The default format is the Section 5.1 (OpenID JSON Encoding) .

Following is the list of variables to be included:

• type - "http://openid.net/specs/ab/1.0#id_res"
• mode - "id_res"
• op_endpoint - OP Endpoint URL from which this assertion was returned.
• cilent_id - The RP's unique identifier.
• server_id - The Server's unique identifier
• claimed_id - The verified identifier of this user.
• identity - The Local ID that this user was verified against.
• user_id - (OPTIONAL) A unique HTTPS URI of the currently signed in user.
• issued_at - A unix timestamp of when this signature was created.

Any other extension and other variables can be included.

Following is a non-normative example.

{
  "openid": {
    "type": "http://openid.net/specs/ab/1.0#id_res",
    "mode": "id_res",
    "op_endpoint": "https://op.example.com/op_endpoint",
    "client_id": "http://rp.example.com/",
    "server_id": "http://op.example.com/",
    "claimed_id": "https://example.com/alice#1234",
    "identity": "alice",
    "issued_at": 1274889460,
    "ax.mode": "fetch_response",
    "ax.type.fname": "http://example.com/schema/fullname",
    "ax.fanme.value": "John Doe",
    "ax.type.gender": "http://example.com/schema/gender",
    "ax.gender.value": "M",
    "ax.required": "fname,gender"
  }
}

5.4.  Signed Format

Artifact Binding does not use symmetric signature as it adds no value over the mandatory TLS connection to the OP.

To mitigate assertion repudiation attack, the assertion may be digitally signed by the OP using a key that supports non-repudiation as in [magic_signatures] (Panzer, J. and B. Laurie, “Magic Signatures,” February 2010.) where parameters are as follows.

"data_type":"application/json"

"encoding":"base64url"

"alg":"RSA-SHA256"

"data":base64url encoded JSON representation of the assertion.

This specification defines following additional parameters.

• certs_url

  Value: A URL from which one can retrieve PEM format X.509 certificate that has a key that supports non-repudiation. It is used as the replacement of "keyhash". The file may contain certificates chain. 'certs_url_alt' MAY also be specified in conjunction with this parameter.

• type

  Value: A URL that signifies the type of this file. "http://openid.net/specs/ab/1.0#signed_format"

Following is the non-normative illustration of a signed response. (Note: Line wraps in the values are only for the display purpose. New lines MUST be escaped in JSON values.)

{
  "type": "http://openid.net/specs/ab/1.0#signed_format",
  "data_type": "application/json",
  "encoding": "base64url",
  "alg": "RSA-SHA256",
  "data": "base64url encoded data without padding",
  "sigs": [
    {
      "value": "EvGSD2vi8qYcveHnb-rrlok07qn...63iJzeGLKfyHg8ZomQ",
      "certs_url": "https://rp.example.com/certs.pem"
    }
  ]
}

5.5.  Encryption

In the response, the payload may be encrypted by RP's public key for additional security. If it is encrypted, the data is formatted as JSON Encryption Envelope (Bradeley, J. and N. Sakimura, “JSON Encryption Envelope,” February 2010.) [json_enc]. The following parameter MUST be set as follows:

• data_type - "http://openid.net/specs/ab/1.0#openid2json-enc"

Following is a non-normative example of encrypted payload.

{
    "type":"http://jsonenc.info/json-encryption/1.0/",
    "data_type":"http://openid.net/specs/ab/1.0#openid2json-enc",
    "enc_data":"b5guwzFgvrIUd7XcXI0bAFrg-....O69VKhY",
    "enc_type_asy":"http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p",
    "enc_type":"http://www.w3.org/2001/04/xmlenc#aes256-cbc",
    "enc_key":"mHM2ongmZlPVexe....2lsBNdw",
    "enc_iv":"_b4INfYIRwLPZdxB2L7wJg",
    "enc_ref":"https://rp.example.com/rpf_ax.json",
    "enc_thumbprint":"511e7a9cfe5eda16fa70f553c2dfa3c473e06423"
}

6.  Communication Types

Communication Types are the same as in [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) section 5 apart from the fact that we call "indirect" in the above as "redirect" to avoid confusion in the terminology used at NIST SP800-63. In addition to those defined, the Artifact Binding uses Direct Communication for sending and receiving authentication message. All Direct Communication MUST be over SSL/TLS encrypted channel.

7.  Common Processing

There are certain processing that are common to all usage patterns, namely, Initiation, Normalization, and Discovery. Steps are as follows:

User->UA: Click Login
UA->RP: Login with identifier
RP->RP: Normalize identifier
RP->OP: Get XRDS
RP->RP: Find OP Endpoint

7.1.  Initiation

Initiation is done as in [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.)

Following is the non-normative explanation of the process.

To initiate OpenID Authentication, the Relying Party SHOULD present the end user with a form that has a field for entering a User-Supplied Identifier.

The form field's "name" attribute SHOULD have the value "openid_identifier", so that User-Agents can automatically determine that this is an OpenID form. Browser extensions or other software that support OpenID Authentication may not detect a Relying Party's support if this attribute is not set appropriately.

7.2.  Normalization

Normalization is done as in [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) Following is a non-normative, simplified explanation of the Normalization process.

1. If the user supplied identifier string starts with "xri://", strip it.
2. If the user supplied identifier string starts with "=", "@", "+", "$", "!", or "(", add https://xri.net/ to the string.
3. If the user supplied identifier string does not start yet with "http://" or "https://", add "http://".
4. If the user supplied identifier starts with http:// or https:// do nothing.

7.3.  Discovery

Discovery is the process where the Relying Party uses the Identifier to look up ("discover") the necessary information for initiating requests, especially the OP Endpoint. When OP Endpoint and other meta-data is known out of band, discovery is unnecessary. Discovery should be performed as in Section 7.3 of OpenID Authentication 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0] .

Optionally, if the RP does not wish to use RSA signature to authenticate itself, RP may obtain the secret dynamically in the following manner.

7.4.  Association

In Artifact Binding, the OP endpoint MUST be HTTPS endpoint. Therefore, the symmetric signature between the servers that were used in OpenID Authentication 2.0 (POST/GET binding) (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0] is unnecessary. Instead, for the RP authentication against the OP, 'client_secret' is used. The 'client_secret' is either the bearer token assigned by the OP or the RSA signature, which will be discussed later.

7.4.1.  Obtaining bearer token 'client_secret'

If the RP opted for the bearer token (note: in this mode, there will be no possibility of non-repudiation of the request), then RP must somehow obtain the secret. This can be achieved in the following manner.

Issue HTTPS "POST" [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.)request to the OP Endpoint with the following REQUIRED parameters:

• type - "push"
• client_name - A human-readable name of the client.
• client_url - The URL of the homepage of the client.
• client_desc - A text description of the client.
• client_icon - OPTIONAL. A URL for an icon for the client.
• redirect_uri - The URL to which the OP should send its response.

The client MAY include additional metadata in the request and the authorization server MAY ignore this additional information.

Following is a non-normative example of such request.

POST /register HTTP/1.1
    Host: server.example.com
    Content-Type: application/json

    {
      type: "push",
      client_name: "Online Photo Gallery",
      client_url:  "http://onlinephotogallery.com",
      client_desc: "Not only uploading, but also editing capabilities!",
      client_icon: "http://onlinephotogallery.com/icon.png",
      redirect_uri: "https://onlinephotogallery.com/client_reg"
    }

If the redirect_uri was not pre-registered out-of-band, then he server should issue the following response parameters in JSON format.

• client_id
• client_secret
• server_id - OPTIONAL. Specifies the URI that represents the server.
• issued_at - OPTIONAL. Specifies the timestamp when the identifier was issued. The timestamp value MUST be a positive integer. The value is expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
• expires_in - OPTIONAL; if supplied, the issued_at parameter is REQUIRED. Specifies the valid lifetime, in seconds, of the identifier. The value is represented in base 10 ASCII.

The parameters are included in the entity body of the HTTP response using the "application/json" media type as defined by JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627]. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings.

The authorization server MUST include the HTTP Cache-Control response header field with a value of no-store in any response containing client_secret.

Following is a non-normative example of such response.

    HTTP/1.1 200 OK
    Content-Type: application/json
    Cache-Control: no-store

    {
      client_id: "5UO9XcL4TQTa",
      client_secret: ”WdRKN3zeTc20�?    }

If the request for registration is invalid or unauthorized, the authorization server constructs the response by adding the following parameters to the entity body of the HTTP response with a 400 status code (Bad Request) using the “application/json” media type:

• error
• description - OPTIONAL.

Following is a non-normative example of such response.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    Cache-Control: no-store

    {
    "error": "unauthorized_client",
    "description": "This client is not on the
      white list of this Authorization Server"
    }

7.4.2.  Exchanging the public key

If the OP desires non-repudiation possibility of the request from the RP through public key cryptography, then it MUST use the RSA signature mode. Unless the OP has the public key by some out-of-band mechanism, the RP MUST send its Public Key as the PEM format X.509 certificate in the Request. It is also strongly advised that the RP to publish its PEM format X.509 certificate at the 'client_id' URL that the RP uses.

If the RP desires non-repudiation possibility of the response from the OP thorugh public key cryptography, then it MUST use the RSA signature mode. Unless the RP has the public key of the OP by some out-of-band mechanism, the OP MUST send its Public Key as the PEM format X.509 certificate in the Response. It is also strongly advised that the OP to publish its PEM format X.509 certificate at the HTTPS URL that 'server_id' URL points to. The OP SHOULD publish its certificate in the XRD or XRDS document as well. The type URL of the certificate is 'http://openid.net/specs/ab/1.0#x509pem'.

8.  Protocol Flows

In this specification, the protocol flow basically follows OAuth2.0 Web Server Flow with a twist that instead of parameters sent as redirect request, the parameters are captured into a file and the URL of the file, 'request_url', is being sent. All steps in the following profiles are preceded by the common processing. The assertion returned may vary in the following five ways depending on the security characteristics that RP wishes to have.

1. Plain Text Assertion.
2. Signed Assertion.
3. Signed and Encrypted Assertion.
4. Holder of Key
5. Other Assertion Types

8.1.  RP prepares an Request File

The RP prepares a static file with a globally reachable URL. Optionally, it may contain other extension parameters. It MAY be signed as well as in Section 5.4 (Signed Format)

8.2.  RP Obtains the URL of the Request File

RP then records the Request File either locally or remotely and obtains the URL, "request_url". The URL MUST be accessible from the OP.

Optionally, an OP may provide the Request File registration service at the request registration endpoint. This is especially useful for the cases such as the RP is behind the firewall or lives on a client device that cannot be accessed from the OP.

When an OP provides the Request File registration service, it SHOULD publish the registration endpoint in the XRDS where the <Type> is "http://openid.net/specs/ab/1.0#request_regist" or in the XRD where "rel" is "http://openid.net/specs/ab/1.0#request_regist".

To register the Request File, the following parameters are sent as HTTPS POST request to the request registration endpoint as query parameters.

• request - The Base64url encoded JSON request file.
• client_secret - (OPTIONAL) client secret assigned to the RP.

Following is a non-normative example of such request.

POST /rfstore.php HTTP/1.1
Host: op.example.com
Content-Length: 2823
 request=wfjsil2wjf...awQfs_w&client_secret=very_secure_secret

If the request is valid, the OP returns the following variables as the OpenID JSON in the HTTP response body using the “application/json” media type:

• type - "http://openid.net/specs/ab/1.0#req_req_res"
• mode - "req_reg_res"
• request_url - The request URL that corresponds to the request file.

It should be noted that if the Request File includes user's attribute values, it MUST NOT be revealed to anybody but the OP before the user's authentication and authorization. As such, the request_url MUST have larger entropy than the user authentication credential.

Following is a non-normative example of the response.

{
    "type":"http://openid.net/specs/ab/1.0#req_req_res",
    "mode":"req_reg_res",
    "request_url":"http://example.com/op/request_url_wfjdokaosidu"
}

8.3.  RP sends a request to OP via redirect

When the user wishes to access an RP resource, and the user is not yet authorized to do so, the RP sends the user to the OP Endpoint through the HTTP 302 redirect with the following parameters. The entire URL MUST NOT exceed 512 bytes.

• mode - "art_req"
• request_url - The URL of the Request File.
• immediate - (OPTIONAL) "true" or "false". Used to override what was written in the Request File.
• claimed_id - (OPTIONAL) claimed_id MAY be sent as flow parameter to override what is written in the Request File.
• state - (OPTIONAL) An opaque value used by the RP to maintain state between the request and callback. If provided, the OP MUST include this value when redirecting the user-agent back to the RP.

Following is a non-normative example. Note: Line wraps are for display purpose only.

HTTP/1.1 302 Found
Location: https://rp.example.com/rp.php?mode=art_req
&request_url=https://rp.example.com/rf.js%23Qfsoe2F

8.4.  OP Sends the user back to the RP

Upon receipt of the Request, the OP MUST send a GET request to the 'request_url' to retrieve the content and parse it to recreate the request parameters. Once this is done, the OP MUST determine that an authorized end user wishes to complete the authentication in the manner described in Section 10 of the [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) . Once it is determined, the OP creates either positive or negative assertion and associated artifact and returns the response to the "redirect_uri" URL specified in Section 5.2 (Request File) with following parameters respectively in the follwing cases:

8.4.1.  End-user Grants Authorization

• mode - "art_res"
• code - The artifact Value.
• state - Set to the exact value received from the RP.

No other parameter SHOULD be returned. The entire URL MUST NOT exceed 512 bytes.

Following is a non-normative example. Line wraps after the second line is for the display purpose only.

HTTP/1.1 302 Found
Location: https://rp.example.com/rp.php?mode=art_res
&code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk

8.4.2.  End-user Denies Authorization or Invalid Request FIle

• mode - "art_res"
• error - "user_denied", if the end-user denied the request. "invalid" if the request file was invalid. "setup_needed" if the user interaction was required.
• request_url - Set to the exact value received from the RP.
• state - Set to the exact value received from the RP.

No other parameter SHOULD be returned. The entire URL MUST NOT exceed 512 bytes.

Following is a non-normative example. Line wraps after the second line is for the display purpose only.

HTTP/1.1 302 Found
Location: https://openid4.us/rp/rp.php?mode=art_res
&error=setup_needed
&request_url=https%3A%2F%2Frp.example.com%2Frpf.json

8.5.  RP requests Assertion directly to the OP

To obtain the assertion, the RP makes a direct request to the OP Endpoint. The RP may authenticate against the OP depending on the level of assurance desired. There are two ways of authentication, namely:

1. Through the use of client_secret
2. Through the use of asymmetric signature

Added benefit of using asymmetric signature, while it is not specified in OAuth 2.0 are as follows:

1. One can achieve the non-repudiation of the request
2. One do not need to have association or dynamic association
3. OP does not need to keep the state on each and every RP

The asymmetric signature based "client_secret" can be created as follows:

1. Apply Magic Signatures to 'code'.
2. Base64url encode the result.

To obtain the assertion, send the following parameters via HTTPS GET:

• mode - "direct_assertion_req"
• grant_type - "authorization_code"
• code - The artifact received
• client_id - The client_id of the RP
• client_secret - (OPTIONAL) If the secret_type is "shared", send the pre-shared secret. If the secret_type is "magic", send the magic signature prepared as above in this section.
• secret_type - (OPTIONAL) "shared" or "magic". Required if "client_secret" was used.

The following is a non-normative example. Line wraps are for display purpose only.

GET /op_endpoint?mode=direct_assertion_req&grant_type=authorization_code
&code=_artifact_received_
&client_id=https%3A%2F%2Frp.example.com%2Frpf.json
&client_secret=1234qwer&secret_type=shared HTTP/1.1
Host: op.example.com

8.6.  RP receives Assertion in the response body

Upon receipt of the Direct Assertion Request, OP MUST return either Positive or Negative Assertion that corresponds to the received Artifact "code".

8.6.1.  Positive Assertion

Positive Assertion can only be returned once for the artifact and contains the following variables.

• type - "http://openid.net/specs/ab/1.0#id_res"
• mode - "id_res"
• server_id - The identifier of the OP.
• pubkey - The OP's X.509 certificate without private key.
• request_url - The exact request_url URL that the OP received from the RP.
• op_endpoint - The OP Endpoint URL.
• claimed_id - The claimed_id that the OP recognizes as linked to the Local ID, "identity".
• identity - The Local ID that was verified by the OP.
• cileint_id - The identifier of the requesting RP that OP recognized.
• user_id - A unique persistent HTTPS URI of the currently signed in user. e.g. "https://op.example.com/a3flsjeow1234"
• issued_at - A unix timestamp of when this signature was created.

Any other variables can be added.

It MUST be formatted in the JSON or JSONP format depending on the atype in the request.

Following is an example of an assertion.

{
    "openid": {
        "type": "http://openid.net/specs/ab/1.0#id_res",
        "mode": "id_res",
        "server_id": "https://op.example.com/",
        "pubkey": "CSqGSIb3DQEBBQ...22WLTnPvcztaqovGW2gaidAyq6",
        "request_url": "https://rp.example.com/rf.js%23Qfsoe2F",
        "op_endpoint": "https://op.example.com/op_endpoint",
        "claimed_id": "https://example.com/alice#1234",
        "identity": "alice",
        "user_id": "https://op.example.com/a3flsjeow1234",
        "issued_at": 1280217103,
        "client_id": "https://rp.example.com/"
    }
}

8.6.2.  Negative Assertion

If the assertion request is invalid or unauthorized, the authorization server constructs the response by adding the following parameter to the entity body of the HTTP response using the "application/json" media type:

• error - REQUIRED. A single error code as described below.
• error_description - OPTIONAL. A human-readable text providing additional information, used to assist in the understanding and resolution of the error occurred.
• error_uri - OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the end-user with additional information about the error.

The error code is as follows:

• invalid_request - The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
• invalid_client - The client identifier provided is invalid, the client failed to authenticate, the client did not include its credentials, provided multiple client credentials, or used unsupported credentials type.
• unauthorized_client - The authenticated client is not authorized to use the access grant type provided.
• invalid_grant - The provided access grant is invalid, expired, or revoked (e.g. invalid assertion, expired authorization token, bad end-user password credentials, or mismatching authorization code and redirection URI).
• unsupported_grant_type - The access grant included - its type or another attribute - is not supported by the authorization server.
• invalid_scope - The requested scope is invalid, unknown, malformed, or exceeds the previously granted scope.

8.7.  Verifying Assertion

Upon receipt of the JSON formatted assertion, the RP SHOULD parse it to obtain the openid parameters.

Then, the RP SHOULD perform the verification as follows:

1. Check that OP that it connected was really the intended OP through TLS/SSL server certificate check.
2. Check if "mode" is "id_res".
3. If "claimed_id" was not sent in the request or different than what was sent, perform the discovery on the "claimed_id" in the assertion.
4. Compare "claimed_id", "identity", "op_endpoint", "ns" to the discovered or "out-of-band known" values.

8.8.  Signed Assertion

To mitigate Assertion-repudiation attack, the assertion may be digitally signed by the OP using a key that supports non-repudiation. The RP should check the digital signature to verify that it was issued by a legitimate OP.

In this case, the Assertion will be encoded as described in Section 5.4 (Signed Format) .

Public key of the OP MUST either be published in the XRDS or given to the RP out-of-band or included in the assertion either as 'certs_url' or 'pubkey'.

To publish the public key, one SHOULD specify "http://openid.net/specs/ab/1.0/pk" in the Service/Type of XRDS, and the URL from which the PEM formatted X.509 certificate can be obtained as Service/URL.

If the Assertion is signed, the signature validation MUST be performed before other verifications specified in Section 8.7 (Verifying Assertion)

8.9.  Encrypted Assertion

Further, the signed assertion MAY optionally be encrypted based on the RP's public key of the intended recipient to achieve end-to-end encryption and to increase the assurance level of the information protection in the assertion. This is especially useful when the assertion is passed through a medium where the SSL is terminated one or more times, such as an active client.

To achieve this, in the Request File Section 5.2 (Request File), it MUST contain "enckey", "enctype" in addition.

The assertion will be returned in the format discribed in Encryption Section 5.5 (Encryption) using the received "enckey" and "enctype". Encryption SHOULD be the last process before the OP returning the assertion.

8.10.  Holder of Key

To achieve the highest level of assurance, the assertion MAY optionally include "proofkey" as one of the field, which can be subsequently used at the RP to further authenticate the user.

8.11.  Other assertion types

When RP wishes to obtain other type of assertion than OpenID, it MAY request one by specifying "atype" in the Request File (Request File) or as a request parameter in an Artifact Request.

9.  Extensions

Extensions are as defined in Section 12 of [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) . In addition, this specification adds following list to the disallowed aliases.

request_url, code, ope_endpoint, user_id, redirect_uri, client_id, server_id, client_secret, immediate, pubkey, certs_url, state, code, atype, proofkey, encdata, enckey, enciv, enctype, encref, access_token, access_token_secret, issued_at, expires_in, refresh_token.

10.  Security Considerations

Followings are the list of attack vectors and remedies that were considered for this specification.

For details of the attack vector, see [SP800‑63] (National Institute of Standards and Technology, “NIST SP800-63rev.1: Electronic Authentication Guideline,” .).

10.1.  Assertion manufacture/modification

To mitigate this attack, there are two ways to mitigate it.

1. The assertion may be digitally signed by the OP. The Relying Party SHOULD check the digital signature to verify that it was issued by a legitimate OP.
2. The assertion may be sent over a protected channel such as TLS/SSL. In order to protect the integrity of assertions from malicious attack, the OP MUST be authenticated. In this specification, the assertion is always sent over TLS/SSL protected channel.

10.2.  Assertion disclosure

The Assertion disclosure can be mitigated in the following two ways.

1. Assertion is sent over TLS/SSL protected channel, where RP is authenticated by "client_id" and "client_secret".
2. Signed Assertion is encrypted by the RP's public key.

10.3.  Assertion repudiation

To mitigate this threat, the assertion may be digitally signed by the OP using a key that supports non-repudiation. The RP SHOULD check the digital signature to verify that it was issued by a legitimate OP.

10.4.  Assertion redirect

To mitigate this threat, the assertion includes the identity of the RP for whom it was generated as "client_id". The RP verifies that incoming assertions include its identity as the recipient of the assertion.

10.5.  Assertion reuse

The assertion includes a timestamp and a short lifetime of validity. The Relying Party checks the timestamp and lifetime values to ensure that the assertion is currently valid.

10.6.  Secondary authenticator manufacture

Due to the large entropy requirement of the Artifact ("code") and short life nature of its validity, the success probability of this attack is extremely low.

10.7.  Secondary authenticator capture

Secondary authenticator (="code") is transmitted only through HTTPS, thus it is protected between the OP and the User-Agent, and User-Agent and the RP.

Only the place it can be captured is the User-Agent where the TLS session is terminated, and is possible if the User-Agent is infested by malwares. However, it renders no usefulness as long as the profile in use either RP authentication or assertion encryption.

10.8.  Assertion substitution

Responses to assertion requests is bound to the corresponding requests by message order in HTTP, as both assertions and requests are protected by TLS that can detect and disallow malicious reordering of packets.

10.9.  Authentication Request Disclosure

If the authentication request is POSTed directly through a protected channel, it is not possible to disclose the authentication request.

If the Request File is encrypted by the OP's public key, the authentication request will not be disclosed unless OP's private key gets compromised or the encryption algorithm becomes vulnerable.

10.10.  Timing Attack

Timing attack can be used to reduce the effctive key length of the signature if the time required to return the response in case of signature error and correct signature exists. Care should be taken in the implementation to avoid this attack.

10.11.  Authentication Process Threats

In the category of Authentication Process Threats, following threats exists.

• Online guessing
• Phishing
• Pharming
• Eavesdropping
• Replay
• Session hijack
• Man-in-the-middle

Authentication process per se as described in NIST SP800-63-rev1 is out of scope for this protocol, but care SHOULD be taken to achieve appropriate protection.

11.  IANA Considerations

11.1.  OAuth Parameters Regitry

The following is the parameter registration request for the "scope" parameter as defined in this specification:

Parameter name: openid

Parameter usage location: The end-user authorization endpoint request, the end-user authorization endpoint response, the token endpoint request, the token endpoint response, and the "WWW-Authenticate" header field.

Change controller: IETF

Specification document(s): [[ this document ]]

Related information: None

Appendix A.  Acknowledgements

As a binding of OpenID Authentication, this specification heavily relies on OpenID Authentication 2.0. Please refer to Appendix C of OpenID Authentication 2.0 for the full list of the contributors for OpenID Authentication 2.0.

In addition, the OpenID Community would like to thank the following people for the work they've done in the drafting and editing of this specification.

Breno de Medeiros (breno@gmail.com)

Hideki Nara (hideki.nara@gmail.com)

John Bradley (jbradely@mac.com) <author>

Nat Sakimura (n-sakimura@nri.co.jp) <author/editor>

Ryo Itou (ritou@yahoo-corp.jp)

12. Normative References

Author's Address