OAuth settings

Prerequisite: To configure the OAuth settings, you must have the OAUTH2ADM access code.

About WorkZone OAuth

OAuth is an open standard authorization framework that allows users to grant applications temporary and limited access to their user account information on other websites without distributing sensitive information such as passwords. The OAuth framework delegates user authentication to the service that hosts the user account, and authorizes third-party applications to access the user account and is used by large internet-based companies to enable users to share information with third party applications or websites.

OAuth and WorkZone

The OAuth framework can be used in WorkZone to improve security and facilitate delegation of authorization between the WorkZone Content Server and external components or systems such as mobile devices or the WorkZone ClientWorkZone Content Server web application without exposing passwords or using "on-behalf-of" features.

The OAuth settings page

The OAuth settings page has two tabs:

  • Clients: Here you can set up, maintain and delete OAuth settings for WorkZone integrated tools (clients), such as WorkZone Configuration Tool, WorkZone PDF Crawler and so on.
  • Integrations: Here you can configure access to WorkZone by the third-party apps registered in your Azure Tenant. By default, there are nine built-in integration accounts that you can configure for different third-party apps.

The Clients tab

Here you can view, create, edit and delete OAuth settings for WorkZone integrated tools.

Field Description

Client ID

Unique ID of the client. You can use all characters in this field.

Client name

Name of the client.

Enabled

Enable the client for OAuth integration.

  • This option is enabled by default.

Allow access token via browser

Enable this option to receive access tokens via the browser.

Disable this option to harden flows that allow multiple response types, for example, by disallowing a hybrid flow client that is supposed to use code id_token to add the token response type and thus leaking the token to the browser.

The access token is normally delivered with the redirect URI as query parameter, but in some scenarios it is not advisable to send the access token in this fashion and instead request the client and not the browser to retrieve the token from OAuth2 server.

  • This option is disabled by default.

Allow offline access

Enable the client to request refresh tokens by requesting the offline_access scope.

  • When this option is enabled: The client will receive a refresh token after the access token expires which enables the client to safely process requests offline and thereafter reconnect without requiring user authorization.
  • When this option is disabled: The client will not receive a refresh token after the access token expires, which will require the user to authorize the client again and repeatedly.

This option is disabled by default.

Require proof key for code exchange

Enable to require the client utilizing an authorization code based grant type to send a proof key for code exchange. This is an additional mechanism to secure communication between the client and WorkZone.

  • This option is disabled by default.

Grant type

The Grant type specifies how a client is to interact with the OAuth IdentityServer.

  • This is a not a mandatory field, but if you want to use the OAuth framework for authentication, you must specify at least one grant type in this field.

There are six types of available grant types:

  • AUTHCODE (Authorization code): Originally specified by OAuth2. Provides a way to retrieve tokens on a back-channel as opposed to the browser front-channel. It also supports client authentication.
  • CLNTCRED (Client credentials): Used for server-to-server communication. A token request is sent to the token endpoint and an access token that represents the client is returned. Tokens are always requested on behalf of a client and not a user. When CLNTCRED grant type is selected, you must select a Username to map to this client.
  • DEVCODE (Device code): Designed for browser-less and input constrained devices, where the device is unable to securely capture user credentials. The user authentication and consent is moved to an external device, for example a smart phone or tablet.
  • HYBRID (Hybrid): A combination of the Implicit and Authorization code and uses a combination of multiple grant types. The identity token is transmitted via the browser channel and contains the signed protocol response along with signatures for other artifacts like the authorization code.
  • IMPLICIT (Implicit): Optimized for browser-based applications. All tokens are transmitted through the browser but refresh tokens are not used. Implicit grant types are not recommended for JavaScript-based applications.
  • PASSWORD (Password): Tokens are requested on behalf of the user. The user's name and password is sent to the token endpoint.

You can select multiple grant types.

Client secret

Define one or more secrets that can authenticate the client (or API resource) to the OAuth server.

