OAuth2 Clients

Wristband uses the OIDC protocol to authenticate users and the OAuth 2 Client Credentials grant to authenticate machines. Therefore, OAuth2 clients are required to initiate any authentication request to Wristband. In Wristband's model, an application can have multiple OAuth2 Clients that are allowed to initiate authentication requests. For example, a Wristband application could have a backend server OAuth2 Client for authenticating users from their web app while also having a native OAuth2 client for authenticating users from their mobile app. Additionally, a Wristband application could have machine-to-machine OAuth2 Clients for software that requires authentication without user involvement.

OAuth2 Clients can be created at either the application level or the tenant level. The right choice depends on your specific use case.

• Application-Level Clients: Used by your application to authenticate users and to allow your own machines to authenticate without user involvement.
• Tenant-Level Clients: Used by your customers to authenticate calls to your application's APIs.

Client Types

Each OAuth2 Client in Wristband has a type associated with it. The type of client affects how authentication requests are made to Wristband, so it's essential to choose the right client type for your use case. There are three types of clients that Wristband supports:

• Backend Server
• Native
• Machine-to-Machine

These client types are categorized as either public or confidential based on their ability to handle credentials securely:

In addition to being classified as public or confidential, OAuth2 Clients can differ in several other ways. The sections below provide a detailed overview of the different client types and their key features.

Backend Server Client Type

Backend server clients are intended for web applications running on a server. As confidential clients, they have a client ID and a secret, which must be stored securely on the backend. All authentication requests to Wristband should originate from the backend server.

Supported Grant Types

Backend server clients support the following grant types:

• Authorization Code: The authorization code grant is used when authenticating users.
• Client Credentials: The client credentials grant can be used to authenticate the client itself.

Native Client Type

Native clients are designed for software that runs directly on a device, such as a mobile phone or desktop computer. Because they are public clients and cannot securely store a client secret, they can only authenticate users. To initialize the authentication request, the native application must open a browser and redirect to Wristband's authorization endpoint. This will then trigger Wristband's hosted login page to render in the browser. Once the user completes the login flow, Wristband will redirect to the client's registered redirect URI. From that point, the native application can call Wristband's APIs directly.

Supported Grant Types

Native clients support the following grant types:

• Authorization Code With PKCE: The authorization code grant is used when authenticating users. For native clients, PKCE is required.

Unique Features

Native clients support several features that are not available to other client types. These include:

• Support for Custom Schemes in Redirect URIs: Native clients can register custom URL schemes (e.g., yourapp.com://) as redirect URIs. These schemes enable the browser to launch the native app when the redirect occurs.
• Support for Loopback Addresses in Redirect URIs: Native clients can register redirect URIs using valid loopback addresses such as localhost or 127.0.0.1.
• Support for Dynamic Ports in Redirect URIs: Dynamic ports can be used in redirect URIs using a valid loopback address, allowing them to handle redirects using an ephemeral local server running on a randomly assigned port. To use dynamic ports, leave off the port number when registering the client's redirect URI. Then, when calling Wristband's Authorize API, you can specify any port number in the redirect_uri query parameter.

Machine-to-Machine (M2M) Client Type

Machine-to-Machine clients are used for authenticating software processes that operate on their own behalf. For example, M2M clients can be used to authenticate backend microservices or scheduled background tasks. As confidential clients, they have a unique client ID and a secret, which should be stored securely on the machine. M2M clients can authenticate themselves by calling Wristband's Token Endpoint directly using the client_credentials grant.

Supported Grant Types

M2M clients support the following grant types:

• Client Credentials: The client credentials grant is used to authenticate the client itself.

URLs

Backend Server and Native clients support two URL-related settings: Login URL and Redirect URIs.

Redirect URIs

Redirect URIs are the list of registered URIs that can be used as part of the Authorization Code grant type flow. Wristband only redirects to URIs that have been explicitly registered, which prevents the authorization code from being sent to an unauthorized destination.

To support applications that use tenant subdomains, the {tenant_name} placeholder can also be used in redirect URIs as the left most domain label. For example:

https://{tenant_name}.myapp.com/callback

When calling the Authorize API, you provide the redirect URI with the {tenant_name} placeholder without substituting the actual tenant name. For example:

https://<tenant_vanity_domain>/api/v1/oauth2/authorize?...&redirect_uri=https://{tenant_name}.myapp.com/callback...'

After the user has successfully authenticated, Wristband will replace the {tenant_name} placeholder with the user's actual tenant name before performing the redirect. For example, if the user belonged to tenant1, then Wristband would redirect to the following URL after the user authenticated:

https://tenant1.myapp.com/callback

Login URL

During certain authentication flows there are times when Wristband needs to redirect back to your application's Login Endpoint. By default, Wristband will redirect to the Login URL defined on the application; however, this can be overridden at the client level. When a client has its own Login URL set, users authenticating through that client will be sent to the client's Login URL instead of the application's. This can be useful if you have clients running in different environments, so you need to redirect to different Login Endpoints depending on which client invoked the authentication flow.

For client Login URLs, the {tenant_name} placeholder can be used as the left-most domain label. If the {tenant_name} placeholder is present, it will be substituted with the current tenant's name when Wristband performs the redirect.

Client Secrets

When a confidential client is created, a secret will be generated for it. When calling the following Wristband APIs, the client ID and secret must be passed in the Authorization header of the request using the Basic authentication scheme:

• Create Tokens
• Introspect Token
• Revoke Token

Wristband only stores the hashed version of the secret, so the plaintext version of the secret can only be viewed once after the client is first created. Therefore, after creating the client, you'll need to record the client secret and store it in a secure location. If you forget the client secret, you can rotate it to generate a new one.

Verifying a Client Secret

If you're unsure whether a client secret value you have is still valid, you can check it against Wristband. This can be done either in the Wristband Dashboard or programmatically using the Verify Client Secret API.

Secret Rotation

Rotating a client secret generates a new one and sets it as the primary. The previous primary becomes the secondary. Both secrets (primary and secondary) remain valid, enabling both to be used while clients are migrated. This can be done either in the Wristband Dashboard or programmatically using the Rotate Client Secret API.

Deleting a Secondary Client Secret

Once all clients are updated to use the new primary secret, the secondary can be safely deleted. Deleting a secondary secret is permanent and immediately invalidates it. This can be done either in the Wristband dashboard or programmatically using the Delete Secondary Client Secret API.

Generating Access Tokens for Testing

If you want to call Wristband APIs with tools like cURL or Postman, you can generate an access token directly from a client's Edit Client page in the dashboard. For a full walkthrough, refer to Getting Access Tokens to Test Wristband APIs.

JWT Settings

JWT Settings let you configure how long the tokens issued to a client remain valid: the access token, the OpenID ID token, and the refresh token.

Login Session Duration

When an application initiates a user login flow, by calling the Authorize API, Wristband creates an authorization request JWT containing the original request parameters that is propagated throughout the login flow. The Login Session Duration controls how long that authorization request JWT remains valid, in other words, how long a user has to complete the login flow before it expires. If Login Session Durations are enabled, Wristband's hosted login pages will force the user to restart the login flow if the login session expires.

The following Login Session Duration settings are available for Backend Server and Native clients:

• Restrict Time to Complete Login: Whether login must be completed within a fixed time window. Off by default, meaning users have unlimited time to complete login.
• Login Session Duration: How long users have to complete login, once the restriction is enabled. Defaults to 60 minutes, with an allowed range of 30 to 60 minutes.

Assigning Roles to Clients

Like users, clients can be assigned roles to enforce authorization within your application. When a client uses an access token issued through the client credentials grant to call Wristband APIs, it must have a role that grants the necessary permissions.

Listed below are the various methods available for assigning roles to clients.

• Manually via the Wristband Dashboard: Administrators can manually assign roles to a client through the Wristband dashboard.
• Programatically via Wristband's APIs: The following APIs can be used to manage the roles assigned to clients programmatically:
  • Assign Roles To Client API
  • Unassign Roles From Client API
  • Update Client Roles Assignments API