Authorize a Web Application
Introduction
When developing web applications using a server-side framework, use the following procedures to set up your authorization.
Before you begin
This guide assumes you have:
- Registered a web app with the necessary scopes for your use case. If you have not created an application, open the My Apps page under your Profile menu to create one. For this guide, the application type is Web App.
- The
client_id
and theclient_secret
supplied when you created your application. - This tutorial requires a redirect URI of
https://developer.bentley.com/redirect-tutorial
. Please add this redirect URI to the App Details for your application. The App Details page can be accessed through the My Apps page.
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.
- Exchange the authorization code for an access token.
- Use the access token to call the API on behalf of the user.
Set up Authorization for your App
The following steps guide you through setting up your application and retrieving an access token with the needed permissions for your web application.
Register a web application
- Click your profile button in the upper-right corner of the page. You must be logged in to the Developer Portal.
- Select My Apps from the drop-down.
- Click the Register New button.
- Enter the name of your application. Web apps have a maximum of 128 characters, the following characters are not allowed: ,;[]=\<>?"{}|+!@#\$%\^*`~
- Select the appropriate scopes for your application in API associations.
Selected scopes are listed in the Allowed scope list box. - In Application Type, click Web App to indicate you are creating a web application.
- In Redirect URIs, enter the callback URL to use during the authorization process. This is the URL to which the authorization code is sent.
Optionally, you can set a Post logout URI to which the user will be redirected when logging out of the app. - Click Save.
- On the Success dialog, click Copy to copy the
client_id
andclient_secret
created for your app. Make sure you save this data in a secure location. It is required to obtain a token.
Close the dialog by clicking the X in the upper-right corner or clicking outside the box.
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=<scopes>+offline_access&response_type=codeThe request for an authorization code requires the following parameters:
ParameterDescriptionresponse_typeSet tocode
to indicate that an authorization code is needed.client_idThe 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_uriThe callback URL you entered when registering your application. The returned authorization code is sent to this URL.scopeAdd the scopes assigned to your app during registration. Separate multiple scopes with a space. Your end user will consent to the app accessing this information on their behalf during the login process. When requesting a refresh token, include the scopeoffline_access
. For all other scopes, check the reference documentation for each respective API.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.RedirectThe 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 theredirect_uri
field.Send a request to the token endpoint to exchange the authorization code for an access token.
POSThttps://ims.bentley.com/connect/tokenThe authorization request requires the following parameters:
Field NameDescriptionclient_idIdentification generated during application creation. Found in the My Apps page or in the first step if generated during the tutorial.client_secretSecret created during application creation.grant_typeSet toauthorization_code
Indicates the type of grant being used. This tells the service you are exchanging the code for a token.codeThis is the authorization code returned in the previous request.redirect_uriThe 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 arefresh_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 withBearer
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.
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
you include is the same one received from the previous request.Validate your token
If you received a 200 OK
response to your request for a token, it is not necessary to validate it. However, the users/me
endpoint is provided if you would like to do so. 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
.