Securing API Requests With Access Tokens
Learn how to secure your backend APIs using Wristband access tokens, including JWT signature verification, and token claim validation.
Overview
Access tokens provide a secure, stateless way to authenticate requests to your backend APIs. Wristband issues access tokens as JSON Web Tokens (JWTs), which can be included in the Authorization request header using the Bearer authentication scheme.
Using access tokens to authenticate API requests offers several benefits:
-
Stateless Authentication: Access tokens contain claims about the authenticated user or machine, allowing backend APIs to validate requests without maintaining server-side session state.
-
Cross-Domain Support: Access tokens can be used to authenticate requests across different domains without relying on browser cookies. For browser-based clients, the API must also be configured to allow the necessary cross-origin requests through CORS.
-
Client Flexibility: Access tokens can be used by different types of clients, including web applications, mobile applications, and backend services.
Access Tokens Are Not a Replacement for Session CookiesFor applications that use a backend server, we recommend using session cookies to maintain authentication between the browser and your backend. Properly configured
HttpOnly,Securesession cookies prevent client-side JavaScript from directly accessing session credentials and allow the backend to manage session expiration and revocation.Access tokens are better suited for authenticating requests between services or to backend APIs that require token-based authentication. Your backend can securely store access tokens in the user's session and use them when calling protected APIs.
Access Token Validation
To secure your backend APIs using Wristband access tokens, you must validate each incoming token before processing the request.
This is typically handled by JWT validation middleware that performs the following steps:
- Extract the access token from the
Authorizationheader. - Verify the token's cryptographic signature.
- Validate the token's claims.
Once the token has been validated, your application can identify the authenticated user or machine and perform any additional authorization checks required to access the requested resource.
Extract the Access Token
The first step is to extract the access token from the incoming request's Authorization header.
The header must use the Bearer authentication scheme, with the access token provided after the Bearer keyword:
Authorization: Bearer <access_token>If the header is missing, malformed, or does not contain a valid bearer token, the request should be rejected with a 401 Unauthorized response.
Verify the Token Signature
Wristband access tokens are JWTs consisting of three Base64URL-encoded components separated by dots (.):
<header>.<payload>.<signature>- Header: Contains metadata about the token, including its type, signing algorithm, and signing key identifier.
- Payload: Contains claims describing the authenticated subject and other token metadata.
- Signature: Cryptographically verifies the token's integrity and authenticity.
The following is an example JWT header for a Wristband access token:
{
"kid": "qtott5t4fvau7lp3zk5dizbpju",
"typ": "at+JWT",
"alg": "RS256"
}The header contains three important fields:
| Field | Description |
|---|---|
kid | Identifies the public signing key used to verify the token's signature. |
typ | Identifies the token type. Wristband access tokens use at+JWT. |
alg | Identifies the signing algorithm. Wristband access tokens use RS256. |
To verify an access token's signature:
- Decode the JWT header and verify that
typisat+JWTandalgisRS256. - Retrieve the public signing key identified by
kidfrom Wristband's JWKS Endpoint. - Use the public key to verify the JWT signature using the RS256 algorithm.
The JWKS Endpoint exposes the public signing keys associated with your Wristband application. These keys can be cached locally to avoid retrieving them for every request. When caching the keys, set a reasonable expiration time so that keys that are rotated out don't stay in the cache forever.
Signature verification ensures the token was signed using a trusted key and has not been modified. However, a valid signature alone does not mean the token should be accepted. You must also validate its claims.
Use Wristband's JWT Validation SDKsRather than implementing JWT signature verification yourself, use one of Wristband's JWT Validation SDKs. These SDKs handle signature verification and help simplify the token validation process.
Validate Token Claims
After verifying the token's signature, your API must validate the claims contained in its payload.
At a minimum, validate the following claims:
| Claim | Validation |
|---|---|
iss (Issuer) | Must exactly match the expected issuer URL for your Wristband application. |
exp (Expiration) | Must be later than the current time to ensure the token has not expired. |
Issuer Validation (iss)
iss)The iss claim identifies the Wristband application that issued the token. Your API must verify that its value exactly matches the expected issuer URL.
The issuer URL depends on your application's domain configuration:
- Default Application Vanity Domain: If your application does not have an active custom domain, the issuer uses the default application vanity domain (e.g.,
https://yourapp-yourorg.us.wristband.dev). - Application Custom Domain: If your application has an active custom domain, the issuer uses that custom domain instead (e.g.,
https://auth.yourapp.com).
Your API should perform a strict string comparison against the expected issuer URL to ensure the token was issued by the correct Wristband application.
Expiration Validation (exp)
exp)The exp claim specifies when the access token expires, represented as a Unix timestamp in seconds.
Your API must verify that the current time is earlier than the token's expiration time. Expired tokens must be rejected.
Additional Claim Validation
Depending on your application's security requirements, you may also want to validate additional claims:
| Claim | Description |
|---|---|
app_id | Verify that the token belongs to the expected Wristband application. |
tnt_id | Verify that the token is associated with a tenant the caller is authorized to access. |
sub_kind | Verify that the subject type (user, application_client, or tenant_client) is permitted to access the API. |
client_id | Verify that the token was issued to an authorized OAuth2 client, if your API restricts access to specific clients. |
For more information about the claims contained in Wristband access tokens, see the JWTs and Signing Keys documentation.
If any required validation fails, your API should reject the request with a 401 Unauthorized response.
Updated 16 days ago