OpenID Connect Authorization Code Binding 1.0 - draft 02

Abstract

The OpenID Connect Authorization Code Binding 1.0 is a binding of OpenID Connect Core 1.0 to the OAuth 2 Authorization Code flow. It provides the most straightfoward and direct binding of OpenID Connect Core by layering directly on-top of existing and commonly deployed OAuth deployment patterns.

Table of Contents

1.  Requirements Notation and Conventions
2.  Terminology
3.  Protocol Flows
    3.1.  Client prepares an Authorization Request URL
    3.2.  Client sends a request to the Authorization Server
    3.3.  Authorization Server Authenticates the End-User
    3.4.  Authorization Server Obtains the End-User Consent/Authorization
    3.5.  Authorization Server Sends the End-User back to the Client
    3.6.  Client requests Assertion using the "code"
    3.7.  Client receives Assertion in the response body
    3.8.  Accessing Userinfo Endpoint
    3.9.  RP receives UserInfo Response
4.  Security Considerations
    4.1.  Assertion manufacture/modification
    4.2.  Assertion disclosure
    4.3.  Assertion repudiation
    4.4.  Assertion redirect
    4.5.  Assertion reuse
    4.6.  Secondary authenticator manufacture
    4.7.  Secondary authenticator capture
    4.8.  Assertion substitution
    4.9.  Authentication Request Disclosure
    4.10.  Timing Attack
    4.11.  Authentication Process Threats
5.  IANA Considerations
    5.1.  OAuth Parameters Registry
Appendix A.  Acknowledgements
6.  Normative References
§  Authors' Addresses

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

See OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc] for terminology used in this specification.

3.  Protocol Flows

The protocol flow goes through the following steps.

1. Client prepares an Authorization Request using URI query string serialization as defined in OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc] containing the desired request parameters.
2. Client sends a request to the Authorization Server
3. Authorization Server Authenticates the End-User
4. Authorization Server Obtains the End-User Consent/Authorization
5. Authorization Server Sends the End-User back to the Client with an Authorization Code
6. Client requests Assertion using the Authorization Code
7. Client receives Assertion in the response body
8. (OPTIONAL) Client accesses the Userinfo Endpoint
9. (OPTIONAL) Client receives UserInfo Response

Note that in each step, the party that receives message MUST verify it according to the verification rule set in OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc].

3.1.  Client prepares an Authorization Request URL

When the user wishes to access a Protected Resource, and the End-User Authorization has not yet been obtained, the Client prepares an Authorization Request URL using URI query string serialization as defined in OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc].

This binding further constrains the following request parameters

response_type

MUST be set to "code".

The scheme used in the Authorization URL MUST be HTTPS

The following is a non-normative example of an Authorization Request URL. Note that the line wraps within the values are for display purpose only.

https://server.com/op/authorize?
response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&scope=openid
&state=af0ifjsldkj

3.2.  Client sends a request to the Authorization Server

Having contructed the URL, the client sends the End-User to the HTTPS End-User Authorization Endpoint using the URL. This MAY happen via HTTPS redirect, hyperlinking, or any other valid means of directing the User-Agent to the URL.

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

HTTP/1.1 302 Found
Location: https://server.com/op/authorize?
response_type=code
&client_id=s6BhdRkqt3
&state=af0ifjsldkj
&openid.type=http%3A%2F%2Fopenid.net%2Fspecs%2Fcc%2F1.0%2F%23req

3.3.  Authorization Server Authenticates the End-User

The Authorization Server validates the request to ensure all required parameters are present and valid. If the request is valid, the authorization server MUST authenticate the End-User. The way in which the authorization server authenticates the End-User (e.g. username and password login, session cookies) is beyond the scope of this specification.

3.4.  Authorization Server Obtains the End-User Consent/Authorization

Once the user is authenticated, the Authorization Server MUST obtain an authorization decision. This MAY be done by presenting the user with a dialogue that allows the user to recognize what he is consenting to and obtain his consent or by establishing approval via other means ( for example, via previous administrative approval )

3.5.  Authorization Server Sends the End-User back to the Client

Once the authorization is determined, the Authorization Server returns positive or negative response.

