Token Exchange

Section 4.5 of RFC 6749 allows the authorization server to define additional, custom grant types. The Token Exchange grant type is a Tapkey-specific flow that allows third-party apps to exchange tokens from external identity providers for an access token that can be used to access the resource server.

External identity providers must be registered with Tapkey beforehand and external tokens must have a specific format.

The Token Exchange Flow

  1. Authentication: Authentication of users is not part of this flow
  2. Authorization: The client exchanges a user's external token for an access token
  3. Accessing protected resources: The client accesses the resource server (e.g. Management API, Mobile SDK) with the user's access token

Authentication

Authentication is not part of the Token Exchange grant type. Instead, clients will have to take care of authenticating users with an external identity provider, that has been registered with Tapkey beforehand and is capable of issuing tokens (referred to as external token in this document) which can be exchanged for an access token.

Authorization

Internet-Draft for OAuth 2.0 Token Exchange

Authorization is similar to the proposal in the OAuth 2.0 Token Exchange draft, section 2.

The external token issued by the external identity provider (registered with Tapkey beforehand) is exchanged for an access token that can be used to access the resource server.

POST https://login.tapkey.com/connect/token
with the following parameters using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the request body:

Name Description
client_id Required. The client ID as issued during the Tapkey OAuth client application process.
grant_type Required. Must be http://tapkey.net/oauth/token_exchange.
provider Required. The ID of the identity provider as assigned during identity provider registration.
scope Required. A space delimited list of scopes. The available scopes can be found here.
subject_token_type Required. The type of the external token. Must be jwt.
subject_token Required. The external token to exchange for an access token.
audience Optional. The audience of the token is requested for. If present, must be tapkey_api.
requested_token_type Optional. Can be used to specify the type of the requested token. If present, must be access_token.

The following snippet shows an exemplary response of a token request using the Token Exchange grant type:

{
  "access_token": "eyJhbGciOiJSUz...O-YbBq8F7086rQi-kEbERp4dA3r0WonpHnmYcXEnA",
  "issued_token_type": "access_token",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Refreshing an Access Token

The authorization server will never issue a refresh token for the Token Exchange grant type. When an access token issued through the Token Exchange grant type reaches the end of its lifetime, the client must carry out a new token request to retrieve a new access token. The access token's lifetime will match the lifetime requested in the external token.

Accessing Protected Resources

The obtained access token can be used to access the resource server (e.g. call the Management API or authenticate users in the Tapkey Mobile SDK).

Hint

Any interaction with Tapkey on behalf of a user originating from an external identity provider is only possible after the external user has been registered with Tapkey as described in the working with users section of the identity provider page.

Management API

The following snippet demonstrates an exemplary call to the Management API, requesting additional user information.

RFC 6750

The authorization method used in this example is specified in section 2.1 of RFC 6750.

GET https://my.tapkey.com/api/v1/auth/auth/userinfo

Authorization: Bearer eyJhbGciOiJSUz...O-YbBq8F7086rQi-kEbERp4dA3r0WonpHnmYcXEnA

Mobile SDK

The following snippet demonstrates how to log in a user in the Tapkey Mobile SDK using the access token retrieved through the Token Exchange flow.

UserManager userManager = tapkeyServiceFactory.getUserManager();
userManager.logInAsync("eyJhbGciOiJSUz...O-YbBq8F7086rQi-kEbERp4dA3r0WonpHnmYcXEnA", ct)
    .continueOnUi(userId -> {
        // User logged in, use user's ID here.
    });

Scopes for the Mobile SDK

Make sure the Token Exchange OAuth client is allowed to request the relevant scopes for working with the Mobile SDK, and that they are included in your token request.