P. Madsen
Ping Identity
A. Jain
VMware
W. Denniss
Google
J. Bradley, Ed.
Ping Identity
May 22, 2015

Authorization Cross Domain Code 1.0
draft-acdc-01

Abstract

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and RESTful manner.

The acdc grant allows a Authorization Server to issue a grant that can be redeemed by a token endpoint that is not tightly coupled to the issuing Authorization server.

A single Authorization Server (AS) authorization endpoint may in this way support multiple token endpoints, those endpoints may be in diffrent policy domains, including ones run by Software as a Service providers.


Table of Contents

1. Introduction

Authorization Cross Domain Code 1.0 is a profile of the OpenID Connect Core 1.0 [OpenID.Core] specification that stipulates how a Client can obtain single use tokens that can be exchanged for access & refresh tokens at federated token endpoints.

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

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.

1.2. Terminology

This specification uses the terms "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", and "Token Endpoint" defined by OAuth 2.0 [RFC6749]. This specification also defines the following terms:

Authorization Cross Domain Code (ACDC)
A single use token that can be exchanged at a token endpoint for Access and Refresh tokens.

2. Overview

More and more applications, both enterprise on-prem and cloud-based, are accessed through REST APIs in addition to, or instead of, browser-based access. Mobile clients will be a key consumer of such APIs. Native installed applications (e.g for iOS , Android, BlackBerry, etc devices) offer an important alternative to web or browser-based applications. Both models have their pros/cons.

OAuth 2.0 is an authentication & authorization framework for such REST APIs. Critically, OAuth 2.0 is explicitly designed to support the variety of different client types that will be accessing REST APIs - both applications running on web servers within the enterprise calling out to the cloud/partners etc, as well as applications running on mobile phones belonging to employees and customers. OAuth supports this variety of client types by defining multiple mechanisms for 'getting a token', the different mechanisms acknowledging the constraints of particular client types.

For accessing protected resources behind an API using OAuth for authentication, the mobile application requires an access token - this to be presented on the HTTP calls to the API.

The high-level sequence by which the client obtains and uses an access token is:

The ACDC model is shown below

   
+-------------+
| Device      |       
| +--------+  |                                         +-----------+
| |        |-------- Login & Authorization (1)--------->|           |
| |        |  |                                         |           |
| |  App   |<------ ACDC for app- (2)-------------------|           |
| |        |  |                                         |    AS 1   |
| |        |  |                                         |           |
| |        |  |                                         |           |
| |        |  |                                         |           |
| |        |  |                                         +-----------+
| |        |  |                                            
| |        |  |                                             
| |        |  |                                         +-----------+
| |        |---- Request Secondary tokens for app (3)-->|           |
| |        |  |                                         |   AS 2    | 
| |        |<-------Secondary Tokens for apps (4)-------|           |
| |        |  |                                         +-----------+
| |        |  |                                           /\    /\
| |        |  |                                            |     |
| |        |  |                                       Validate tokens (6)
| |        |  |                                            |     | 
| |        |  |                                          +---------+
| |        | -|--------- API Call with token (5)-------> |  RS2    |
| +--------+  |                                          +---------+
+-------------+                                         
                                          
            

Figure 1

  1. The client requests a ACDC grant using the acdc responce_type. The client also sends a PKCE challenge. The client may also include the Audience paramater (aud), to indicate the token_endpoint it intends to exchange the acdc at.
  2. The ACDC token is returned to the client in the acdc paramater.
  3. The client exchanges the acdc and PKCE verifier at the token endpoint identified by the aud paramater from (1).
  4. The client receives access token and optional refresh token from AS2.
  5. The client accesses the resource server.

Note: the token validation of Step 6 may require a call to the issuing AS (as shown) or may be achieved locally via a digital signarture verification.

3. Deployment Models

ACDC tokens can be obtained in two ways:

  1. From the authorization endpoint using the acdc response type.
  2. From the token endpoint by using the refresh token grant type and including the PKCE paramater code_challange and 'aud' to indicate the intended audience.

4. Audience

When an authorization server creates a ACDC token, it needs to indicate what token_endpoint it will be used at.

This section defines a new paramater that is used by the client to indicate what protected resource at which resource server it wants to access if requesting a access token, or which token_endpoint if requesting a ACDC grant. This information may subsequently also communicated by the authorization server securely to the resource server, for example within the audience field of the access token or ACDC token.

4.1. Audience Parameter: Token Endpoint

The client constructs the ACDC token request to the token endpoint by adding the 'aud' parameter using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body.

The URI included in the aud parameter MUST be an absolute URI as defined by Section 4.3 of [RFC3986]. It MAY include an "application/x-www-form-urlencoded" formatted query component (Section 3.4 of [RFC3986] ). The URI MUST NOT include a fragment component.

The ABNF syntax for the 'aud' element is defined in Appendix C.

If requesting a code or acdc token the value of the 'aud' paramater MUST be the absolute URI of the token_endpoint that the resulting token is to be presented to. Failing to provide the propper URI may cause the token to be rejected by the token_endpoint.

4.2. Audience Parameter: Authorization Endpoint

