OAuth 2.0 application registration

A FoxIDs OAuth 2.0 application registration represents either a protected API resource or a backend application using machine-to-machine authentication. Register an API to expose scopes, and register a Backend Application to obtain access tokens with Client Credentials Grant.

FoxIDs OAuth 2.0 application registration

Key capabilities include multiple API audiences in one access token, scoped API access, client authentication with secrets or certificates, claim transformation and token exchange.

Configuration

In FoxIDs Control:

  1. Select the environment in which the API or backend application should be registered.
  2. Open Applications and click Add application.
  3. Enable Show all options.
  4. Choose API or Backend Application.
  5. Configure the application and click Create.

Choose an OAuth 2.0 application type

After creation, click Change application to review or change the complete application settings. Enable Show advanced only when the required setting is advanced.

OAuth 2.0 API

Choose API to register a protected backend API as an OAuth 2.0 resource. The API registration defines its resource name, scopes and the audience used in access tokens.

The following example registers a Customers API:

  1. Enter Customers as the Name.
  2. Enter customers-api as the Resource name.
  3. Add the scopes read and write.
  4. Click Create.

Create an OAuth 2.0 API with scopes

The complete scope values are customers-api:read and customers-api:write. A client requests one or both values from the token endpoint, and the resulting access token includes customers-api as an audience.

The API must validate the access token issuer, audience, lifetime and required scope. A calling application is granted access separately by adding the API resource and the scopes it may request.

Backend application and Client Credentials Grant

Choose Backend Application for a service, daemon, scheduled job or background process. FoxIDs creates it as a confidential client that requests an access token without a user by using Client Credentials Grant.

The following example creates the calling service:

  1. Enter Backend service as the Name.
  2. Enter backend-service as the Client ID, or let FoxIDs generate it.
  3. Copy the generated Client secret before leaving the creation result. The complete generated secret is shown only during creation.
  4. Click Create.

Create an OAuth 2.0 backend application

Grant access to an API

After creating the backend application, click Change application and configure Resource and scopes on the OAuth 2.0 Client tab:

  1. Keep Default resource 'backend-service' for the application itself cleared because this client is not acting as its own API.
  2. Click Add Resource and scopes.
  3. Enter customers-api as the Resource.
  4. Add the read and write scopes.
  5. Click Update.

Allow a backend application to call the Customers API

The backend application can now request customers-api:read, customers-api:write or both. Scopes requested by the client are validated against the scopes exposed by the API registration.

Access tokens can contain multiple audiences and therefore grant access to multiple APIs registered as OAuth 2.0 resources in FoxIDs. Add each required resource and its permitted scopes to the backend application.

Client authentication

The default token-endpoint client authentication method is client secret post. To change it, click Change application, enable Show advanced, and select:

  • client secret basic to send the client ID and secret using HTTP Basic authentication.
  • client secret post to send the client ID and secret in the token request body.
  • private key JWT to authenticate with a signed client assertion.

Configure OAuth 2.0 client authentication

Up to 10 secrets and 4 client certificates can be configured to support credential rotation. Store secrets and private keys securely and do not write them to source code or logs.

The following request uses the default client secret post method to obtain an access token for the Customers API:

POST https://foxids.com/tenant-x/environment-y/backend-service(*)/oauth/token HTTP/1.1
Host: foxids.com
Content-Type: application/x-www-form-urlencoded

client_id=backend-service
&client_secret=<client-secret>
&grant_type=client_credentials
&scope=customers-api%3Aread

The token response contains an access token for the customers-api audience with the customers-api:read scope.

Authenticate with a certificate

Select private key JWT and upload the client certificate after creating the backend application. The client keeps the corresponding private key and signs a short-lived client assertion for each token request.

Register overlapping certificates before replacing an expiring certificate so that the client can rotate keys without interrupting token requests.

Client secrets

FoxIDs hashes client secrets using the configured password hash algorithm. A generated secret cannot be recovered after creation. For secrets longer than 20 characters, FoxIDs retains the first three characters as identification information and displays them with an ellipsis, for example 6j9....

Add a replacement secret before removing the previous one to rotate credentials without downtime.

Claims issued to a client or API can be changed with claim transforms and claim tasks.

Resource Owner Password Credentials Grant

FoxIDs does not support Resource Owner Password Credentials Grant because it requires the application to handle the user's password and is not suitable for secure modern authentication.

Request parameters

Configure Allowed request parameters to make selected values from the client-credentials or token-exchange request available as _local:params:{name} claims. See application request parameters for configuration, space-separated lists and limits.