Home ›

Openid Token Exchange Protocol

Enable the Subscriptions block here!
Draft Version 5
by Praveen Alavilli, George Fletcher, and Srinivas Lingutla
Sep 21, 2007

Abstract

OpenID Token Exchange is an OpenID service extension that enables a Relying Party to receive authentication tokens from OpenID identity providers. The tokens can be used by the Relying Party to invoke services from Service Providers on behalf of the user.  The request and response messages are described in this document.


1. Definitions and Conventions

User:
Also referred to as "End User" or "Subject". A person with a digital identity who participates in OpenID-based identity information exchanges using their client software, typically a web browser or other user-agent.
OpenID Provider:
Also called "OP" or "Server". An OpenID Authentication server from which a Relying Party receives  an assertion that the end user controls an Identifier.
Relying Party:
Also called "RP" or "Consumer". A Web application that wants proof that the end user controls an Identifier, and requests identity data associated with the end user.
Application Identifier:
An opaque identifier obtained from OP by the Relying Party, by an out-of-band mechanism.
Authentication Token:
An opaque token, also called "Token", that is returned by the OP in a successful authentication response. The RP can use the Token to invoke services from service providers.
Service Provider:
An application that provides identity-based services after validating authentication tokens issued by OP.

2. Overview

The token exchange service extension is identified by the URI "http://openid.net/srv/token/1.0". This URI MUST be specified in the extension namespace declaration.

A Relying Party sends a get_token message and receives an authentication token in the response. The RP can then use the token to invoke identity-based services from a service provider on behalf of the user, without requiring the user to sign in again.  The service provider may require the user to provide consent for the successful completion of the service invocation from the RP.

A Relying Party "registers" with the OP using an out-of-band mechanism, prior to using the token exchange extension, and obtains an application identifier, called App ID. This application identifier is sent with every token exchange request.

The request parameters detailed here MUST be sent using OpenID extension mechanism.

3. Authentication Token Model

The Token Exchange service extension provides a mechanism for a Relying Party to obtain an authentication token and use it for service invocation at service providers.  The following entities are involved in the token exchange:

3.1 Application Identifier

An application identifier, or App ID, is obtained by an RP from an OP, using an out-of-band registration. The RP may be required to provide identifying credentials such as the name of the application, an url for the website, contact information, etc., during registration. The App ID is required to be passed to the service provider during each service invocation. 

3.2 Authentication Token

An authentication token, or Token, is returned by the OP to the RP in the response to the get_token request. The token is valid for a length of time, called the token expiry interval, after the token is issued by the OP. The length of time interval during which the token is valid is determined by the OP.

The authentication token enables an RP to invoke service from Service Providers without requiring the user to sign in again.

3.3 Service Provider

A Service Provider, also called "SP", is an application that provides identity-based services. A Relying Party can invoke services from a SP by sending the authentication token, along with the service-specific parameters. The SP validates the authentication token with the OP, before sending a successful service response to the RP.

3.4 Request Flow

The following diagram illustrates the sequence of events that occur during the authentication and service invocation.



Openid_token


The flow of requests for obtaining and using the authentication token is:

1. User enters OpenID url at the RP

2. RP sends checkid_setup or checkid_immediate request, including the get_token request parameters, to OP.

3. User authenticates at OP

4. OP returns authentication token, via a user agent redirect, to the RP

5. RP invokes a service from the SP with a server-to-server call.

  • 5a. the OpenID identity url, authentication token and RP's application id are sent as parameters in addition to service specific parameters
  • 5b. SP discovers the OP from the identity URL

6. SP validates the token by sending the validate_token message to the OP. 

  • 6a. If SP doesn't already have an association, SP gets an association handle from the OP by sending the OpenID associate request.
  • 6b. The authentication token, user's OpenID url,  SP's association handle are sent in the request to OP.
  • 6c. OP signs the response to the SP using the association identified by SP's association handle.

7. After validating token at OP, the SP returns user-specific data to RP in the response to the service request.

8. RP delivers a personalized page to the user


     When the user logs out at the RP site, the RP can send the invalidate_token message to the OP, which results in the authentication token being invalidated.

4. Messages

All OpenID Token Exchange messages MUST contain the following extension namespace declaration, as specified in the Extensions section of OpenID-Authentication-2.0:
openid.ns.<extension_alias>=http://openid.net/srv/token/1.0
The actual extension namespace alias should be determined on a per-message basis, and for the purposes of this document, the extension namespace alias for the attribute exchange service will be "tok".

4.1 get_token

4.1.1  Request Parameters

The  get_token message is used to obtain the token for the user, for the given Application ID. These parameters are sent with the checkid_setup or checkid_immeidate messages. The optional token_type parameter allows for different token types to be generated, for example, " SAML", "DEFAULT", etc. In the absence of a token type, the "DEFAULT" token type is returned.

Request parameters:

Parameter Name Value Required
openid.ns.tok "http://openid.net/srv/token/1.0" Y
openid.tok.mode "get_token" Y
openid.tok.token_type type of token N
openid.tok.app_id RP's application identifier Y
openid.trust_root RP's Trust root Y
openid.identity Identity Url Y

