Authorizing Web Applications

Web apps are written in a server-side framework and run on a server where the source code or configuration of the application is not available to the public. This allows the use of a client secret when communicating with the authorization server to help improve security.

NOTE: Your client credentials carry many privileges, so be sure to keep them secure!

• Do not put your client credential information (clientid, client secret or access tokens) in publicly accessible code where they can be discovered.
• Store them in a safe place on the backend (server).

Authorization Code Flow

Most Bentley APIs support the OAuth 2.0 Authorization Code Flow. This flow provides the ability for a resource owner (owner of the data to access) to authorize applications to access their personal data on their behalf. Your application can use this flow including all built-in features like customer login and consent handling in order to get the authorization by the resource owner.

These are the steps that the flow executes:

1. Redirect the end user's (resource owner's) browser to the authorization server endpoint
2. Authenticate the end user and ask for consent
3. Redirect the end user to your application's callback URL with an authorization code
4. Exchange the authorization code for an access token
5. Use the access token to call the API on behalf of the end user

The following steps outline how to implement the authorization code flow in your application:

1. Redirect the end user's browser to the authorization endpoint

In order to initiate the end user's authorization, you must redirect the end user's browser to Bentley's authorize endpoint. This will provide a login screen to the end user for authentication. After successful authentication, the consent screen is displayed, if the user has not given the consent yet.

Authorization endpoint: https://ims.bentley.com/connect/authorize

The URL requires the following parameters:

1. • response_type=code: Request an authorization code as the result of the end user authorization process.
   • client_id=<insert_your_client_id_here>: Provide the client ID of your application.
   • redirect_uri=<insert_redirect_uri_here>: This is the callback URL that is registered for you application in order to receive the authorization code.
   • scope=<insert_scopes_of_API_here>: Include the scopes for the API, which are the permissions to request the end users consent for. For each API, you can find the required scopes in the additional API specific documentation.
   • state=<insert_client_state_here>: (optional) An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery.

2. Authenticate the end user and ask for consent

This step will be performed by Bentley's authorization server and does not require anything to be implemented in your application. Redirect the end user to your application's callback URL with an authorization code

3. Redirect the end user to your application's callback URL with an authorization code

After the end user provides consent for your application, Bentley's authorization server will redirect the end user with an authorization code to the redirect URL registered with your application.

4. Exchange the authorization code for an access token

After your application has received the authorization code you can exchange it for an access token. The client must authenticate using the HTTP Basic method and provide the url-encoded clientId and the clientSecret (<insert_your_url_encoded_client_id_here>:<insert_your_url_encoded_client_secret_here>) encoded with BASE64 in the HTTP Authorization header.

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

The following parameters are used in the request payload using the "application/x-www-form-urlencoded" format:

1. • grant_type=authorization_code: Tells the token endpoint to use the OAuth 2.0 Authorization Code Flow for this request.
   • code=<authorization_code>: Provide your one-time use authorization code that you received in step 3.
   • redirect_uri=<insert_redirect_uri_here>: This is the callback URL that is registered for your application in order to receive the authorization code. The URL must also match the URL that you have provided in the authorization request (see step 1).

You will then receive the OAuth access token in the server response accesstoken field. Note that the expiresin field in the response represents the validity period of the access token in seconds and it is equal to 3600s.

5. Use the access token to call the API on behalf of the end user

You can now use the access token to call the API as long as it is not expired. Add the provided token to the Authorization header of your API request, using Bearer scheme.

Authorization request example

https://ims.bentley.com/connect/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&scope=<scope>&state=<state>

curl https://ims.bentley.com/connect/token -X POST --data-urlencode grant_type=authorization_code --data-urlencode code=<authorization_code> --data-urlencode client_id=<client_id> --data-urlencode client_secret=<client_secret> --data-urlencode redirect_uri=<redirect_uri> --data-urlencode scope=<scope>