The client constructs the ACDC token request to the authorization endpoint by adding the 'aud' parameter to the query string of the authorization request.

The URI included in the aud parameter MUST be an absolute URI as defined by Section 4.3 of [RFC3986]. It MAY include an "application/x-www-form-urlencoded" formatted query component (Section 3.4 of [RFC3986] ). The URI MUST NOT include a fragment component.

The ABNF syntax for the 'aud' element is defined in Appendix C.

If requesting a acdc token the value of the 'aud' paramater MUST be the absolute URI of the token_endpoint that the resulting token is to be presented to. Failing to provide the propper URI may cause the token to be rejected by the token_endpoint.

5. ACDC Token Response Type

This section registers a new Response Type, the acdc , in accordance with the stipulations in the OAuth 2.0 specification, Section 8.4. The intended purpose of the acdc is that it MUST provide an assertion of the scopes authorized by the Resource Owner as understood by the Authorization Server. The assertion MUST specify a targeted audience, e.g. the target AS and SHOULD contain the identity of the Resource Owner as understood by the Authorization Server.

6. ACDC Grant type

This section registers a new Grant Type, the urn:ietf:params:oauth:grant-type:jwt-acdc

This isa profile of the JWT Authorization grant defined in Sec 4 of [RFC7523]

6.1. ACDC Grant type processing

JWT authorization grants may be used with or without client authentication or identification. Whether or not client authentication is needed in conjunction with a JWT authorization grant, as well as the supported types of client authentication, are policy decisions at the discretion of the authorization server. However, if client credentials are present in the request, the authorization server MUST validate them.

The cnf element MUST be present in the JWT. The default confirmation method is PKCE. Other Proof of possession methods may be defined as extensions, but are out of scope for this document.

The pkce element is present in the JWT, the AS must require the code_verifyer to be present in the request and validate it according to the PKCE [I-D.ietf-oauth-spop] specification.

If the JWT is not valid, or the current time is not within the token's valid time window for use, the authorization server constructs an error response as defined in OAuth 2.0 [RFC6749]. The value of the "error" parameter MUST be the "invalid_grant" error code. The authorization server MAY include additional information regarding the reasons the JWT was considered invalid using the "error_description" or "error_uri" parameters.

For example:

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

     {
      "error":"invalid_grant",
      "error_description":"Audience validation failed"
     }
                
            

Figure 2

7. ACDC Token

The ACDC Token is a single use security token that contains Claims about the authorization grant. The ACDC Token is represented as a JSON Web Token (JWT) [RFC7519].

The ACDC Token is used to communicate authorization information between authorization servers. The user is passed as the value of sub is scoped to the iss.

The ACDC Token is audience restricted to a remote AS via the aud (audience) Claim.

The cnf claim from JWT POP communicates the PKCE code_challange and code_challange_method. If code_challange_method is not included the default is "S256". The code_challange_method "plain" MUST NOT be used.

The scopes claim is an array of scopes that the AS has granted for this client.

The sid claim is a string identifying the user session as understood by the AS. In the case of a native application this SHOULD identify the device.

The following is a non-normative example of a base64url decoded ACDC Token with the remote AS as the value of aud and the client_id as the value of azp (with line wraps for display purposes only):

  {
   "iss": "https://server.example.com",
   "sub": "24400320",
   "azp": "client-ID",
   "aud": "https://server.partner.com",
   "exp": 1311281970,
   "iat": 1311280970,
   "sid": "Work iPhone",
   "cnf":{ "code_challange" : "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
          "code_challange_method" : "S256" },
   "scopes" : [ "scope1" , "scope2" ]
  }

8. Security Considerations

TBD

9. Privacy Considerations

TBD

10. IANA Considerations

This document makes no requests of IANA.

11. Normative References

[I-D.ietf-oauth-spop] Sakimura, N., Bradley, J. and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", Internet-Draft draft-ietf-oauth-spop-11, May 2015.
[OpenID.Core] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C. and E. Jay, "OpenID Connect Standard 1.0", December 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999.
[RFC3986] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012.
[RFC7519] Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, May 2015.
[RFC7521] Campbell, B., Mortimore, C., Jones, M. and Y. Goland, "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, May 2015.
[RFC7523] Jones, M., Campbell, B. and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, May 2015.

Appendix A. Acknowledgements

The following have contributed to the development of this specification.

  • Chuck Mortimore
  • Brian Campbell
  • Scott Tomilson

Appendix B. Notices

Copyright (c) 2014 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.

Appendix C. Augmented Backus-Naur Form (ABNF) Syntax

This section provides Augmented Backus-Naur Form (ABNF) syntax descriptions for the elements defined in this specification using the notation of [RFC5234].

C.1. 'aud' Syntax

The ABNF syntax is defined as follows where by the "URI-reference" definition is taken from [RFC3986]:

  • aud = URI-reference

Appendix D. Document History

[[ To be removed from the final specification ]]

-01

  • Initial draft

Authors' Addresses

Paul Madsen Ping Identity EMail: paul.madsen@gmail.com
Ashish Jain VMware EMail: itickr@gmail.com
William Denniss Google EMail: wdenniss@google.com
John Bradley (editor) Ping Identity EMail: jbradley@pingidentity.com