OAuth 2 Clients

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

In the sections below, we'll cover key concepts regarding OAuth 2 Clients.

Client Types

Each 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 for your use case. There are three types of clients that Wristband supports:

• Backend Server
• Native
• Machine-to-Machine

These client types are grouped into two main classifications based on their ability to handle credentials securely:

In addition to being classified as public or confidential, 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 localhost in Redirect URIs: Native client can register redirect URIs using localhost.
• Support for Dynamic Ports in Redirect URIs: Native clients support dynamic ports in redirect URIs, allowing them to handle redirects using a transient local server running on a randomly assigned port. To use dynamic ports, leave off the port number when registering the client's redirect URI. Now, when calling Wristband's Authorize API, you can specify any port number in the URL provided to 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.

Client Secrets

When a public 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
• Instrospect 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.

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. Once all clients are updated to use the new primary secret, the secondary can be safely deleted.

Application-Level vs. Tenant-Level Clients

In Wristband, OAuth 2.0 clients can be created at either the application level or the tenant level. The right choice depends on your specific use case. In the sections below, we’ll explore the scenarios where each type is most appropriate.

Application-Level Clients

Application-level clients are used by your application to initiate authentication requests to Wristband. These clients are meant to authenticate users accessing your application. However, you can also create application-level Machine-to-Machine (M2M) clients to authenticate autonomous processes without user interaction.

ℹ️

Note

A single application-level client can be used to authenticate users across all tenants that belong to the application that client is associated to.

Supported Client Types

Listed below are the types of clients that can be created at the application level:

• Backend Server
• Native
• Machine-to-Machine

Tenant-Level Clients

Tenant-level clients are intended to be used by your customers in order to acquire an access token that can be used to call your application's APIs. Your application APIs can then verify the access tokens provided in the request to authenticate the tenant clients.

Supported Client Types

Listed below are the types of clients that can be created at the tenant level:

• Machine-to-Machine

Example Scenarios

Web Application + Mobile

Let's imagine you have an application that your users can access by the following methods: a web application in their browser served by NextJS, an Android app, and an iOS app. You would configure an OAuth2 Client for each of those three different interfaces to your application. Each OAuth2 Client can initiate authentication requests for all users under the application.

Backend Microservices

If your application is implemented using a microservice architecture, you can create an application-level M2M client for each microservice to authenticate requests between services.