OpenID Connect - Part 2: Authentication Implicit 1.0 draft-01

Abstract

OpenID Connect Authentication Basic 1.0 is an authentication extension to OAuth 2.0 [RFC6749] implicit flow. It allows Clients to verify the Identity of the End-User based on the authentication performed by an OAuth 2.0 Authorization Server by extending the Authorization and Token Endpoint responses.

Table of Contents

1.  Introduction
2.  Terminology
3.  Authorization Endpoint
4.  ID Token and Access Token Validation
5.  Initiating Login at Client from Third Party
6.  Security Considerations
7.  Privacy Considerations
8.  IANA Considerations
9.  References
    9.1.  Normative References
    9.2.  Informative References
Appendix A.  Examples
Appendix B.  Acknowledgements
Appendix C.  Notices
§  Authors' Addresses

1.  Introduction

OpenID Connect Authentication Basic 1.0 defines how to perfom federated login using OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. It does so by extending Authorization Endoint and Token Endpoint by defining standardized scope and a new token type. In perticular, it introduces a standard scope called openid, which asks the server to provide the authentication event information through a new token type called ID Token, which is a JSON Web Token (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT].

As this specification is built on top of OAuth 2.0, it trys to avoid duplicating the normative text of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. As the result, the readers are expected to be familiar witth to read this specification.

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

All uses of JSON Web Signature (JWS) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] data structures in this specification utilize the JWS Compact Serialization; the JWS JSON Serialization is not used.

When the RFC 2119 language applies to the behavior of OpenID Providers, it is in this specification for explanatory value to help Client implementers understand the expected behavior of OpenID Providers.

2.  Terminology

This specification strives to make itself readable without constantly refering to the term definitions. Defined terms are shown with its first letters capitalized. When in doubt, refer to OpenID Connect Messages 1.0 for the authoritative defintion of the defined terms.

3.  Authorization Endpoint

For the purpose of this specification, it is assumed that the Relying Party knows the location of the Authorization Endpoint in one way or another. It could be through out-of-band information sharing or through some form of discovery operation, which is out of scope of this specification.

To start the Authentication process for the End User, the RP sends the User-Agent to the Authorization Endpoint through HTTP redirection or other mechanism. The parameters that are sent are that of the OAuth 2.0 Authorization Request plus some OpenID Connect specific parameters. They are sent to the Authorization Endpoint using HTTPS and the server MUST be able to process these parameters.

3.1.  Request Parameters

Follwoings are the OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] parametes.

scope

REQUIRED. The value MUST contain the openid. This scope value requests ID Token, which is a JWT that includes the Claims about the End-User Authentication event.

response_type

REQUIRED. The value MUST be token id_token or code token id_token as defined in OAuth 2.0 Multiple Response Type Encoding Practices (de Medeiros, B., Ed., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” June 2013.) [OAuth.Responses].

client_id

REQUIRED. OAuth 2.0 Client Identifier.

redirect_uri

REQUIRED. Redirection URI to which the response will be sent. This MUST be pre-registered with the OpenID Provider. This URI MUST exactly match one of the redirect_uris registered for the Client, with the matching performed as described in Section 6.2.1 of [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) (Simple String Comparison).The redirection URI MUST use the https scheme.

state

RECOMMENDED. Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with the browser cookie.

The OpenID Connect parameter nonce is REQUIRED for this specification.

nonce

REQUIRED. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values. One method to achieve this is to store a random value as a signed session cookie, and pass the value in the nonce parameter. In that case, the nonce in the returned ID Token can be compared to the signed session cookie to detect ID Token replay by third parties.

Other OPTIONAL parameters defined in [OpenID.Core] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Authentication Core 1.0,” July 2013.) such as display, prompt, max_age, ui_locales, etc. can be used as well.

Following is a non-normative example using HTTP redirect (with line wraps within values for display purposes only):

  HTTP/1.1 302 Found
  Location: https://server.example.com/authorize?
    response_type=token%20id_token
    &client_id=s6BhdRkqt3
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    &scope=openid
    &state=af0ifjsldkj

