UC_OAUTH_SETTINGS - AE REST API Authentication

This VARA object defines the configuration required to secure AE REST API access using OAuth2, enabling safe communication and integration with modern identity providers such as Microsoft Entra ID, Google, or Okta. It can be defined in Client 0 to apply globally across all Clients, or in a specific production Client to override the global configuration.

The variable includes the following keys:

JWKS_URL (Mandatory)

Specifies a publicly accessible HTTPS endpoint that hosts a JSON Web Key Set (JWKS). The JWKS contains the public keys used by identity providers (such as Microsoft Entra ID, Google, or Okta) to sign JWTs. The AE uses this endpoint to automatically download and cache the keys, ensuring that token signatures can be validated for authenticity and integrity.

Important! The Java Work Process (JWP) must have outbound network access to this endpoint. If the JWP is located in a DMZ or behind a firewall that restricts outbound traffic, OAuth2 authentication is not possible. In this scenario, REST API requests return a generic 401 or 45254 error, and the JWP log will display a connection refused error.

Examples:

https://login.microsoftonline.com/{your_directory_id}/.discovery/v2.0/keys

http://keycloak.example.com:8180/realms/example/protocol/openid-connect/certs

The system verifies JWT signatures using the keys retrieved from the configured JWKS endpoint.

Restart required: No
JWT_ID_KEYS (Optional)

A comma-separated list of JWT claims from the token payload. The Automation Engine uses these claims to identify which user the token belongs to.

Note: JWKS keys are used solely to verify the cryptographic signature and confirm that the JWT was issued by a trusted identity provider. The JWT_ID_KEYS are searched in order, after signature validation, to determine which AE user the token represents.

The claims are read in order, and the first non-empty claim value matching one of the JWT_ID_KEYS is used to identify the user. The claim specified here must contain a value that exactly matches the OAuth2 Value field defined in the corresponding User object, see Defining Users . The claim IDs are searched irrespective of the token type.

These are the claims searched by default (JWT_ID_KEYS=email,appid):
- User tokens: Identified by the email claim.
- Application tokens: Identified by the application ID (appid) claim.
You can customize this behavior to use other claims from the JWT payload (for example, oid) to align token identification with your organization’s identity management standards.

Example:

If you configure oid here, an incoming token containing "oid": "ccef-a1331515" in the payload will be mapped to the User object where the OAuth2 Value is set to ccef-a1331515.

Restart required: No
JWT_SCOPES (Optional)

Note: JWT_SCOPES will be renamed in a future release to JWT_AUDIENCES.

Defines which OAuth2 audiences are accepted by the AE REST API. After signature and identity validation, the system verifies that the token includes at least one audience (aud field in the token) that exactly matches a configured value. Partial or approximate matches are not allowed.

If JWT_SCOPES is not configured, any token that passes signature and identity validation is accepted. Defining an audience is strongly recommended to ensure that tokens are explicitly issued for this API. Depending on the identity provider, the token’s audience must match the application to confirm that the token was created for the AE.

Example: If you define automic here, the incoming token must contain the claim "aud": "automic".

Restart required: No

Troubleshooting OAuth2 Validation

If REST API authentication fails, you will typically receive generic errors such as 401 or 45254 ("The credentials are not valid"). To diagnose the root cause, you should check your JWP logs:

Network Errors: A log entry stating "Couldn't retrieve JWK set from URL: Connection refused" indicates a network or firewall issue preventing the JWP from reaching the JWKS_URL.
Token Logging: To assist with diagnosing claim or mapping mismatches, the JWP logs the incoming JWT header and payload. For security reasons, the signature portion of the token is removed before logging, so the logged token string is not usable.