OAuth2
OAuth2 Concepts
Overview
OAuth 2.0 is a standard designed to allow a website or application to access resources hosted by other web apps on behalf of a user.
The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.
Grants
Identity’s authorization framework supports several different flows or grants. Grants determine the way the application retrieves an Access Token without exposing credentials. The configuration of an application with Identity is done following a particular grant type. OAuth grant types determine the exact sequence of steps that are involved in the OAuth process, and affects how the client application communicates with the OAuth service at each stage. The application type and the programming language is written in are the best criteria for selecting the grant type you follow.
Roles
OAuth defines four roles:
| Role | Description |
|---|---|
| Client | The term client refers to your application. The terms client and application can be used interchangeably. Your application can be a web app based on a server, a single app that executes on a browser, or a desktop app on a mobile device. |
| Resource Owner | An entity capable of granting access to a protected resource. This is usually a user. |
| Resource Server | A server-side entity that handles authenticated requests after applying an access token via OAuth tokens. These tokens are issued by the authorization server, typically to a client application. The resource server validates the token before serving a resource to a client. |
| Authorization Server | Trimble Identity is the authorization server, which authenticates and authorizes users depending on the grant types. |
Protocol Flow
The abstract OAuth 2.0 flow describes the interaction between the four roles.
Grant types
Below are the currently used grant types and how you can use them with Identity.
| Grant type | Description |
|---|---|
| Authorization Code | The Authorization Code grant type is intended to be used by user-facing web applications with a server-side component. When the user grants authorization, the Identity authorization endpoint provides the client with a short-lived authorization code. |
| Authorization Code with PKCE | The Authorization Code with Proof Key for Code Exchange (PKCE) flow is an extension of the Authorization Code grant flow. However, with PKCE, requests do not need to include the client_secret in the /token request. The PKCE flow reduces security risks for desktop and mobile applications because the client_secret does not need to be embedded in source code. |
| Client Credentials | This method is used outside of the context of the user. The client is assumed to be the resource owner and the access request to an application’s resources rather than the resource’s owned by the user. |
| On behalf / Token Exchange | The On Behalf grant flow allows an application to act on behalf of a user. The On Behalf grant is only supported for access tokens. It does not work with any other type of token, including refresh tokens. |
Types of tokens
Tokens are programming elements that represent the right to perform an operation depending on the token type.
ID token
Trimble Identity issues an ID token (using OpenID framework) when the user logs on. An ID token is an artifact that proves the user has been authenticated. The ID token contains information about the user, such as user name and email, and is used to authenticate a user.
The ID token, a JWT (JSON Web Token), conforms to IETF RFC 7519 and contains three parts: A header, a body, and a signature.
The header contains the type of token and the hash algorithm used on the contents of the token. The body, also called the payload, contains identity claims about a user. Claims can include registered names like the token issuer, the subject of the token, and the time of issuance. The recipient of a JWT uses the signature to validate the integrity of the information conveyed in the JWT.
Access token
The access token is generated using the grant types specified in the OAuth flow. The access token’s primary function is to authorize a user. Access tokens are issued via OAuth 2.0 endpoint /OAuth/token. Access tokens must be used to gain access to an API.
Access tokens are short-lived, with a lifetime of 60 minutes (1 hour). If the access token expires or becomes invalid, it can be requested through refresh tokens or regenerated.
Refresh token
A refresh token is used to obtain access tokens after an initial authorization grant without interaction with the end-user. When the access token becomes invalid or expires, the refresh token can be used to request another access token for the same set of scopes (or a subset of those scopes).
A refresh token can be used once and is valid for 9 days. If the refresh token expires, you need to reauthenticate.