3.2.  Server Processings

Upon receipt of the parameters, the server MUST perform the following.

1. Check if scope includes openid. If it does not, just proceed with normal OAuth processing;
2. Chekc that response_type is token id_token.
3. Authenticate the user and obtain authorization from the user as needed;

3.3.  Authorization Response

If the Resource Owner authenticates and authorizes, the Authorization Endpoint returns the OAuth 2.0 response as follows:

3.3.1.  Authorization Successful Response

The Authorization Server returns OAuth 2.0 parameters as defined in Section 4.2.2 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] together with ID Token. The Client MUST follow the validation rule set by OAuth 2.0.

The following is a non-normative example (with line wraps for the display purposes only):

  HTTP/1.1 302 Found
  Location: https://client.example.org/cb#
    access_token=jHkWEdUXMU1BwAsC4vtUsZwnNvTIxEl0z9K3vx5KF0Y
    &token_type=Bearer
    &id_token=eyJhbGciOiJSUzI1NiJ9.ew0KICJpc3MiOiAiaHR0cDovL3NlcnZlc
    i5leGFtcGxlLmNvbSIsDQogInN1YiI6ICIyNDgyODk3NjEwMDEiLA0KICJhdWQiO
    iAiczZCaGRSa3F0MyIsDQogIm5vbmNlIjogIm4tMFM2X1d6QTJNaiIsDQogImV4c
    CI6IDEzMTEyODE5NzAsDQogImlhdCI6IDEzMTEyODA5NzAsDQogImF0X2hhc2giO
    iAiNzdRbVVQdGpQZnpXdEYyQW5wSzlSUSINCn0.g7UR4IDBNIjoPFV8exQCosUNV
    eh8bNUTeL4wdQp-2WXIWnly0_4ZK0sh4A4uddfenzo4Cjh4wuPPrSw6lMeujYbGy
    zKspJrRYL3iiYWc2VQcl8RKdHPz_G-7yf5enut1YE8v7PhKucPJCRRoobMjqD73f
    1nJNwQ9KBrfh21Ggbx1p8hNqQeeLLXb9b63JD84hVOXwyHmmcVgvZskge-wExwnh
    Ivv_cxTzxIXsSxcYlh3d9hnu0wdxPZOGjT0_nNZJxvdIwDD4cAT_LE5Ae447qB90
    ZF89Nmb0Oj2b1GdGVQEIr8-FXrHlyD827f0N_hLYPdZ73YK6p10qY9oRtMimg
    &state=af0ifjsldkj

3.3.2.  Authorization Error Response

If the End-User denies the access request or if the request fails, the OP (Authorization Server) informs the RP (Client) by using the Error Response parameters defined in Sections 4.2.2.1 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

In addition to the error codes defined in Sections 4.2.2.1 of OAuth 2.0, the server MUST support the Authorization Error Response defined in [OpenID.Core] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Authentication Core 1.0,” July 2013.).

4.  ID Token and Access Token Validation

4.1.  ID Token Validation by the Client

After validating the response, the Client needs to validate the ID Token to find out the authenticity of the supplied Authentication event information. To validate the ID Token in the Authorization or Token Endpoint Response, the Client MUST follow the Section 4.5 of OpenID Connect Authentication Core 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Authentication Core 1.0,” July 2013.) [OpenID.Core].

4.2.  Access Token Validation

Since the Access Token is returned in the front channel, the client needs to validate the Access Token in this flow. To validate an Access Token issued from the Authorization Endpoint with an ID Token, the Client SHOULD do the following:

1. Hash the octets of the ASCII representation of the access_token with the hash algorithm specified in JWS (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) [JWA] for the alg parameter in the ID Token's JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] header.
2. Take the left-most half of the hash and base64url encode it.
3. The value of at_hash in the ID Token MUST match the value produced in the previous step if at_hash is present in the ID Token.

5.  Initiating Login at Client from Third Party

