Authorize a Web Application - Tutorials

Introduction

When developing web applications using a server-side framework, use the following procedures to set up your authorization.

IMPORTANT

Keep your client credentials, i.e., client ID, client secret, and access tokens, secure. Do not include them in publicly accessible code where they could be discovered. Instead, store them safely on a backend server.

Before you begin

This guide requires you to have:

A registered web app. If you have not created an application, open the My Apps page under your Profile menu and click the Register New button. For this guide, the application type is Web App.
A redirect URI of https://developer.bentley.com/redirect-tutorial. Add this redirect URI during app registration, or on the App Details for a previously registered application. The App Details page can be accessed through the My Apps page.
The client_id and the client_secret supplied when you create your application. Make sure to save this data in a secure location.

Note

There is an optional step at the end of the tutorial that enables you to test the token you received beyond the successful HTTP response.

User authorization code flow

Web applications can use the OAuth 2.0 Authorization Code Flow to enable data owners to authorize third-party apps to access user data. This flow includes features like customer login and consent handling to obtain authorization from the resource owner.

The following steps provide an overview of the process.

The application makes a request to the authorization server endpoint.
The end-user provides their authentication information and consents for the application to access resources on their behalf.
The authorization server returns an authorization code to the Redirect URI specified when creating the application.
The application uses the authorization code to obtain an access token from the authorization server.
The application uses the access token to call the API on behalf of the user.

sequenceDiagram participant ro as Resource Owner participant app as Application participant as as Authorization Server participant api as iTwin API ro->>+app: Connect to application app->>+as: Request authorization code as->>ro: Redirect to login and consent ro->>as: Sign in and consent as->>-app: Authorization code app->>+as: Exchange authorization code for an access_token as->>as: Validate client_id, client_secret, scope and redirect_uri as->>-app: Granted access token app->>-ro: Signed in ro->>+app: Perform action app->>+api: API request with the access token api->>-app: API response app->>-ro: Render content

Set up authorization for your app

The following guide steps you through retrieving an access token for your web app. Once you have your app registered, you can begin to obtain the access token.

Obtain an access token

To obtain an access token for your app, follow these steps:

When the user opens the web app, redirect them to the authorization server endpoint.

https://ims.bentley.com/connect/authorize?client_id=<client_id>&redirect_uri=<redirect_uri>&scope=itwin-platform+offline_access&response_type=code

The request for an authorization code requires the following parameters:

Parameter
Description
response_type
Set to code to indicate that an authorization code is needed.
client_id
The ID of the app you created. If you forgot the ID, find it on the My Apps page. Locate your app in the list, and the Client ID is in the same-named column.
redirect_uri
The callback URL you entered when registering your application. The returned authorization code is sent to this URL. In this case, the callback URL must be https://developer.bentley.com/redirect-tutorial.
scope
Add the itwin-platform scope assigned to your app during registration. When requesting a refresh token, include the scope offline_access. Separate multiple scopes with a space. Your end user will consent to the app accessing this information on their behalf during the login process.
state
(Optional) Used by the client to maintain state between a request and a callback. Recommended to prevent cross-site request forgery. The authorization server includes this value when redirecting the user-agent to the client.

Redirect
The user signs in to authenticate and consents for the application to access resources on their behalf. This page is managed by the Bentley authorization server and does not require any implementation in your application.

Once authenticated, the Bentley authorization server returns an authorization code to the Redirect URI registered with your application. Extract the code in the response from the redirect_uri.

https://example-rediect-uri/?code=<code>

Note
Authorization codes are time-sensitive. If your code expires, send a new request to the authorization server for a new code.
Send a request to the token endpoint to exchange the authorization code for an access token.

POST
https://ims.bentley.com/connect/token

The authorization request requires the following parameters:

Field Name
Description
client_id
Identification generated during application creation. Found in the My Apps page or in the first step if generated during the tutorial.
client_secret
Secret created during application creation.
grant_type
Set to authorization_code Indicates the type of grant being used. This tells the service you are exchanging the code for a token.
code
This is the authorization code returned in the previous request.
redirect_uri
The callback URL you entered when registering your application. This URL must match the URL provided in the initial request.
The authorization server confirms the information sent in the request and returns an access token. Bentley's authorization server completes this step. There is no implementation needed in your application. A successful response includes the access_token, an expiry of 3600 seconds, and a refresh_token. Tokens are Bearer type, which must be specified in your API calls.
Use the access token to call the API. Tokens are added to the Authorization header with Bearer type in subsequent requests.
Successfully sending a request to an API requires the end user to have the correct account permissions. Use the Access Control API to ensure your user can access the required resources.

Request a new access token with a refresh token

When your access token is close to the expiry time, you must request a new one using the refresh token provided in the original request. The response contains a new token and a new refresh token. Tokens are Bearer type, which must be specified in your API calls.

POST

https://ims.bentley.com/connect/token

client_id

Identification generated during application creation. Found in the My Apps page or in the first step if generated during the tutorial.

client_secret

Secret created during application creation.

grant_type

Set to refresh_token Indicates the type of grant being used. This tells the service you are requesting a new access_token with a refresh_token.

refresh_token

The refresh token. Ensure the refresh_token you include is the same one received from the previous request.

Test your token

If you received a 200 OK response to your token request, you have successfully obtained a token. You can use this token to call various iTwin Platform APIs. You can try making an API call to users/me endpoint to test your token. On success, this request returns the profile information for the user account associated with the token received.

Remember, the iTwin Platform Base URI is api.bentley.com.

More resources that you may like

Access Control

Manage Access Controls for your iTwin member using iTwin roles and permissions.