Strategy One

Configure Strategy Library OAuth2

Starting in Strategy One (May 2025), you can configure your environment to use OAuth 2.0 to log in to Library. Use this option to unify authentication methods to the Intelligence server through the Library server, regardless of the authentication mode that is enabled on the Library server.

This functionality is only supported in Managed Cloud Enterprise.

See the following topics to configure Library OAuth2:

Prerequisites

  • Ensure you have the latest version of Workstation installed.

  • You must have the Administer environment privilege.

  • Ensure the OAuth2 feature is enabled. Check the WEB-INF/classes/config/configOverride.properties file and ensure auth.oauth2.server.enabled = true is configured.

Configure OAuth2 Clients

  1. Open the Workstation window.
  2. In the Navigation pane, choose Environments to view the available environments. Make sure the environment is connected.

  3. Right-click the environment and choose Properties.

  4. In the left pane, click Library.

  5. In OAuth2 Configuration, under server, the following fields display:
    • Authorization Endpoint: The URL a user is redirected to authorize the application.
    • Token Endpoint: The URL the application exchanges the authorization code for an access token.
  6. In OAuth Configuration, click Create under Clients.

  7. Type a name for the client in Display Name.

  8. Expand the Client Type drop-down list and choose an option.

    If you choose Single Page Application or Native Application, Proof Key for Code Exchange (PKCE) is required.

  9. Click Copy to copy the Client ID and Client Secret.

    The Client Secret only displays once.

  10. Enter a Redirect URI. To add additional URIs, click Create New.

    For example, https://example.com/oauth2/callback, http://localhost:8080/oauth2/callback, or custom.scheme://auth.

    HTTPS is required for non-localhost URIs.

  11. Optionally select the checkbox next to Refresh Token to add a refresh token to obtain new access tokens without user interaction and configure the following fields:
    • Reuse Refresh Token: Select this checkbox to reuse the refresh token to obtain new access tokens. If you do not select this checkbox, a new refresh token will be issued each time a new access token is obtained.
    • Refresh Token Lifetime: Enter a value in minutes for the refresh token time span.
  12. Click OK.
  13. To verify the configuration saved:

    1. Right-click the environment and choose Properties.

    2. Click Library and review the OAuth2 Configuration section.

    3. To add more clients, click Add and repeat steps 6 through 11.

    4. To regenerate the Client Secret, click Regenerate .

    5. Click OK.

Troubleshoot

The /oauth2/authorize Endpoint Returns a 404 Error

Check the WEB-INF/classes/config/configOverride.properties file and ensure auth.oauth2.server.enabled = true is configured.

The /oauth2/authorize Endpoint Returns HTTP Status 400 - Bad Request

Check the OAuth2 client configuration in Workstation and ensure that the parameters in the /oauth2/authorize request match, including the following parameters:

  • client_id: Ensure the client IDs match.

  • redirect_uri: Ensure the redirect URIs match.

  • response_type: The response type is code.

  • scope: Ensure Refresh Token is selected if the scope parameter is offline_access.

  • code_challenge: Ensure this field has an entry if the client type is Single Page Application or Native Application.

  • code_challenge_method: Ensure this field has an entry if the client type is Single Page Application or Native Application.

The Refresh Token is Not Returned in the /oauth2/token Response

Ensure the offline_access scope is in the /oauth2/authorize request and the Refresh Token option is selected in the client configuration.

Ensure the client_secret is included int he token exchange request, even when the OAuth2 client type is configured as Single Page Application or Native Application. In such cases, the client_secret is no longer confidential. A Proof Key for Code Exchange (PKCE) is implemented as an additional security measure to mitigate risk of the code being compromised.

The {error: 'server_error'} is Returned in /oauth2/token Endpoint

Ensure the Trust Relationship is established between the Library server and the Intelligence Server. To do this, check the WEB-INF/classes/config/configOverride.properties file and ensure that the iserver.trustToken field has a valid value.

If the trust token exists, regenerate it on the Library Web admin page or in Workstation.

After you regenerate the trust token, you need to restart the Library server.

Use Refresh Token to Exchange Access Token Returns 400 Error: {"error" : "invalid_grant}

The refresh token may have expired or the OAuth2 server may be configured to not be reused. Ensure Reuse Refresh Token is selected in the Workstation OAuth2 settings page.

The Library OAuth2 server may be configured to use the In-Memory token store and the server restarted. After the server restarts, the refresh token is lost. Check the auth.oauth2.server.storage field in the WEB-INF/classes/config/configOverride.properties file and ensure it is set to redis.