In some cases, the login flow can start at the Authorization Server or another party by contacting the Client via a stored link. The target resource at the Client can be a deep link, rather than a default landing page. To achieve this, follow Section 5 of OpenID Connect Authentication Core 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Authentication Core 1.0,” July 2013.) [OpenID.Core].

6.  Security Considerations

For Security Considerrations, refer to OpenID Connect Consolidated Security and Privacy Considerations document.

7.  Privacy Considerations

For Privacy Considerations, refer to OpenID Conenct Consolidated Security and Privacy Considerations document.

8.  IANA Considerations

This specification does not request any registration to IANA.

9.  References

9.1. Normative References

9.2. Informative References

Appendix A.  Examples

In this appendix, several examples on the request and responses are shown to aid the developers test their code.

response_type=code

  https://server.example.com/op/authorize?
    response_type=code
    &client_id=s6BhdRkqt3
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    &scope=openid
    &nonce=n-0S6_WzA2Mj
    &state=af0ifjsldkj

  HTTP/1.1 302 Found
  Location: https://client.example.org/cb?
    code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk
    &state=af0ifjsldkj

Upon receipt of the code, the Client sends Token Request to the Token Endpoint to obtain the Tokens.

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

  grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

 HTTP/1.1 200 OK

  {
   "access_token": "SlAV32hkKG",
   "token_type": "Bearer",
   "refresh_token": "8xLOxBtZp8",
   "expires_in": 3600,
   "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
  }

Verifying and decoding the ID Token will yield the following Claims:

  {
   "iss": "http://server.example.com",
   "sub": "248289761001",
   "aud": "s6BhdRkqt3",
   "nonce": "n-0S6_WzA2Mj",
   "exp": 1311281970,
   "iat": 1311280970,
   "at_hash": "77QmUPtjPfzWtF2AnpK9RQ"
  }

Appendix B.  Acknowledgements

As a successor version of OpenID, this specification heavily relies on ideas explored in OpenID Authentication 2.0 (OpenID Foundation, “OpenID Authentication 2.0,” December 2007.) [OpenID.2.0]. Please refer to Appendix C of OpenID Authentication 2.0 for the full list of the contributors for that specification.

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

Naveen Agarwal (naa@google.com), Google

Amanda Anganes (aanganes@mitre.org), Mitre

Casper Biering (cb@peercraft.com), Peercraft

John Bradley (ve7jtb@ve7jtb.com), Ping Identity

Tim Bray (tbray@textuality.com), Google

Johnny Bufu (jbufu@janrain.com), Janrain

Brian Campbell (bcampbell@pingidentity.com), Ping Identity

Breno de Medeiros (breno@gmail.com), Google

Pamela Dingle (pdingle@pingidentity.com), Ping Identity

Vladimir Dzhuvinov (vladimir@nimbusds.com), Nimbus Directory Services

George Fletcher (george.fletcher@corp.aol.com), AOL

Roland Hedberg (roland.hedberg@adm.umu.se), University of Umea

Ryo Ito (ryo.ito@mixi.co.jp), mixi, Inc.

Edmund Jay (ejay@mgi1.com), Illumila

Michael B. Jones (mbj@microsoft.com), Microsoft

Torsten Lodderstedt (t.lodderstedt@telekom.de), Deutsche Telekom

Nov Matake (nov@matake.jp), Independent

Chuck Mortimore (cmortimore@salesforce.com), Salesforce

Anthony Nadalin (tonynad@microsoft.com), Microsoft

Hideki Nara (hdknr@ic-tact.co.jp), Tact Communications

Axel Nennker (axel.nennker@telekom.de), Deutsche Telekom

David Recordon (dr@fb.com), Facebook

Justin Richer (jricher@mitre.org), Mitre

Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.

Luke Shepard (lshepard@fb.com), Facebook

Andreas Akre Solberg (andreas.solberg@uninett.no), UNINET

Paul Tarjan (pt@fb.com), Facebook

Appendix C.  Notices

Copyright (c) 2013 The OpenID Foundation.

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.

Authors' Addresses