OpenID Connect (OIDC)

Wristband utilizes the OIDC protocol to authenticate your application's users. While the OIDC specification defines three different authentication flows: Authorization Code Flow, Implicit Flow, and Hybrid Flow, Wristband only supports the Authorization Code Flow. The Implicit Flow and Hybrid Flow are not supported mainly to avoid the security risks inherent in passing the access token directly in the authorization response.

Authorization Code Flow Endpoints

The Authorization Code Flow uses three endpoints to authenticate users: the Authorization Endpoint, Token Endpoint, and UserInfo Endpoint.

Authorization Endpoint

To begin the authentication process, an application must redirect to the Authorization Server's authorize endpoint. For Wristband, each tenant has a unique authorization endpoint with a URL pattern of https://{tenant_qualified_domain}.us.wristband.dev/api/v1/oauth2/authorize.

After redirecting to the Wristband tenant's authorization endpoint, the user will be presented with a login page hosted by Wristband. The login methods and branding that appear on the login page depend on the tenant's configurations. Once the user has completed the login flow, Wristband will redirect to the application's callback endpoint specified in the authorization request.

You can learn more about the Wristband Authorization Endpoint in our API Reference.

Token Endpoint

After Wristband redirects to the application's callback endpoint, the application then needs to retrieve the user's security tokens by calling the Token Endpoint. The Token Endpoint will always return two tokens: an access token and an ID token. The access token grants users access to specific resources, while the ID token contains claims describing the user that authenticated and what methods they used to authenticate. Also, if the offline_access scope was specified in the authorization request, a refresh token will be returned in the token response. The refresh token can be used to retrieve a new access token when it expires without requiring the user to authenticate again.

You can learn more about the Wristband Token Endpoint in our API Reference.

UserInfo Endpoint

Once the access token has been retrieved from the Token Endpoint, additional information regarding the authenticated user can be fetched by calling the UserInfo Endpoint. The claims returned in the UserInfo response depend on the scopes specified in the authorization request.

📘

Why Are the Claims Not in the ID Token

The OIDC spec says that if an access token is returned from the /token endpoint, then the scope claims should be returned in the UserInfo Endpoint response and not in the ID token:

"The Claims requested by the profile, email, address, and phone scope values are returned from the UserInfo Endpoint, as described in Section 5.3.2, when a response_type value is used that results in an Access Token being issued. However, when no Access Token is issued (which is the case for the response_type value id_token), the resulting Claims are returned in the ID Token."

Wristband always returns an access token, so the scope claims are always returned in the UserInfo Endpoint response and not in the ID token.

You can learn more about the Wristband UserInfo Endpoint in our API Reference.

OAuth 2

In addition to authenticating end users, Wristband also supports authenticating machines. Machine authentication is handled using the OAuth 2 Client Credentials grant. In this flow, the client ID and client secret are passed directly to the Token Endpoint. The Token Endpoint response will contain an access token corresponding to the authenticated client. The client can then use this access token to access protected resources on its own behalf. If the access token expires, the client can retrieve a new access token by calling the Token Endpoint again with its credentials.