Authorization Code
Using the authorization code flow
Authorization Code
In the Authorization Code flow, a code is returned to the client through a browser redirect after the user (resource owner) gives consent to Identity (authorization server). The client subsequently exchanges the authorization_code for an access_token. Users’ credentials are never exposed to the application (client).
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.
How it works
- The application opens a browser to send the user to the authorization server login page
- The user performs a standard login with Trimble Identity credentials
- The user is redirected with the Authorization Code in the query string
- Trimble Identity returns an ID token to an application which validates the signature
- The application exchanges the Authorization Code for an
access_tokenand arefresh_token - The
access_tokenis used to authorize the application.
What you need
You will need the following information from the Developer Console.
- Client name
- Client id
- Client secret
- Callback url
Authorization Request
The first request is a GET or redirect to the authorization endpoint (/authorize) performed in a web browser. The /authorize endpoint supports three response_types: code, id_token, token. If code is present in your parameters, JWTs are not needed for authorization.
If the request contains the OpenID scope, it is also considered an authentication (OpenID Connect) request, and an ID token is issued.
get
https://id.trimble.com/oauth/authorize
Parameters
| Parameter | Description |
|---|---|
| state | This field is used to return data (like a return URL) after sign-in with an access code. |
| client_id | Application ID registered for the application (UUID) |
| response_type | code |
| scope | openid and applicationname (Scope is space delimited) |
| redirect_uri | Redirect URL registered with Identity |
| ui_locales (optional) | Local value |
| prompt (optional) | How Trimble Identity displays the login UI. See below for more information |
| login_hint (optional) | Allows an application to specify the email address for use in the sign in or sign up page if you are using prompt=create |
Prompt Options
Possible values for the optional prompt parameter
| Prompt value | Description |
|---|---|
| none | Trimble Identity will not display any UI, if there is no SSO session the /authorize call will redirect to the caller with a error |
| login | Trimble Identity will always display the sign in UI, regardless of whether an SSO session exists |
| create | Trimble Identity will display the sign up page rather than the sign in page |
Authorization Response
The following is an example of the callback made to your callback endpoint. You will need to parse the code parameter from the callback to use in your token call.
http://localhost:5173/auth/callback?code=us_9fd5fee3f3c74267910f8ed7c71c85a8&state=Hn4K-n1m00000CiUUV-vOUNcOJZ8Jh_4shooToken Request
After acquiring the authorization code, you exchange an authorization code for an access token through the resource server.
post
https://id.trimble.com/oauth/token
Headers
| Header | Description |
|---|---|
| Authorization | Basic credentials |
| Accept | application/json |
| Content-Type | application/x-www-form-urlencoded |
Body
| Body | Description |
|---|---|
| grant_type | authorization_code |
| code | The authorization code returned from the above call |
| client_id | Application ID registered for the application |
| redirect_uri | Callback URL registered with Identity |
Token Response
If the token request succeeds, the server responds with a 200 response code.
Response fields
| Field | Description |
|---|---|
| access_token | The access token’s primary function is to authorize a user. |
| refresh_token | A refresh token is used to obtain access tokens after an initial authorization grant without interaction with the end-user. |
| expires_in | The duration of time the access token is granted for in seconds |
| id_token | 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. |
Example response
{ "access_token": "8aca1...", "refresh_token": "861e9...", "expires_in": 3600, "id_token": "eyJhbG...",}Refreshing the token
If the access token expires, it can be refreshed using the one-time refresh token.
The server will respond with a Token Response.
post
https://id.trimble.com/oauth/token
Headers
| Header | Description |
|---|---|
| Authorization | Basic credentials |
| Accept | application/json |
| Content-Type | application/x-www-form-urlencoded |
Body
| Body | Description |
|---|---|
| grant_type | refresh_token |
| refresh_token | The refresh token from the previous token response |
Examples
Postman
Fork this Postman collection into your own workspace to quickly get started using Authorization Code.
You need the following from your Developer Console application:
- Client name
- Client id
- Client secret
- Callback url
To use with Postman, the Postman callback url (https://oauth.pstmn.io/v1/browser-callback) must be configured for your application.