In some situations clients need to authenticate with the OAuth Server and you can use the list of secrets for this authentication.

  • This is a not a mandatory field, but if you want to use the OAuth framework for authentication, you must specify at least one secret in this field.

Username

Select a username to map to this client.

  • This field is mandatory, if Grant type is CLNTCRED, Client credentials.

Redirect URI

Enter the URI the client is to be redirected to after successful OAuth2 authorization.

  • This is a not a mandatory field but if you want to use the OAuth2 framework for authentication, you must specify at least one redirect URI in this field.

Post logout redirect URI

Enter the URI the user is to be redirected to after successfully logging out the OAuth2 server.

You can use this setting to specify a web page which will be displayed after the user has logged out from the OAuth2 server, for example, a web page displays a "You have been successfully logged out" message, prompt for a new log-in or perform a clean-up of used elements.

Create, edit or delete OAuth settings

  1. In WorkZone Configurator, click Global > OAuth Settings > Clients.
  2. Click Create to open the Create OAuth settings form.
  3. Fill in the following fields:
    • Client ID: Enter a unique identifier for the client.
    • Client name: Enter a name for the client.
    • Enabled: Turn on to enable the client for using the OAuth framework for authentication.
    • Allow offline access: Turn on to enable the client to request refresh tokens from the OAuth server.
    • Allow access token via browser: Turn on to enable the client to receive access tokens via the browser.
    • Require proof key for code exchange: Turn on to require the client utilizing an authorization code based grant type to send a proof key for code exchange.
    • Grant type: Select which grant types to apply to the client.
    • Client secret: Select one or more secrets to use for additional authentication for the client.
    • Redirect URI: Select the URI the user is redirected to after authentication.
    • Post logout redirect URI: Select the URI the user is redirected to after logging off.
  4. Click Create.
  1. In WorkZone Configurator, click Global > OAuth Settings > Clients.
  2. Hover the mouse over the OAuth setting you want to edit, and click in the menu.
  3. Edit the values as needed.
  4. Click Save.
  1. In WorkZone Configurator, click Global > OAuth Settings > Clients.
  2. Hover the mouse over the OAuth setting you want to delete, and in the menu click Delete.
  3. Click Delete.

The Integrations tab

Use the Integrations tab to configure access to WorkZone by the third-party apps registered in your Azure Tenant. By default, there are nine built-in integration accounts that you can configure for different third-party apps.

Field Description
Account ID Name of the integration account. This field is read-only.
Object ID Object ID of Enterprise App registration in Azure
Department Department to which this integration account belongs to.
Note: Leave this field empty to apply the integration to your whole organization.
Allow impersonation Enable to allow the integration account to act on behalf of other users
Security code

The security code that applies to.

Note: By default the security code is set to 0, meaning that the integration account is disabled.
Departmental access*

Enable to give the integration account full access to any items within the selected Authority. See Global and departmental access.

*This field is only visible, if you have the STJERNADM access code.

  • This field is automatically disabled, if you turn on Global access.
Global access*

Enable to give the integration account full access to any items in the whole organization. See Global and departmental access.

*This field is only visible, if you have the STJERNADM access code.

  • Global access overrides the departmental access.

Set up a new third-party integration account

  1. In WorkZone Configurator, click Global > OAuth Settings > Integrations.
  2. On the OAuth settings page, hover the mouse over the integration account you want to edit, and click in the menu.
  3. In the [%account_name] - OAuth Integration settings form, fill in and edit the needed settings:
    • Account ID: This field is read-only.
    • Object ID: Enter the object ID of your Enterprise app registration in Azure.
    • Security code: From the dropdown, select the security code.
    • Department: Select a department from the dropdown, if this integration should only apply to a specific department within your organization.
    • Allow to act on behalf of other users: Turn on to allow this account to act on behalf of other users.
    • Departmental access: Turn on to give the integration account full access to any items within the selected Authority.
    • Global access: Enable to give the integration account full access to any items in the whole organization.
  4. Click Save.