OAuth2 Bootstrap to web session - draft 03

Abstract

This document describes a process that allows a client to seamlessly transition the user from an authenticated state in a native application, to an authenticated state in a web browser.

Requirements Language

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

Table of Contents

1.  Introduction
    1.1.  Roles
    1.2.  Scopes
    1.3.  Protocol Flow
    1.4.  Terminology
2.  Bootstrap Token
    2.1.  Refresh Token Authorization Grant
    2.2.  Assertion Framework Authorization Grants
    2.3.  Bootstrap Token Request Processing Rules
3.  Web Session endpoint
4.  Security Considerations
5.  Normative References
§  Author's Address

1.  Introduction

In order to provide a good user experience it is necessary at times to "share" an authentication state across disparate environments. For example, a desktop utility that shows the user a list of their last N mail messages, and when the user selects one of the mail messages, opens a browser logging the user into their mail account on the web.

This document defines a process based on OAuth2 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] to enable this functionality.

1.1.  Roles

This specification uses the 'client' and 'authorization server' roles from the OAuth2 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] specifcation. In addition to these two roles, this specification also identifies the role of the

web application

The destination web application where the user will be seamlessly logged in.

1.2.  Scopes

This specification defines an additional scope that MUST be authorized to the client in order to obtain the bootstrap-token.

web_session

A scope that provides the client the authorization to obtain a bootstrap-token

1.3.  Protocol Flow

                                       +-----------------+
                                       |                 |
                                       |                 |
               +----------(C)----------+    Client       |
               |                       |                 |
               |                       |                 |
               |                       +------------+----+
               |                            ^       |
               |                            |      (A)
               |                           (B)      |
               v                            |       v
     +-----------------+               +----+------------+
     |                 |               |                 |
     |                 +-----(D)------>|                 |
     |    Browser      |               |  Authorization  |
     |                 |<----(E)-------+     Server      |
     |                 |               |                 |
     +---------+-------+               +-----------------+
               |
               |
               |
               |                       +-----------------+
               |                       |                 |
               |                       |                 |
               +----------(F)--------->|      Web        |
                                       |  Application    |
                                       |                 |
                                       +-----------------+

Figure 1: Abstract Protocol Flow

The abstract Web Session Bootstrap flow illustrated in Figure 1 describes the interaction between the three roles and includes the following steps:

(A)

The client requests a bootstrap-token using the OAuth2 token endpoing (e.g. grant_type=refresh_token)

(B)

The authorization server returns bootstrap-token

(C)

The client constructs a URL to the AS (/web-session?access_token=<bootstrap-token>) and loads it into the browser

(D)

The browser invokes the AS /web-session endpoint.

(E)

The AS validates the bootstrap-token and establishes a web session for the user identified by the token. The AS redirects the browser to the destination web application (potentially setting cookies)

(F)

The browser follows the HTTP redirect and loads the destination web application

1.4.  Terminology

See OAuth2 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] for terminology used in this specification. In addition to the terms defined in the OAuth2 specification, the following terms are defined:

bootstrap-token

An OAuth2 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] access_token that is used to bootstrap the authentication context from the client to the web application.

2.  Bootstrap Token

In order for the client to obtain a bootstrap-token, the client MUST have an authorization grant that is authorized with the 'web_session' scope. The process of obtaining an authorization grant authorized with the 'web_session' scope is outside the scope of this document. This specification specifically profiles the refresh_token and Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants. The required scope for this process is

web_session

This scope provides the authorized party the ability to bridge the user's identity from the receiving client application to a browser based session.

2.1.  Refresh Token Authorization Grant

The request to obtain the bootstrap-token uses the token endpoint described in section 6 of OAuth2 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. This use of the /token endpoint is profiled for grant_type=refresh_token as follows.

grant_type

The value MUST be 'refresh_token'

refresh_token

The refresh_token obtained by the client.

scope

The value MUST only contain 'web_session'. This is effectively a "downscoped" token and MUST only be used for this flow.

dest_url

An additional parameter used by this profile; The URL to which the browser should be redirected if the seamless bootstrapping of the authentication is successful.

2.2.  Assertion Framework Authorization Grants

