OpenID OAuth Extension

Abstract

This draft describes 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.  Purpose of this Specification
4.  Overview
5.  Extension Namespace
6.  Discovery
7.  Before Requesting Authentication - Registration
8.  Requesting Authentication
9.  Authorizing the OAuth Request
10.  Responding to Authentication Requests
11.  Obtaining the Access Token
12.  General Considerations
13.  Security Considerations
14.  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.  Purpose of this Specification

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, to the user, 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 OpenID authentication response. Instead a mechanism to obtain the access token is provided.

4.  Overview

Unlike standard OAuth ([OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.)), the OpenID OAuth Extension does not provision request tokens in a server-to-server request from the Combined Consumer to the request token endpoint at the Combined Provider. Instead, the Combined Provider returns an already-approved request token to the Combined Consumer as part of the OpenID authentication response.

The Combined Consumer then exchanges the request token for an access token at the access token endpoint of the Combined Provider, following standard OAuth practice.

5.  Extension Namespace

This protocol is an extension as defined by Section 12 of [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.). The namespace URI for this extension is "http://specs.openid.net/extensions/oauth/1.0".

All OpenID messages that contain an OpenID OAuth Extension element MUST contain the following extension namespace declaration:

openid.ns.<alias>=http://specs.openid.net/extensions/oauth/1.0

The actual extension namespace alias is determined by the party composing the message in such a manner as to avoid conflicts among multiple extensions. Throughout this document "oauth" is used as an example for the extension namespace alias.

6.  Discovery

Discovery of the OpenID OAuth Extension is achieved via the mechanism described in [OpenID] (Openid.net, “OpenID Authentication 2.0 - Final,” December 2007.). The OpenID OAuth Extension namespace "http://specs.openid.net/extensions/oauth/1.0" SHOULD be listed as an <xrd:Type> child element of the <xrd:Service> element in the XRDS discovery document.

7.  Before Requesting Authentication - Registration

The Combined Consumer and the Combined Provider agree on a consumer key and consumer secret (see [OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.)).

The Combined Provider SHOULD in addition obtain, from the Combined Consumer, a list of valid OpenID realms that the Combined Consumer may use in subsequent authentication requests. The Combined Provider SHOULD verify that the Combined Consumer is authorized to use those realms.

8.  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 access token at the same time as an OpenID authentication. This is done by sending the following parameters as part of the OpenID request. (Note that the use of "oauth" as part of the parameter names here and in subsequent sections is just an example. See Section 5 (Extension Namespace) for details.)

openid.ns.oauth

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

openid.oauth.consumer

REQUIRED. Value: The consumer key agreed upon in Section 7 (Before Requesting Authentication - Registration).

openid.oauth.scope

OPTIONAL. Value: A string that encodes, in a way possibly specific to the Combined Provider, one or more scopes for the OAuth token expected in the authentication response.

9.  Authorizing the OAuth Request

If the OpenID OAuth Extension is present in the authentication request, the Combined Provider SHOULD verify that the consumer key passed in the request is authorized to be used for the realm passed in the request. If this verification succeeds, the Combined Provider SHOULD determine that delegation of access from a user to the Combined Consumer has been requested.

The Combined Provider SHOULD NOT issue an approved request token unless it has user consent to perform such delegation.

10.  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 OpenID 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 end user does wish to delegate access to the Combined Consumer, the Combined Provider MUST include and MUST sign the following parameters.

openid.ns.oauth

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

openid.oauth.request_token

REQUIRED. A user-approved request token.

openid.oauth.scope

OPTIONAL. A string that encodes, in a way possibly specific to the Combined Provider, one or more scopes that the returned request token is valid for. This will typically indicate a subset of the scopes requested in Section 8 (Requesting Authentication).

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

11.  Obtaining the Access Token

To exchange the request token for an access token, the Combined Consumer follows Section 6.3.1 of [OAuth] (OAuth Core Workgroup, “OAuth Core 1.0,” December 2007.), i.e., it sends an access token request to the access token endpoint of the Combined Provider. It SHALL use the following values to create the OAuth access token request:

consumer key

Combined Consumers use the consumer key they established with the Combined Provider in Section 7 (Before Requesting Authentication - Registration).

consumer secret

Combined Consumers use the consumer secret they established with the Combined Provider in Section 7 (Before Requesting Authentication - Registration).

OAuth token

Combined Consumers use the request token obtained in Section 10 (Responding to Authentication Requests).

OAuth token secret

Combined Consumers use the empty string.

The Combined Provider follows Section 6.3.2 to verify the request and either issue the access token or send an error response.

12.  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 OpenID 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.

13.  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 are 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, server-to-server calls are used to exchange such secrets). Combined Providers can preserve this property by making the request_token short-lived, since the request token will be exchanged for an access token and secret over a server-to-server call.

Imposters cannot retrieve the OAuth access token

While it is possible for a malicious party to fake an OpenID request, including an OpenID request that includes the OpenID OAuth Extension (the request is not signed, and knowledge of the consumer key and realm is sufficient to cause the Combined Provider to display an authorization page for that realm/consumer), that malicious party would have to have knowledge of the consumer secret to exchange the request token for an access token. Note that while secure under reasonable threat models, this is different from standard OAuth: In standard OAuth, one needs knowledge of both the consumer key and consumer secret (or, alternatively, of a request token obtained through knowledge of the consumer key and secret) to cause the Service Provider to display an authorization page for that consumer.

14. Normative References

Authors' Addresses