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¶

Authentication: Authentication of users is not part of this flow
Authorization: The client exchanges a user's external token for an access token
Accessing protected resources: The client accesses the Tapkey Web APIs (e.g. the Tapkey Access Management Web 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",
  "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 Tapkey Web APIs (e.g. call the Tapkey Access Management Web 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.

Tapkey Web APIs¶

The following snippet demonstrates an exemplary call to the Tapkey Access Management Web 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.

Android

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.