The request to obtain the bootstrap-token uses the token endpoint described in section 6 of OAuth2 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. This use of the /token endpoint is profiled for grant types of the Assertion Framework as follows.

grant_type

The value MUST be a valid assertion framework grant type

assertion

The assertion previous issued in an authorization grant.

scope

The value MUST only contain 'web_session'. This is effectively a "downscoped" token and MUST only be used for this flow.

dest_url

An additional parameter used by this profile; The URL to which the browser should be redirected if the seamless bootstrapping of the authentication is successful.

2.3.  Bootstrap Token Request Processing Rules

The authorization server MUST validate the request as follows

1. Verify the client credentials. The request MUST fail if the client credentials are not valid. The AS may whitelist clients such that only certain clients can perform this function.
2. Verify the authorization grant. The authoriztaion grant MUST be valid and MUST be granted the 'web_session' scope.
3. Generate a new bootstrap-token with a short expiry time. Note that these tokens SHOULD be treated as one-time-use tokens. The bootstrap-token MUST be associated with the specified dest_url. If no dest_url is specified, the request SHOULD fail.
4. Return bootstrap-token as the access_token in the response per OAuth2 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] Section 6

For Example: (line breaks added for readability)

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

     grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&
     scope=web_session&dest_url=https%3A%2F%2Fweb-app.example.com

In the case that there are processing rule errors or other failure conditions the /token endpoint response MUST conform to OAuth2 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] Section 5.2

3.  Web Session endpoint

The web session endpoint allows the holder of a bootstrap-token to establish an authenticated web session for the user identified by the bootstrap-token. This endpoint is a protected resource as defined by Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750].

This endpoint defines no additional parameters other than the OAuth2 access token. The client invokes this API by specifying the bootstrap-token as the API's access_token.

The web session endpoint MUST support both the GET and POST methods of the Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] specification. Support for the Authorization header is not required as most browsers do not allow for setting of arbitrary HTTP headers.

The web session endpoint SHOULD identify requests not coming from a browser and return an error of 'invalid_request'

On receipt of a web-session request, the Authorization Server MUST validate the bootstrap-token to ensure that it has not expired and SHOULD verify the token is not being replayed.

The AS then determines the user and destination URL from the bootstrap-token and establishes a web session for this user. NOTE: the web session context MUST identify that this web session was establish with a means other than user credentials.

The web-session endpoint responds successfully by returning a HTTP 302 redirect instructing the browser to load the destination URL and setting whatever cookies necessary to establish the web authentication session.

For Example: (line breaks added for readability)

     HTTP/1.1 302 Found
     Host: server.example.com
     Location: http://web-app.example.com
     Set-Cookie: AuthSession=asdfasdfasd; Domain=.example.com; Path=/; Secure; HttpOnly

The mechanism by which web application determines the identity of the web authentication session is out of scope of this document.

Error responses for this endpoint follow the Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] specification.

4.  Security Considerations

In some ways this exposes an escalation of privileges because a "restricted" (by scope[s]) refresh_token is used to generate a full web session. It is imperative that the session semantics generated by the Web-Session endpoint ensure that downstream web-applications understand that the user has not "recently" authenticated and instead this session is generated from an existing token. In many respects, this web-session is equivalent to that generated from a "remember me" or "keep me signed in" cookie as supported on many sites. Access to special privileges for this user SHOULD be restricted and require additional authentication checks. Possible mitiations include...

• One way to manage the authentication session is to track the time at which the user last presented authentication credentials (e.g. password). By tracking this within the session context any web-application can protect certain privileges by requiring the user to have presented their credentials within the last n seconds/minutes. For a web session created via this flow, the authentication credentials presentation time is the time at which the user authenticated to create the refresh_token.
• The Authorization Server SHOULD revoke any existing web session if the refresh_token used to create the web session is revoked.
• Any additional tokens issued from the web session MUST be linked to the refresh_token that created the web session such that if the refresh_token is revoked or expired, the generated access tokens are revoked/expired accordingly.
• The Authorization Server SHOULD provide an interface for the user that shows the active web sessions issued from refresh tokens and allow the user to expire the web session.

5. Normative References

Author's Address