OAuth2 and OpenID Connect (OIDC)
Here, we'll cover at a high level how Wristband provides authentication for your application via the OAuth2 and OpenID Connect (OIDC) protocols.
OAuth2
OAuth2 is the prevailing industry protocol for facilitating secure access to APIs. This open authorization framework enables applications to access resources from other applications on a user's behalf while safeguarding user credentials. OAuth serves as the foundation for third-party developers to seamlessly integrate with other identity providers for user authentication (e.g., social login with Google).
In OAuth terms, Wristband serves as your application's authorization server. Your application, which can consist of one or more OAuth Clients, interacts with Wristband to handle authentication for users of your application. When users perform an authorization request with Wristband (also known as authenticating, or logging in), the process is considered first-party from the perspective of the developer as opposed to being third-party.
Wristband generates access tokens for API authorization scenarios in the JSON Web Token (JWT) format. Access tokens tell Wristband which rights or access levels a user has when attempting to access a resource.
Confusion Around "Authorization"
The term "authorization" has a slightly different meaning and context when used in the context of OAuth2 and Role-Based Access Control (RBAC).
OAuth authorization is about determining whether a client should be granted an access token that represents the user's approval to access particular resources or perform specific actions. The client is authorized to act on behalf of the user, and the access token serves as proof of that authorization.
RBAC authorization, on the other hand, involves determining whether a user or entity, based on their role, has the necessary permissions to perform specific actions on a resource. It is about enforcing access control based on the user's role and the permissions associated with that role. The RBAC authorization process occurs within the application itself and does not involve external authorization servers or user consents.
Wristband's usage of the word "authorization" generally refers to RBAC, except when necessary or required to explain OAuth-based authorization flows (i.e., Authorization Code flow, authorization request, etc.), such as on this page.
OAuth 2.1 vs 2.0
Wristband currently adheres to the OAuth 2.1 specification as opposed to just the OAuth 2.0 specification. OAuth 2.1 is designed to enhance the security and usability of OAuth 2.0. It introduces security best practices to mitigate common vulnerabilities like token misuse and insecure redirect URLs. It also simplifies and clarifies the original OAuth 2.0 specification to make it more secure and user-friendly.
Certain flows as defined by the OIDC specification are deprecated by OAuth2.1 and are not supported by Wristband (more on that below).
To learn more about OAuth 2.0, you can read the specification here:
The OAuth 2.0 Authorization Framework
To learn more about OAuth 2.1, you can read the specification here:
The OAuth 2.1 Authorization Framework
OpenID Connect (OIDC)
Building upon the OAuth 2.1 framework, OpenID Connect (OIDC) introduces an identity validation layer. This empowers applications to authenticate a user's identity and retrieve fundamental user profile information. OIDC makes use of JSON web tokens (JWTs) obtained through authentication flows in accordance with OAuth 2.1 standards.
To learn more about OpenID Connect, you can read the specification here:
OpenID Connect Core 1.0 Specification
OAuth/OIDC Endpoints
OIDC defines several flows that allow applications to authenticate users and obtain their identity information. These flows are designed to accommodate different use cases and security requirements. There are two main API endpoints of interest that a resource owner needs to interact with to be considered authenticated: the Authorization Endpoint and the Token Endpoint.
Authorization Endpoint
The primary purpose of the Authorization Endpoint (located at /api/v1/oauth2/authorize) is to initiate the OAuth Authorization Flow. It is where a user is sent to authenticate and authorize a client to access their protected resources.
You can learn more about the Wristband Authorization Endpoint in our API Reference.
Supported Response Types
The Response Type request parameter (response_type) informs the Authorization Server of the desired authorization processing flow, including what parameters are returned from the endpoints used. Wristband only supports a value of code for the response_type parameter for the Authorization Endpoint. Following the guidance of OAuth 2.1, Wristband does not support the following values: token, id_token, and none.
Token Endpoint
The primary purpose of the Token Endpoint (located at /api/v1/oauth2/token) is for a client application to exchange an authorization grant for an access token.
You can learn more about the Wristband Token Endpoint in our API Reference.
Supported Grant Types
The Grant Type request parameter (grant_type) is a method or flow that a client application uses to request and obtain an access token from an authorization server. Each grant type is designed to accommodate different use cases and security requirements. Wristband only supports the following values for the grant_type parameter for the Token Endpoint: authorization_code, refresh_token, and client_credentials.
Supported OIDC Flows
| Flow | Supported | Description |
|---|---|---|
| Authorization Code | Yes | This is the most commonly used flow for web, mobile, and desktop applications. It involves multiple steps where an OAuth Client redirects the user to the authorization server (Wristband), the user logs in, and then the authorization server sends an authorization code back to the OAuth Client. The OAuth Client then exchanges this code for an access token and an identity token (ID token). |
| Client Credentials | Yes | This flow is suitable for machine-to-machine (M2M) communication between services or applications without user involvement. It allows a client to authenticate directly with the authorization server (Wristband) and obtain an access token based on its own credentials. |
| Resource Owner Password Credentials | No | The user's credentials (username and password) are sent directly to the authorization server by the OAuth Client, which then responds with an access token and ID token. Wristband does not support this flow as OAuth 2.1 recommends its deprecation in favor of more secure flows. Since the client application collects and sends the user's username and password directly to the authorization server, this can expose sensitive information and is vulnerable to interception, man-in-the-middle attacks, and potential client-side security issues. OAuth 2.1 recommends the Authorization Code Flow with PKCE (Proof Key for Code Exchange) instead. |
| Implicit | No | This flow is suitable for client-side applications, such as single-page apps (SPAs), where it's not safe to store a client secret. It directly returns the access token and ID token to the client after the user logs in, without the need for an authorization code exchange. Wristband does not support this flow as OAuth 2.1 recommends its deprecation in favor of more secure flows. Since access tokens are delivered directly to the client application without an intermediate authorization code exchange, then that means sensitive access tokens are exposed in the browser, which increases the risk of token leakage through client-side vulnerabilities, including cross-site scripting (XSS) attacks. There is also no refresh token support for this flow, which means there is no built-in mechanism for obtaining new access tokens without user involvement (i.e., refresh tokens), leading to a suboptimal user experience. OAuth 2.1 recommends the Authorization Code Flow with PKCE (Proof Key for Code Exchange) instead. |
| Hybrid | No | This flow is a combination of the Authorization Code Flow and the Implicit Flow, allowing the client to receive an ID token and access token directly (like Implicit Flow) and also provides an authorization code for more secure access token retrieval (like Authorization Code Flow). It's often used when additional security is required in certain parts of the application. This flow is not used very often in practice, so Wristband has chosen not to support this flow. |
Supported OpenID Scopes
The following are possible OIDC scope values supported by Wristband that can be returned within an access token:
Note About Scopes and ID Token Claims
The OIDC spec says that if an access token is returned from the
/tokenendpoint, then the scope claims should be returned in the Userinfo Endpoint response and not in the ID token:
"The Claims requested by theprofile,address, andphonescope values are returned from the UserInfo Endpoint, as described in Section 5.3.2, when aresponse_typevalue 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.
| Scope | Required | Description |
|---|---|---|
| openid | Yes | Indicates that an authorization request is an OIDC request. This scope is required to be present for all OIDC authorization requests. |
| profile | No | Indicates that the following claims should be included in an ID token and userinfo endpoint response: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at. Wristband does not currently support the profile and website claims for the profile scope, so those claims are never returned. |
| No | Indicates that the following claims should be included in an ID token and userinfo endpoint response: email and email_verified. | |
| address | No | Indicates that the following claims should be included in an ID token and userinfo endpoint response: address. Wristband will accept the address scope, but we don’t currently support addresses so it will be ignored if passed in the authorization request. |
| phone | No | Indicates that the following claims should be included in an ID token and userinfo endpoint response: phone_number and phone_number_verified. |
| roles | No | Indicates that the following claims should be included in an ID token and userinfo endpoint response: roles. This is a custom scope that is not defined as part of the OIDC specification. |
| offline_access | No | Indicates if a refresh token should be included in the token response. |
OAuth Client Types
A client type is a classification or categorization of different applications or services that make authentication requests to Wristband. The OAuth2 specification defines different client types to help establish the trust level and security measures for different types of clients. The type defines the capabilities and characteristics of the client, how the client interacts with Wristband, and how to handle sensitive information like client secrets and access tokens.
There are two main ways the OAuth2 specification classifies client types: public and confidential. With those two classifications, there are sub-categories of client types that fall under the public and confidential buckets. Wristband supports the following client types:
| Client Classification | Client Types | Description |
|---|---|---|
| Public | Single Page Application, Native | These are applications or services that cannot securely store client credentials, meaning they do not have a client secret. Public clients rely on the user's authentication, and their lack of a client secret implies reduced security compared to confidential clients. |
| Confidential | Backend Server, Machine-to-Machine | These are applications or services that can securely store and maintain client credentials (such as a client secret). They are capable of keeping their client credentials confidential and are trusted by Wristband to protect them as well. |
Backend Server Client
Supported Grant Types
authorization_codeclient_credentialsrefresh_token
Backend server clients are a type of confidential client. They are intended for traditional web applications running on web servers. They can securely store client credentials and communicate directly with the authorization server using server-to-server communication. Common usage for this type includes classic MVC-style web applications, API proxy servers for single-page apps, and various hybrid architectures where the server needs to act on behalf of itself in addition to your application's users.
Single Page Application Client
Supported Grant Types
authorization_coderefresh_token
Single-page application (SPA) clients, otherwise known as user-agent-based applications, are a type of public client that run entirely in the user's browser. This type is for client-side JavaScript applications that will interact with Wristband APIs directly instead of through a backend server. Since SPAs cannot keep client credentials confidential, they only support the OAuth2 authorization code grant type flow with PKCE as the primary means of authentication.
Native Client
Supported Grant Types
authorization_coderefresh_token
Native clients are public clients that are intended either for a mobile device (i.e., iOS or Android) or a desktop device (i.e., macOS, Windows, or Linux) that interfaces with your application. Native clients support custom Authorization URI protocols and schemes for any URLs that you configure in Wristband. Like single-page applications, native clients only support the OAuth2 authorization code grant type flow with PKCE as the primary means of authentication.
Machine to Machine Client
Supported Grant Types
client_credentials
Machine-to-machine (M2M) clients are confidential clients intended for servers that have zero end-user interaction and primarily deal with server-to-server workflows or automated server-side business logic. M2M clients can also be used for generating access tokens by developers looking to test APIs from command-line utilities like cURL or testing tools like Postman.
Application vs Tenant Client Types
In Wristband, OAuth Clients can be owned either at the application level or at the tenant level. The main distinction is that application-level clients are considered "first-party" while tenant-level clients are considered "third-party".
Application-level/First-Party Clients
Supported Client Types
- Backend Server
- Single Page Application
- Native
- Machine-to-Machine
First-party clients are owned and operated by you. Your application and all of its associated OAuth Clients are in the same "first-party" trust domain as Wristband. You maintain administrative control over the access to your application's user data and resources in Wristband. Application-level clients will typically cover most of your authentication needs for your applications and services.
Tenant-level/Third-Party Clients
Supported Client Types
- Machine-to-Machine
Third-party clients, also known as external clients, are intended to be operated by entities outside of the administrative control of your application's user data and resources. In Wristband, the common use cases for these clients are when you want to grant access tokens to each of your customers when they want to integrate with your application's APIs (in a fashion similar to API keys).
Updated about 2 months ago