OpenID OAuth Extension

Abstract

This draft describe a mechanism to combine an OpenID authentication request with the approval of an OAuth request token.

Table of Contents

1.  Requirements notation
2.  Terminology
3.  Overview
4.  Before Requesting Authentication
5.  Requesting Authentication
6.  Responding to Authentication Requests
7.  Requesting the Access Token
    7.1.  Optimized Access Token Request for Non-Associated RPs
    7.2.  Responding to Access Token Requests
8.  General Considerations
9.  Security Considerations
10.  Normative References
§  Authors' Addresses

1.  Requirements notation

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

2.  Terminology

Terms emphasized are pre-defined in either the [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.) or the [OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.) specifications.

Combined Consumer:

A web service that is simultaneously an OpenID Relying Party (RP) and an OAuth Consumer.

Combined Provider:

A web service that is simultaneously an OpenID Identity Provider (OP) and an OAuth Service Provider (SP).

3.  Overview

The OpenID OAuth Extension describes how to make the OpenID Authentication and OAuth Core specifications work well together. In its current form, it addresses the use case where the OpenID Provider and OAuth Service Provider are the same service. To provide good user experience, it is important to present a combined authentication and authorization screen for the two protocols.

This extension describes how to embed an OAuth approval request into an OpenID authentication request to permit combined user approval. For security reasons, the OAuth access token is not returned in the URL. Instead a mechanism to obtain the access token is provided.

The specific mechanisms proposed are extensions to the OpenID authentication request and response, and also to the assertion verification mechanism, found in Sections 9, 10, and 11 of [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.).

4.  Before Requesting Authentication

The Combined Consumer must, prior to issuing an OpenID authentication request, have obtained an unauthorized OAuth request token (Section 6.1 of [OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.)). It must also have performed OpenID discovery and (optionally) created an association with the OP as indicated in the preamble to Section 9 of [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.).

5.  Requesting Authentication

When Requesting OpenID Authentication via the protocol mode "checkid_setup" or "checkid_immediate", this extension can be used to request that the end user authorize an OAuth token at the same time as their OpenID authorization. This is done by sending the following parameters as part of the OpenID request.

openid.ns.oauth

REQUIRED. Value: "http://specs.openid.net/extensions/oauth/1.0".

openid.oauth.request_token

REQUIRED. Value: The OAuth Unauthorized Request token the Consumer wishes the end user to authorize.

6.  Responding to Authentication Requests

If the OpenID authentication request cannot be fulfilled (either in failure mode "setup_needed" or "cancel" as in Sections 10.2.1 and 10.2.2 of [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.)) then the OAuth request SHOULD be considered to fail and the Provider MUST NOT send any OAuth extension values in the response.

The remainder of this section specifies how to handle the OAuth request in cases when the OpenID authentication response is a positive assertion (Section 10.1 of [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.)).

If the request parameter "openid.oauth.request_token" is present and is a valid Unauthorized Request Token, the Combined Provider SHOULD determine that an authorized end user wishes to complete the OAuth Authorization.

If the end user does wish to grant access to the Consumer, the Combined Provider MUST include and MUST sign the following parameters.

openid.ns.oauth

REQUIRED. Identical value as defined in Section 5 (Requesting Authentication).

openid.oauth.request_token

REQUIRED. The value included in the request.

openid.oauth.response_token

OPTIONAL. The response token MUST be included in the response if the Provider supports the 'Unregistered Consumer' extension to OAuth, (see [UnregisteredOAuth] (Balfanz, D., Eaton, B., and B. de Medeiros, “OAuth Unregistered Consumer Extension,” .)), and the Consumer is unregistered, as defined in that extension. Response tokens are needed by an unregistered Combined Consumer to obtain an OAuth access token.

To note that the OAuth Authorization was declined or not valid, the Combined Provider SHALL only respond with the parameter "openid.ns.oauth".

7.  Requesting the Access Token

To exchange the request token for an access token, the Combined Consumer follows Section 6.3 of [OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.), or Section x.x of [UnregisteredOAuth] (Balfanz, D., Eaton, B., and B. de Medeiros, “OAuth Unregistered Consumer Extension,” .), whichever is appropriate. However, if the Combined Consumer cannot itself verify the signature in the authentication response, it MAY use the optimization described in this Section.

7.1.  Optimized Access Token Request for Non-Associated RPs

If the Combined Consumer cannot itself verify the signature in the authentication response, it MUST construct a direct verification request, according to section 11.4.2.1 of [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.), including all openid.* parameters that appeared in the response. The RP sends the OAuth access token request parameters (section 6.3.1 of [OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.)) either in the HTTP Authorization header or in the query part of the URL (as described in section 5.2 of the same document). The third mechanism defined in the Section 5.2 of [OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.) cannot be used because the OpenID request POST body has an incompatible Mime-type.

7.2.  Responding to Access Token Requests

If the OpenID signature verification fails, the Combined Provider should not include any OAuth extension parameters in the response, and should proceed identically as in Section 11.4.2.2 of [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.).

If the OpenID signature verification succeeds, the Provider verifies the OAuth signature, according to Section 9 of [OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.).

If the OAuth signature verification fails, the OpenID signature verification response proceeds identically as described in Section 11.4.2.2 of [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.).

If the OAuth signature verification succeeds, the Provider constructs an OpenID signature verification response message with the following additional parameters:

openid.ns.oauth

REQUIRED. Same value as in Section Section 5 (Requesting Authentication).

openid.oauth.access_token

REQUIRED. The OAuth access token, encoded according to Section 5.1 of [OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.).

openid.oauth.access_token_secret

REQUIRED. The OAuth access token secret, similarly encoded.

8.  General Considerations

The proposal takes the approach to insulate each protocol from the other, both for backwards compatibility as well as to enable OpenID and OAuth to evolve and incorporate additional features without requiring reviews of the combined usage described here. In particular:

OpenID full compatibility

The OpenID identity provider (OP) MAY safely announce the endpoint supporting the OAuth extension to all relying parties, whether or not they support the extension as well. The use of a separate service-type announcement for Combined Providers endpoints provides a mechanism for auto-discovery of OAuth capabilities by RPs.

OAuth token compatibility

The OAuth tokens approved via this mechanism MAY be used identically as tokens acquired through alternative mechanisms (e.g., via standard OAuth) without requiring special considerations either because of functionality or security reasons.

9.  Security Considerations

This proposal composes protocols that provide security services (authentication in the case of OpenID, authorization in the case of OAuth) with the intention that the combined protocol provides both services simultaneously. Since security is not a property generally preserved by composition, the design takes the approach of encapsulating the OAuth flow within OpenID in a modular way, and applies the general rule-of-thumb of NOT introducing reliance on the security properties of one protocol for the correctness of the other. Ultimately, only public scrutiny and review can incrementally provide confidence that the approach described here is sound from a security perspective.

The following security principles is reflected in this design:

No long-term OAuth secrets hit the browser

The OAuth protocol was designed so that browser-mediated communication is not used to transfer long-term secrets or capabilities to access data. Instead, temporary approval tokens are exchanged through the browser and then exchanged in authenticated server-to-server calls for higher-value secrets and tokens. In this protocol, the use of response_token preserves this feature of the OAuth protocol even with unregistered consumers.

10. Normative References

Authors' Addresses