OpenID User Interface Extension 1.0 - DRAFT 0.5

Abstract

This specification defines a mechanism to support OpenID user interfaces optimized for different environments and languages.

Table of Contents

1.  Notation and Conventions
2.  Overview
3.  Extension Namespace
4.  Language Preference
5.  Requesting Authentication in a Popup
    5.1.  Authentication Response in a Fragment
6.  Requesting Display of RP icons in the OP Approval UI
7.  Discovery
8.  Considerations
9.  Acknowledgements
10.  References
Appendix A.  Example Use of Experimental Mode
§  Authors' Addresses

1.  Notation and Conventions

The keywords 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, B., “Key words for use in RFCs to Indicate Requirement Levels,” .).

Unless otherwise noted, this specification is written as a direct continuation of [OpenID 2.0] (OpenID 2.0 Workgroup, “OpenID 2.0,” .), inheriting the definitions and guidelines set by it.

2.  Overview

OpenID traditionally required the Relying Party to redirect the entire browser window to the OpenID Provider for the user to authenticate before redirecting the browser back to the Relying Party. It is believed that the User Experience (UX) could be significantly improved if the authentication flow occurred within a separate popup window, making the experience less disruptive to the user.

Although it is possible for Relying Parties to open a popup window for the user to authenticate at the OpenID Provider using the Provider's default user interface, the overall user experience can be optimized if the OP was aware that its UI was running within a popup. For instance, an OP may want to resize the popup browser window when using the popup interface, but would probably not want to resize the full browser window when using the default redirect interface. Another optimization is that the OP can close the popup, rather than return a negative assertion if the user chooses to cancel the authentication request.

This extension also adds support for Relying Parties to indicate the user's language preference to the OP, potentially making the transition from the RP to the OP less disruptive to the user.

3.  Extension Namespace

All OpenID 2.0 messages that contain a UI Extension element MUST contain the following extension namespace declaration, as specified in the Extensions section of [OpenID 2.0] (OpenID 2.0 Workgroup, “OpenID 2.0,” .).

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

The actual extension namespace alias should be determined on a per-message basis by the party composing the messages, in such a manner as to avoid conflicts between multiple extensions. For the purposes of this document, the extension namespace used for all examples is "ui".

4.  Language Preference

When requesting OpenID authentication using the checkid_setup mode, the Relying Party MAY send the OP a hint regarding the user's preferred language by sending the following parameters:

openid.ns.ui

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

openid.ui.lang

REQUIRED. The user's preferred languages as a [BCP 47] (Phillips, A. and M. Davis, “Tags for Identifying Languages,” .) language priority list, represented as a comma-separated list of BCP 47 basic language ranges in descending priority order. For instance, the value "fr-CA,fr-FR,en-CA" represents the preference for French spoken in Canada, French spoken in France, followed by English spoken in Canada.

The language preference hint SHOULD take precedence over the Accept-Language HTTP header sent by the user's browser, and SHOULD take precedence over the language preference inferred by the user's IP address.

5.  Requesting Authentication in a Popup

The Relying Party SHOULD first request authentication using the checkid_immedidate mode if the Relying Party has reason to believe that user had previously authenticated at the Relying Party and can determine the user's OpenID Provider.

When requesting OpenID authentication using the checkid_setup mode, the Relying Party MUST send the following parameters:

openid.ns.ui

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

openid.ui.mode

REQUIRED. Value: "popup". New modes may be defined in future versions of this extension. Any mode starting with the prefix "x-" should be considered experimental. If an OpenID provider receives a request containing an experimental mode, and it does not recognize that mode, it SHOULD NOT throw an error or invalidate further processing of this extension. If no other parameters are present, then the OpenID provider receiving an experimental mode SHOULD continue processing the OpenID request as if this extension were not included in it.

The RP SHOULD create the popup to be 450 pixels wide and 500 pixels tall. The popup MUST have the address bar displayed, and MUST be in a standalone browser window. The contents of the popup MUST NOT be framed by the RP.

The RP SHOULD open the popup centered above the main browser window, and SHOULD dim the contents of the parent window while the popup is active. The RP SHOULD ensure that the user is not surprised by the appearance of the popup, and understands how to interact with it.

To keep the user popup user experience consistent, it is RECOMMENDED that the OP does not resize the popup window unless the OP requires additional space to show special features that are not usually displayed as part of the default popup user experience.

The OP MAY close the popup without returning a response to the RP. Closing the popup without sending a response should be interpreted as a negative assertion.

The response to an authentication request in a popup is unchanged from [OpenID 2.0] (OpenID 2.0 Workgroup, “OpenID 2.0,” .). Relying Parties detecting that the popup was closed without receiving an authentication response SHOULD interpret the close event to be a negative assertion.

5.1.  Authentication Response in a Fragment

The user experience can be optimized by returning the authentication response parameters in the fragment portion of the Relying Party's return_to URL, allowing the content of the return_to URL to be returned from the browser's cache, if already present. To use this technique, the Relying Party MUST include the fragment delimiter (the "#" character) in the return_to URL in the authentication request. If the fragment delimiter character is present in the return_to URL, the OpenID Provider SHOULD return the response parameters in the fragment portion of the URL. If the return_to URL already contains a question mark "?", the first response parameter MUST be prefixed with an ampersand "&", otherwise the first response parameter MUST be prefixed with a question mark "?".

