SystemConfigure OAuth 2.0 Authentication

You can configure OAuth 2.0 authentication for incoming REST API calls as an alternative to Basic Auth.

Note: To perform this task, you must be signed in as the ClientAdmin, SystemAdmin, or SuperAdmin user. For more information, see Controlling Access to System Settings

To configure OAuth 2.0 for incoming REST API, use the following procedure. You must already have a OAuth 2.0 authentication server.

  1. Stop the Loftware Spectrum service.
  2. On the Loftware Application Server, navigate to the <LOFTWARE_HOME>/product/conf directory.
  3. Create an OAuth 2.0 .properties file in the directory.

    Example

    Create a file named oauth2_template.properties in the <LOFTWARE_HOME>/product/conf directory.

  4. Include the following keys and values in the .properties file as appropriate for your server:
    • security.oauth2.client.id: This value should match both the Client ID on the incoming authentication token and the LDAP domain on the Loftware Enterprise SP system. However, note that this value does not prevent tokens containing different client IDs from being used.
    • security.oauth2.issuer.url: The value provided for this key must match the name of the realm created on the OAuth identification server side. Loftware Enterprise SP will validate this property value against the "iss" (issuer) value within the authentication token passed to Loftware Enterprise SP by the calling REST client.
  5. In the <LOFTWARE_HOME>/product/conf directory, open the jdbc.properties file for editing.
  6. Modify the following key values (and make sure they are not commented out), or add the keys and values to the bottom of the file if they do not exist:
    • security.oauth2.config.filename: Enter the name of the .properties file you created.

      Example

      security.oauth2.config.filename=oauth2_template.properties

  7. Start the Loftware Spectrum service.
  8. Sign in to Loftware Enterprise SP as an administrator and go to System System Management.
  9. Click LDAP Authentication and then create a new authentication.
  10. Configure the Domain Name to be the same name as the "azp" (authorized party) value. Note that "azp" is a key name in the authorization token. "azp" in the token stands for "Client ID", built from the OAuth identity server. The value of the LDAP Domain (LDAP name) in Loftware Enterprise SP needs to match the Client name/azp token value.
  11. Configure the remaining fields as appropriate. For more information, see User Interface: LDAP Authentication.

    Tip: The LDAP Domain can be a real server with fully populated valid fields, or placeholder. For placeholders (LDAP Domains with sparsely populated fields) the only required fields are the name (which must match the Client ID) and the "Provider URL" field, which can use a placeholder value, "ldap://test".

  12. Click Save.
  13. In Access Control Access Control, create or modify user(s) for the new LDAP domain you created. The username must match either the username or the name part of the email address for a user that exists on the OAuth 2.0 server.
  14. Configure permissions for the user(s) as needed. For more information, see Configuring Loftware Enterprise SP Users.

    Note: A user must be assigned the LOCAL_ADMIN or ROLE_ADMINISTRATOR role to call Loftware Enterprise SP from a REST client.

Tip: You can test your REST calls with Postman. Use the Authorization tab in Postman to get an access token. If you are using a Keycloak server, you can review the "well known" values by using a URL in the following format:
<issuer url>/.well-known/openid-configuration
For example, http://localhost:9080/auth/realms/LoftwareOAuth2Test/.well-known/openid-configuration