Openid Token Exchange Protocol

Abstract

• 1. Definitions and Conventions
• 2. Overview
• 3. Authentication Token Model
• 3.1 Application Identifier
• 3.2 Authentication Token
• 3.3 Service Provider
• 3.4 Request Flow
• 4. Messages
• 4.1 get_token
  • 4.1.1  Request Parameters
  • 4.1.2 Response
• 4.2. validate_token
  • 4.2.1 Request parameter
  • 4.2.2 Response parameter
• 4.3. invalidate_token
  • 4.3.1 Request parameter
  • 4.3.2 Response parameters
• 5. Security Considerations

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.

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

4. Messages

openid.ns.<extension_alias>=http://openid.net/srv/token/1.0

4.1 get_token

4.1.1  Request Parameters

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

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

4.2.1 Request parameter

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

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

4.3.1 Request parameter

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

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