6.  Requesting Display of RP icons in the OP Approval UI

When requesting authentication, the Relying Party MAY indicate to the OpenID Provider the availability of graphical resources to represent the Relying Party brand at the OpenID Provider's approval UI. This is indicated by including the following parameter:

openid.ui.icon

REQUIRED. Value: "true"

In order to retrieve the indicated graphical resources, the OpenID Provider performs discovery on the Relying Party, as specified in [OpenID 2.0] (OpenID 2.0 Workgroup, “OpenID 2.0,” .) (or future versions of the OpenID protocol specification). The RP SHOULD indicate the location of the graphical resource by adding an entry to its XRDS document:

<Service xmlns="xri://$xrd*($v*2.0)">
  <Type>http://specs.openid.net/extensions/ui/icon</Type>
  <URI>http://consumer.example.com/images/image.jpg</URI>
</Service>

<Service xmlns="xri://$xrd*($v*2.0)">
  <Type>http://specs.openid.net/extensions/ui/icon</Type>
  <URI>http://consumer.example.com/favicon.ico</URI>
</Service>

If the Relying Party indicates availability of graphical resources using the "icon" parameter but the OpenID Provider does not succeed in obtaining a discovery document at the Relying Party, the OpenID Provider MAY attempt to locate a graphical resource at the domain indicated by "openid.realm", under the path "/favicon.ico". If the realm contains the wildcard "*" for the host, the OpenID Provider should replace it with "www". In this case, the OpenID provider MAY restrict the display of the resource to 16x16 format, and the Relying Party SHOULD ensure that the resource displays well in 16x16 format.

It is RECOMMENDED that the OpenID Provider do not inline graphical resources from the Relying Party without verification. Instead, the OpenID Provider SHOULD proxy the icons after performing appropriate sanitization. Proxying is also necessary to avoid mixed-content warnings if the OpenID Provider approval page is served over HTTPS but the graphical resource is only available over HTTP.

7.  Discovery

OpenID Providers supporting the User Interface Extension SHOULD advertise their support of the Extension using OpenID Discovery as defined in Section 7.3 of [OpenID 2.0] (OpenID 2.0 Workgroup, “OpenID 2.0,” .).

OpenID Providers supporting the language preference functionality SHOULD define http://specs.openid.net/extensions/ui/1.0/lang-pref as a <xrd:Type> child element of the <xrd:Service> element in the XRDS discovery document.

<Type>http://specs.openid.net/extensions/ui/1.0/lang-pref</Type>

OpenID Providers supporting the popup functionality SHOULD define http://specs.openid.net/extensions/ui/1.0/mode/popup as a <xrd:Type> child element of the <xrd:Service> element in the XRDS discovery document.

<Type>http://specs.openid.net/extensions/ui/1.0/mode/popup</Type>

OpenID Providers supporting the graphical RP representation functionality SHOULD define http://specs.openid.net/extensions/ui/1.0/icon as a <xrd:Type> child element of the <xrd:Service> element in the XRDS discovery document.

<Type>http://specs.openid.net/extensions/ui/1.0/icon</Type>

8.  Considerations

OpenID Providers SHOULD use HTTPS for all their authentication screens, and educate their users to always check their browser's address bar before entering their credentials. OPs SHOULD implement Javascript framebusting code to prevent their UI from being framed.

Credential verification and approval screens SHOULD always be in an independent browser window to protect the user's credentials and approval from clickjacking exploits.

9.  Acknowledgements

Allen Tom (atom@yahoo-inc.com)

Breno de Medeiros (breno@google.com)

Brian Ellin (brian@janrain.com)

Chris Messina (chris@citizenagency.com)

David Recordon (david@sixapart.com)

10. References

Appendix A.  Example Use of Experimental Mode

In OpenID authentication, when using the checkid_immediate mode, there is no mechanism to indicate that there is a user logged in at the OpenID Provider. Therefore, the Relying Party does not know if the checkid_immediate request failed because:

1. The user does not have an account at the OpenID Provider (or is not logged in at the Provider), or:
2. The user is logged in to the OpenID Provider but has not yet approved transparent login with the Relying Party.

This makes it difficult for the RP to optimize the OpenID user experience by, for instance, displaying a prominent button for the OpenID Provider in case (2). The following example shows how an experimental mode can be sent with checkid_immediate requests to obtain this information.

openid.ns.ui

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

openid.ui.mode

REQUIRED. Value: "x-has-session".

To respond, the OpenID provider sends identical parameters in the "setup_needed" response to answer affirmatively (i.e., there IS an authenticated browser session):

openid.ns.ui

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

openid.ui.mode

REQUIRED. Value: "x-has-session".

Alternative, if the OpenID provider needs to indicate the LACK of a session, it sends simply the UI namespace, without a mode, in the "setup_needed" response:

openid.ns.ui

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

Authors' Addresses