Authorization Code¶

Section 4.1 of the RFC 6749 describes the Authorization Code grant type as optimized for confidential clients. In a nutshell: Clients using this grant type must not expose their source code to the public. They are written using a server-side language such as C#, Python or Java and are Web Applications most of the times.

Why is this important?

During the authentication/authorization process, clients using the Authorization Code grant type must send their credentials (client ID and secret) when communicating with the authorization server. If a client cannot hold its credentials securely, this grant type is not suited for it. Clients like mobile apps or native apps are exposed to attacks because potential malicious users could either steal the credentials or the code returned and then use it to get an access token. For these clients, consider using the Authorization Code with PKCE grant type.

The Authorization Code Flow¶

Authentication: Users are redirected to request their Tapkey identity and to negotiate scopes
Authorization: The client exchanges an authorization code for an access token
Accessing protected resources: The client accesses the Tapkey Web APIs (e.g. the Tapkey Access Management Web API) with the user's access token

Authentication¶

RFC 6749

This step corresponds with section 4.1.1 of the OAuth 2.0 Authorization Framework standard.

The client application redirects to Tapkey's authorization endpoint located at

GET https://login.tapkey.com/connect/authorize

with the following query string parameters using the application/x-www-form-urlencoded format

Name	Description
`client_id`	Required. The client ID as issued during the Tapkey OAuth client application process.
`redirect_uri`	Required. The URL in the client application where users will be sent after authorization.
`response_mode`	Can be `query` or `form_post`. Defaults to `query`.
`response_type`	Required. Must be set to `code`.
`scope`	Required. A space delimited list of scopes. The available scopes can be found in the Scopes page.
`state`	An unguessable random string. It is used to protect against cross-site request forgery attacks.¹ Typically 32 bytes long.

Authorization¶

RFC 6749

This step corresponds with section 4.1.3 of the OAuth 2.0 Authorization Framework standard.

If the user accepts the client's request to gain access to selected resources, Tapkey's authorization server redirects the user back to the client with a temporary authorization code in a code parameter as well as the state provided in the previous step in a state parameter. If the states don't match, the process must be aborted. The redirect furthermore contains a scope parameter, that reflects the selection of scopes the user has actually granted. The code can then be exchanged for an access token (for accessing the Tapkey API²) using the token endpoint

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.
`client_secret`	Required. The client secret as issued during the Tapkey OAuth client application process.
`code`	Required. The authorization code obtained during the Authentication phase.
`grant_type`	Required. Must be set to `authorization_code`.
`redirect_uri`	Required. The same URL used during the Authentication phase. See below more details

The client is returned an access token in exchange.

RFC 6749 - Redirect URI on token request

According to section 4.1.3. the redirect_uri parameter is required if it was included in the authorization request. Since the authorization server requires the redirect URI during the authorization request it must be sent also during the token request. This adds an extra layer of security as the authorization server will enforce them to match.

RFC 6749

According to section 4.1.3., the client_secret parameter is optional. However, for reasons of security, Tapkey requires client_secret to be present in any token request for authorization_code clients.

Refreshing an access token¶

RFC 6749

This step corresponds with section 6 of the OAuth 2.0 Authorization Framework standard.

Access tokens are issued by Tapkey with limited lifetime only (1 hour, subject to change). After an access token has expired, it can no longer be used to access the resource server. Doing so will result in a 401 - Unauthorized response. In this case, the client has to either run through the entire process described above again or, if repetitive user interaction is undesirable, a refresh token can be used to retrieve a new access token from the authorization server.

The refresh token can be used to retrieve an access token using the token endpoint

POST https://login.tapkey.com/connect/token

with the following parameters:

Name	Description
`client_id`	Required. The client ID as issued during the Tapkey OAuth client application process.
`client_secret`	Required. The client secret as issued during the Tapkey OAuth client application process.
`grant_type`	Required. Must be set to `refresh_token`.
`refresh_token`	Required. The refresh token issued to the client.
`scope`	The scope of the access request as described by section 3.3 The requested scopes MUST NOT include any scope not originally granted by the resource owner, and if omitted is treated as equal to the scope originally granted by the resource owner.

Important

To be able to get refresh tokens, your application must request the offline_access scope during the Authentication request.

The authorization server uses sliding expiration semantics for refresh tokens. This means refresh tokens are issued with a lifetime of 90 days. Every time you call the token endpoint using the Refresh Token grant type, you'll get:

A new access_token valid for 1 hour
The same refresh_token that was passed. Replacing the existing refresh token even though it is the same is good practice.
The lifetime of the refresh token is now + 90 days.

This gives clients a good flexibility to get new access tokens without having to make the users go through the same process again. If your app does not call the token endpoint in 90 days, your refresh token will expire. In this case, the whole flow has to be initiated again.

Storing refresh tokens in a secure way

Refresh tokens offer a convenient way of retaining an up-to-date access token without having to interact with the end user. Because refresh tokens are long lived entities, it is the client's obligation to store them in a secure way.

The following snippet shows an exemplary response of a token refresh request:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ij...j8vltwIXCCxGV2D9xm82tx-A",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "4a4a8fb5c4ef170a9e07e30a2f5...f1dc4f955d72c77e1ceb76ff2e1"
}

Accessing Protected Resources¶

Tapkey Access Management Web API¶

After obtaining an access token, it can be used to call the Tapkey Access Management Web API to manage grants, view logs or query the users locking devices. Take a look at the Operations section to see all the endpoints available.

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

will return the authenticated user's details, e.g.:

{
  "ownerAccounts": ...,
  "ownerAccountPermissions": ...,
  "id": "9da7db0a-....-....-....-1c81a6060daf",
  "ipId": "com.auth0"
}