OAuth2 settings

Prerequisite: To set up OAuth2, you must be assigned the OAUTH2ADM access code.


About WorkZone OAuth2

OAuth2 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 OAuth2 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.


OAuth2 and WorkZone

The OAuth2 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 OAuth2 settings page

Use the OAuth2 settings page to set up, maintain and delete settings for using OAuth2 protocol for WorkZone.

Field Description

Client ID

Enter a unique ID of the client. You can use all characters in the client ID.

  • This is a mandatory field.

Client name

Enter a name for the client to provide an easier method of client identification.

  • This is a mandatory field.

Enabled

Enable the client for OAuth2 integration.

  • This option is enabled by default.

Allow access token via browser

Enable 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

Select the Grant type, which specifies how a client is to interact with the OAuth2 IdentityServer.

  • This is a not a mandatory field, but if you want to use the OAuth2 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 OAuth2 server.

In some situations clients need to authenticate with the OAuth2 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 OAuth2 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.


Creating, editing or deleting OAuth2 settings.

  1. In WorkZone Configurator, click Global > OAuth2 Settings to open the OAuth2 settings page.
  2. On the OAuth2 settings page, click Create to open the Create OAuth2 settings form.
  3. Fill in the following fields in the Create OAuth2 settings form:
    • 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 OAuth2 framework for authentication.
    • Allow offline access - Turn on to enable the client to request refresh tokens from the OAuth2 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 to close the form and create the OAuth2 setting.
  1. In WorkZone Configurator, click Global > OAuth2 Settings to open the OAuth2 settings page.
  2. On the OAuth2 settings page, hover the mouse over the OAuth2 setting you want to edit, and click in the menu to open the OAuth2 settings form.
  3. On the OAuth2 settings form, edit the values as needed.
  4. Click Save to close the form and update the OAuth2 settings.
  1. In WorkZone Configurator, click Global > OAuth2 Settings to open the OAuth2 settings page.
  2. On the OAuth2 settings page, hover the mouse over the OAuth2 setting you want to delete, and in the menu click Delete to open the Delete OAuth2 settings dialog.
  3. In the Delete OAuth2 settings dialog, click Delete to delete the selected OAuth2 setting.