3.5.1.  End-user Grants Authorization

If the resource owner grants the access request, the authorization server issues an Authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format:

code

REQUIRED. The Authorization Code.

state

REQUIRED if the "state" parameter in the request. Set to the exact value of the "state" parameter received from the client.

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

The 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://client.com/rp?
code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk
&state=af0ifjsldkj

3.5.2.  End-User Denies Authorization or Invalid Request FIle

If the user denies the authorization or the user authentication fails, the server MUST return the negative authorization response as defined in OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc]. No other parameter SHOULD be returned.

3.6.  Client requests Assertion using the "code"

Upon receipt of the "code", the Client requests an Assertion that includes the "access_token" and other variables. To obtain the assertion, the client send the following parameters via HTTPS POST to the token endpoint using application/x-www-form-urlencoded format in the HTTP request entity-body:

grant_type

REQUIRED. A string "authorization_code".

code

REQUIRED. The authorization code received from the authorization server.

client_id

REQUIRED. The client_id of the RP.

client_secret

OPTIONAL. Client Secret. If the secret_type is "basic", send the pre-shared secret. If the secret_type is "jwt", send the compact serealization of the JWT (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” January 2011.) [jwt] Signature over the 'code'.

secret_type

OPTIONAL. Type of the client_secret. "basic" or "jwt". Defaults to "basic".

TODO - we shouldn't constrain the authentication options here, but rather defer to OAuth2 and applicable extensions.

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

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk
&client_id=s6BhdRkqt3
&client_secret=1234qwer
&secret_type=shared

3.7.  Client receives Assertion in the response body

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

3.7.1.  Positive Assertion

A Positive Assertion is the Access Token Response of the OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc].

The authorization server MUST include a HTTP Cache-Control response header field with a value of no-store in any response containing tokens, secrets, or other sensitive information.

Following is a non-normative example for openid2json version of the Assertion:

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

{
    "access_token": "SlAV32hkKG",
    "token_type": "jwt",
    "refresh_token": "8xLOxBtZp8",
    "user_id": "http://op.example.com/alice#1234",
    "domain": "op.example.com",
    "expires_in": 3600,
    "session":"jwtheader.jwtpayload.jwtcrypto"
}

3.7.2.  Error Response

If the Token Request is invalid or unauthorized, the Authorization Server constructs the response by returning the Token Error Response defined in OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc] in the entity body of the HTTP response using the application/json media type with HTTP response code 400.

Following is a non-normative example:

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

{
  "error":"invalid_request"
}

3.8.  Accessing Userinfo Endpoint

To obtain the additional attributes and tokens/assertions, the client makes a GET or POST request to the Userinfo Endpoint as in OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc].

3.8.1.  Requesting Userinfo

Client SHOULD send the the UserInfo request defined in section 4.3.1 of the OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc] either in HTTP GET or POST request.

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

POST /userinfo HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

access_token=SlAV32hkKG

3.9.  RP receives UserInfo Response

Upon receipt of the UserInfo Request, the UserInfo Endpoint MUST return the JSON Serialization of the Userinfo Response as in [cc] (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) in the HTTP response body.

Following is a non-normative example of such response.

{
    "name": {
        "givenName": "Jane",
        "familyName": "Doe"
    },
    "displayName": "Jane Doe",
    "emails": [
        {
            "value": "janedoe@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"
        }
    ]
}

3.9.1.  Error Response

When some error condition arises, the UserInfo endpoint returns the Error Response defined in section 4.3.3 of the OpenID Connect Core (Recordon, D., Sakimura, N., Ed., Bradeley, J., de Madeiros, B., and M. Jones, “OpenID Connect Core 1.0,” September 2010.) [cc]

4.  Security Considerations

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

4.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 MUST 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.

4.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.

4.3.  Assertion repudiation

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

4.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.

4.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.

4.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.

4.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.

4.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.

4.9.  Authentication Request Disclosure

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

4.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.

4.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.

5.  IANA Considerations

5.1.  OAuth Parameters Registry

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.

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>

Ryo Itou (ritou@yahoo-corp.jp)

Chuck Mortimore (cmortimore@salesforce.com) <editor>

6. Normative References

Authors' Addresses