Application-Level Clients

Application-level OAuth2 Clients are used by your application to initiate authentication requests to Wristband. They can authenticate your application's users as well as non-human identities, depending on the client type.

The following types of clients can be created at the application level:

• Backend Server
• Native
• Machine-to-Machine

A single application can have multiple client types configured to support a variety of different authentication use cases. Also, clients configured at the application level can be used to authenticate users across all tenants belonging to the application.

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.

---

Managing Application Clients With Wristband's Dashboard

The Wristband dashboard provides a comprehensive set of tools for managing your application's clients. The sections below highlight the dashboard's core client management features.

Adding a Client

To add a new client, go to "OAuth2 Clients" from the left navigation menu in Application View, then click the "+ Add Client" button.

Select a client type (Backend Server, Machine (M2M), or Native), enter a name for the client, and then click the "Create" button.

If you selected Backend Server or Machine (M2M), you'll be shown the client's clientId and clientSecret. Wristband only stores the hashed version of the secret, so record the plaintext secret securely at this time since it won't be shown again.

When a client is first created, it has no roles assigned yet (relevant for Backend Server and Machine-to-Machine clients), and no Redirect URIs are set yet (relevant for Backend Server and Native clients). To configure either of these, you'll need to edit the client's configuration, covered in the sections below.

Editing an Existing Client

You can edit a client by clicking "OAuth2 Clients" from the left navigation menu and then clicking the client you want to edit from the clients table.

Configuring Client Settings

The Client Settings section lets you configure the client's Name, Description, and Redirect URIs.

Expanding "Advanced Settings" reveals additional configuration. Note, this section never appears for Machine-to-Machine clients.

• Enable Refresh Token Grant Type: Allows this client's users to obtain new access tokens using a refresh token instead of re-authenticating.
• Enable Client Credentials Grant Type: Allows this client to authenticate itself directly using the Client Credentials grant, letting it call Wristband's APIs on its own behalf. This configuration only applies to Backend Server clients, since Native clients can't authenticate themselves since they don't have a secret.
• Restrict Time to Complete Login: Whether user logins must be completed within a fixed time window. If this configuration is disabled it means users have unlimited time to complete the login flow.
• How Long Should Users Have to Complete Login: Can only be configured once "Restrict Time to Complete Login" is enabled. Max expiration: 60 minutes.
• Login URL: Optionally overrides your application's Login URL. Authentication flows using this particular client will redirect to the client's Login URL instead of the application's Login URL.

Configuring JWT Settings

To configure how long the tokens issued to this client remain valid, scroll down to the "JWT Settings" section.

Assigning Roles to a Client

To assign roles to the client, scroll down to the "Roles" section. There, you'll see a multi-select dropdown that can be used to modify the roles assigned to the client.

Validating a Client's Secret

If you're unsure whether a client secret value you have is still valid, scroll down to the "Client Secret Settings" section, enter your secret value, and click the "Validate" button.

Rotating a Client's Secret

To rotate a client's secret, scroll down to the "Client Secret Settings" section and click the "Rotate" button next to the Primary Client Secret.

Rotating secrets generates a new primary secret in place of the current one. The current secret becomes the secondary client secret, and both remain valid for authenticating the client. If a secondary secret already exists, it will be permanently deleted.

To confirm, type "rotate" and click the "Rotate" button.

You'll then be shown the new client secret. Record it securely, since it won't be shown again.

Once the new secret has been rolled out everywhere it's needed, you can permanently remove the old secondary secret by clicking "Delete" next to the Secondary Client Secret.

Deleting a secondary secret can't be undone, and it immediately stops working for authenticating the client. To confirm, type "delete" and click the "Delete" button.

Deleting a Client

Scroll to the bottom of the Edit Client page to the "Delete This Client" section, then click the "Delete" button. Once the client is deleted it can no longer be used to authenticate users or machines.

Deleting a client is permanent and can't be undone. To confirm, type "delete" and click the "Delete" button.

Generating Access Tokens

If you want to test calling Wristband APIs manually with tools like cURL or Postman, you can generate an access token for the client directly from the Edit Client page. Scroll down to the "Generate Access Tokens" section, paste in the client secret, and click the "New Token" button.

You'll be shown the access token. Copy it somewhere safe, since it won't be shown again.