OAuth Extension for Specifying User Language Preference - Draft 2

Abstract

This memo describes how the Consumer and Service Provider can communicate the user's preferred language preference.

Table of Contents

1.  Contributors
2.  Notation and Conventions
3.  Definitions
4.  Description
5.  Parameter Specification
6.  Extension Identifier
7.  Processing Rules
8.  Examples
9.  Possible Use Cases
    9.1.  Language preference as part of Request Token request
    9.2.  Language preference as part of Authorization request
10.  References
§  Author's Address

1.  Contributors

Allen Tom

Eran Hammer-Lahav

John Kemp

Joseph Holsten

2.  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] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.). Domain name examples use [RFC2606] (Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” June 1999.).

3.  Definitions

Service Provider:

A web application that allows access via OAuth.

Consumer:

A website or application that uses OAuth to access the Service Provider on behalf of the User.

User:

An individual who has an account with the Service Provider.

4.  Description

In certain cases it is necessary or prudent for the Consumer to specify to the Service Provider the language preference of the user so that UI presented during the user authorization phase is presented in the preferred language of the user.

This language preference specification should be interpreted by the Service Provider as a UI/UE recommendation. The goal is to provide a better experience for the user.

Note that this is NOT the language preference of the Service Provider.

5.  Parameter Specification

The OAuth Language Preference MUST be specified with the parameter name 'xoauth_lang_pref'. The value of the parameter MUST conform to the rules for the Accept-Language HTTP header in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.).

xoauth_lang_pref = 1#( language-range [ ";" "q" "=" qvalue ] )

language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )

As this can be in the query params or form data it will also then need to be appropriately URL-encoded for transmission and decoded for use by the recipient.

6.  Extension Identifier

The Service Provider can advertise that it supports this extension by listing the following URI in the public documentation that also describes the public endpoints. In addition, if the Service Provider supports the [OAuth Discovery 1.0] (Hammer-Lahav, E., “OAuth Discovery 1.0 Draft 1,” December 2007.) specification, then this URI must be listed for each endpoint where the Service Provider will process the parameter.

http://oauth.net/ext/language_preference/1.0

7.  Processing Rules

The Consumer MAY specify the language preference of the user by adding the xoauth_lang_pref parameter to any Service Provider endpoint that supports the extension.

The Service Provider MUST document publicly which endpoints support the extension.

The Service Provider SHOULD specify which enpoints support the Language Preference extension via the [OAuth Discovery 1.0] (Hammer-Lahav, E., “OAuth Discovery 1.0 Draft 1,” December 2007.) specification.

The recipient of the xouath_lang_pref parameter MAY combine the language preferences found in that parameter with those present in any available Accept-Language HTTP header to determine the language preference list of the user (by virtue of any supplied 'quality values' (see [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.), section 14).

The Consumer SHOULD consider using a higher 'quality value' if precedence over the HTTP Accept-Language header is desired.

If the Service Provider can not provide the UI in the preferred language, then the Service Provider should attempt a "best effort match" between the user's preferred languages and the languages supported by the Service Provider. Definition of the "best effort match" algorithm is out of scope for this document.

8.  Examples

Example xoauth_lang_pref with a single language

xoauth_lang_pref="en-us"

Example xoauth_lang_pref with multiple values

xoauth_lang_pref=en-gb;q=1.0, en-us;q=0.8

Example xoauth_lang_pref encoded for transport as query string or form element

xoauth_lang_pref=en-gb%3bq%3d1.0%2c+en-us%3bq%3d0.8

9.  Possible Use Cases

9.1.  Language preference as part of Request Token request

[The following flow is for explanatory purposes and describes only one of many ways to accomplish the specified task.]

In this use case the Consumer knows the user's language preference and chooses to specify it as part of the request for the Request Token. By specifying the language preference on this request, the Service Provider can either encode information into the request token or potentially dynamically generate an appropriate authorization URL. This last option requires the support by both the Consumer and Service Provider of dynamically generated authorization URLs.

The basic flow would be...

1. The user interacts with the Consumer in a way that allows the Consumer to know the user's language preference. It could also be that the Consumer only really supports a single language and wants the user's experience to all be in the same language.
2. When the user requests access to a resource that requires authorization with a Service Provider, the Consumer generates the request for the request token and adds the xoauth_lang_pref parameter to those being sent to the Service Provider.
3. The Service Provider receives the request for the Request Token and processes the xoauth_lang_pref parameter.
4. The Service Provider encodes the chosen language preference from those specified or it's own default and associates the language preference with the generated request token.
5. The Consumer receives the request token and generates the authorization URL and redirects the user to the authorization endpoint at the Service Provider.
6. The Service Provider processes the request token and retrieves the associated language preference.
7. The Service Provider uses this language preference to display the UI for the user to authorize the resource access request.

9.2.  Language preference as part of Authorization request

[The following flow is for explanatory purposes and describes only one of many ways to accomplish the specified task.]

In this use case, the Consumer knows the user's language perference but the Service Provider only supports acceptance of the xoauth_lang_pref parameter as part of the user authorization step. In handling the authorization request, the Service Provider will process the xoauth_lang_pref parameter and display the authorization UI in the "best effort match" of the user's specified language preference and those languages supported by the Service Provider.

The basic flow would be...

1. The user interacts with the Consumer in a way that allows the Consumer to know the user's language preference. It could also be that the Consumer only really supports a single language and wants the user's experience to all be in the same language.
2. When the user requests access to a resource that requires authorization with a Service Provider, the Consumer generates the request for the request token without specifying the xoauth_lang_pref parameter.
3. The Service Provider receives the request for the Request Token and processes per [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” December 2007.).
4. The Consumer receives the request token and generates the authorization URL also appending the xoauth_lang_pref parameter.
5. The Service Provider processes the request token and language preference parameter.
6. The Service Provider determines the "best effort match" of requested language preferences and Service Provider supported languages and uses that language to display the UI for the user to authorize the resource access request.

10. References

Author's Address