OAuth Extenstion for Specifying User Language Preference - Draft 1

Abstract

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

Table of Contents

1.  Notation and Conventions
2.  Definitions
3.  Description
4.  Parameter Specfication
5.  Extension Identifier
6.  Processing Rules
7.  Examples
8.  Possible Use Cases
    8.1.  Language preference as part of Request Token request
    8.2.  Language preference as part of Authorization request
9.  References
§  Authors' Addresses

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

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

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

4.  Parameter Specfication

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.

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.

5.  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, the URI may be included in the Discovery spec for the service provider. If using the Discovery specification, the extension identifier MUST only added to the request_token and authorization endpoints.

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

6.  Processing Rules

The Consumer may specify the language preference of the user by adding the xoauth_lang_pref parameter to either the request token request or the user authorization request.

If a Service Provider specifies that it supports the language preference extension, it MUST process the xoauth_lang_pref parameter.

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 RFC 2616, section 14).

If the Service Provivder can not provide the UI in the perferred language, then the Service Provider's default language should be used.

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

8.  Possible Use Cases

8.1.  Language preference as part of Request Token request

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

8.2.  Language preference as part of Authorization request

TODO: This section still to be written.

9. References