The following sample request shows request parameter values. 
openid.ns.tok=http://openid.net/srv/token/1.0
openid.tok.mode=get_token
openid.tok.app_id=AA83838jnndkakla
openid.trust_root=http://examplerp.com/
openid.identity=http://user.exampleidp.com/

4.1.2 Response

The response contains the authentication token and the expiry interval for the token. The following response parameters, in addition to the standard Openid parameters for an Openid checkid request, are sent

Parameter Name Value Required
openid.ns.tok "http://openid.net/srv/token/1.0" Y
openid.tok.mode "get_token_response" Y
openid.tok.token authentication token
 Y
openid.tok.expires_in_secs token expiry interval N


The following sample response illustrates the parameters sent in the response. 
openid.mode=id_res
openid.identity=http://user.exampleidp.com/
openid.assoc_handle=djueuajj23kkakd
openid.return_to=http://examplerp.com/login
openid.signed=identity,return_to,tok.status,tok.mode,ns.tok
openid.sig=jkd838jjklld02lk30dkd
openid.ns.tok=http://openid.net/srv/token/1.0
openid.tok.mode=get_token_response
openid.tok.token=/Adadds123adcs+1324333==
openid.tok.expires_in_secs=86400

4.2. validate_token

This message is used to validate an authentication token, and is typically called by the Service Provider. The authentication token, the application identifier, and the OpenID url that generated the token, are passed by the RP to the SP, during service invocation.

4.2.1 Request parameter

The request parameters include the application ID of the RP and the authentication token.

Parameter Name Value Required
openid.trust_root RP's Trust root Y
openid.ns.tok "http://openid.net/srv/token/1.0" Y
openid.tok.mode "validate_token" Y
openid.tok.app_id RP's application identifier Y
openid.tok.token authentication token Y
openid.assoc_handle SP's association handle  Y
openid.identity The OpenID for which the token was issued Y


The following sample request shows parameter values. 
openid.trust_root=http://examplerp.com/
openid.ns.tok=http://openid.net/srv/token/1.0
openid.tok.mode=validate_token
openid.tok.app_id=yewjudsyekw
openid.tok.token=/Adadds123adcs+1324333==
openid.assoc_handle=Y6363djd-djnenne=
openid.identity=http://dave.exampleidp.com/

4.2.2 Response parameter

The response parameters include the validity status of the token, and if the token is valid, the expiry interval for the token. The response parameters are sent in the body of the response as per the Openid key-value format.

Parameter Name Value Required
openid.ns.tok "http://openid.net/srv/token/1.0" Y
openid.tok.mode "validate_token_response" Y
openid.tok.valid "true" or "false"
 Y
openid.tok.expires_in_secs token expiry interval Y
openid.tok.issued_time when token was issued Y
openid.assoc_handle The assoc used for signature Y
openid.signed list of fields in signature Y
openid.sig signature Y

The following sample response illustrates the parameters sent in the response. 
openid.ns.tok=http://openid.net/srv/token/1.0
openid.tok.mode=validate_token_response
openid.tok.valid=true
openid.tok.expires_in_secs=86201
openid.tok.isued_time=1142636386201
openid.tok.assoc_handle=dhsjhds-sdddjs
openid.tok.signed=identity,tok.mode,tok.valid,tok.expires_in_secs,tok.issued_time
openid.tok.sig=dsfkdsjkjfwiew

4.3. invalidate_token

This message is used to invalidate the token and is typically called when a user signs out at the RP.  If the return_to parameter is present, the user is redirected to that url. Otherwise, the response parameters are sent in the body of the response as per the Openid key-value format.

4.3.1 Request parameter


Parameter Name Value Required
openid.trust_root RP's Trust root Y
openid.return_to RP's return url N
openid.ns.tok "http://openid.net/srv/token/1.0" Y
openid.tok.mode "invalidate_token" Y
openid.tok.app_id RP's application identifier Y
openid.tok.token authentication token Y
openid.assoc_handle Association handle Y

The following listing shows a sample request message. 
openid.trust_root=http://examplerp.com/
openid.ns.tok=http://openid.net/srv/token/1.0
openid.tok.mode=invalidate_token
openid.tok.app_id=AbHGFTre126-dkdnen3135reXY
openid.tok.token=/Adadds123adcs+1324333==
openid.assoc_handle=jdjksjdAdadds123adcs+1324333==

4.3.2 Response parameters

The response parameter "openid.tok.valid"  is set to "true" if the token invalidation is successful, else set to "false".

Parameter Name Value Required
openid.ns.tok "http://openid.net/srv/token/1.0" Y
openid.tok.mode "invalidate_token_response" Y
openid.tok.status "ok" or "fail"
 Y
openid.signed list of fields in signature
openid.sig signature

The following sample response illustrates the parameters sent in the response. 
openid.ns.tok=http://openid.net/srv/token/1.0
openid.tok.mode=invalidate_token_response
openid.tok.status=ok
openid.signed=tok.status,tok.mode
openid.sig=Y6360kdjlandpoew==

5. Security Considerations

The mechanism used for ensuring the integrity of the communication between the RP and SP is determined by the SP, and is not addressed in this document. It is recommended that the https protocol and signatures generated with shared secret key be used for communication between the RP and SP.
» Submitted by wjhamerman on September 21, 2007 - 12:34pm.