OAuth Administration

On the OAuth Administration page, you register the OAuth 2.0 clients that can access the partition on behalf of a user. An OAuth client is an external application, for example an AI assistant connector or an integration tool. After the user signs in and grants consent, the client receives an access token. The client then calls the Pricefx API with this token instead of a user name and password.

Users with the General Admin or General Admin (without User Management) role can create and manage OAuth clients. Users with the Investigate for Support role can view clients and secrets, but cannot change them. Other users cannot open the page.

How OAuth Works in Pricefx

The partition acts as the OAuth 2.0 authorization server. It implements the Authorization Code Grant flow, as defined in RFC 6749.

1. The client sends the user to the partition's authorization endpoint.

2. The user signs in, either on the Pricefx login page or through a SAML SSO profile.

3. The user grants consent to the client.

4. The partition redirects the user to the client's Redirect URL with a one-time authorization code.

5. The client exchanges the code and its client secret for an access token and a refresh token.

6. When the access token expires, the client uses the refresh token to get a new access token.

The current implementation has these rules:

For the endpoint URLs and request details that the client developer needs, see OAuth Authorization.

Create an OAuth Client

1. Go to Administration > Configuration > External Systems > OAuth Administration.

2. Click Add.

   

3. Enter the Name of the client.

4. Select the Authorization Code type. The Client Credentials type is not supported yet.

5. Select Enabled to allow the client to request tokens. The partition rejects authorization and token requests from a disabled client.

6. On the Clients tab, select the new client.
   The partition generates the Client ID automatically. Enter this Client ID in the configuration of your OAuth client.

7. On the Configuration tab, set the parameters. Enter all TTL values in seconds. All values must be greater than 0. Next to each field, the page shows the value as a readable duration, for example seconds (30 minutes).

   

   • Redirect URL – The URL to which the partition sends the user after a successful authentication. The value must be identical to the redirect_uri that the client sends. Otherwise the partition rejects the request.

   • Token TTL – The lifetime of the access token. When the access token expires, the client uses the refresh token to get a new one. The default is 1,800 seconds (30 minutes). The maximum is 3,600 seconds (1 hour).

   • Idle Refresh Token TTL – The time after which an unused grant expires. The grant is the consent that the user gave to the client. Each token refresh and each API call with an access token starts this period again. When the grant expires, the refresh token and the access tokens stop working, and the user must sign in and give consent again. The value must be greater than the Token TTL. The default is 1,296,000 seconds (15 days). The maximum is 2,592,000 seconds (30 days).

   • Absolute Refresh Token TTL – The maximum lifetime of the grant, counted from the moment the client receives its first tokens. After this time, the user must sign in and give consent again, even if the client used the grant regularly. The value must be greater than or equal to the Idle Refresh Token TTL. The default is 7,776,000 seconds (90 days). The maximum is 15,552,000 seconds (180 days).

   • SAML Profile – The SSO SAML profile that authenticates the user. If you leave it empty, the partition shows the Pricefx login page.

8. Create a client secret:

   1. On the Secrets tab, click New OAuth Secret.

      

   2. Set the Expiry Date and click Add. The earliest date is tomorrow, and the latest date is 365 days from today. The secret stops working at 00:00 UTC on the expiry date.

   3. Copy the secret and enter it in the configuration of your OAuth client. The dialog hides the secret value by default.

Manage Client Secrets

A client can have more than one secret. Use this to rotate secrets without downtime:

1. Create a new secret.

2. Update the OAuth client with the new secret.

3. Disable the old secret.

You can enable a disabled secret again if necessary. The partition rejects a secret from 00:00 UTC on its Expiry Date.

Disable or Delete Clients and Secrets

The table shows how each action affects the tokens that the client already has:

Migration from the oauthConfiguration Application Property

Earlier versions stored OAuth clients in the oauthConfiguration application property. This page replaces it and stores the client secrets securely.

• In version 17.2, partitions still use the oauthConfiguration application property by default. The partition ignores the clients on this page until Pricefx switches it to the new implementation. To use the clients on this page, contact Pricefx Support.

• Pricefx does not migrate existing clients automatically, because they have no client secret. Create each client again on this page and update the client application with the new Client ID and secret.

• After the switch, the partition rejects sign-ins from clients in the oauthConfiguration application property. Their existing access tokens stay valid until they expire, but the clients cannot refresh them.

• If Pricefx switches the partition back to the oauthConfiguration application property, the partition immediately rejects the access tokens of clients on this page. You can still edit clients on this page in that state.

• A future version removes the oauthConfiguration application property.

Related Topics

• OAuth Authorization

• User Roles