Using OAuth scopes for ACI rules with the REST API

To help isolate access to admin credentials in authentication workflows, you can use OAuth scopes to enforce ACIs for users authenticating to specific Directory REST API endpoints.

About this task

When users make requests to Directory REST API endpoints, they are required to authenticate. Depending on the configured authentication policy, they could be prompted for credentials and issued an OAuth 2.0 bearer token in exchange.

After receiving the token, users can be granted OAuth scopes by a token validator, such as PingFederate. PingDirectory can then apply user-configured ACIs to those scopes, enabling the REST API to provide the permissions for the user and the request.

You must have an encryption settings definition configured on the server before using OAuth scopes with the Directory REST API. Learn more in Creating encryption settings definitions.
In a proxied configuration, PingDirectoryProxy can still pass OAuth scopes to PingDirectory for REST API requests.
Some Directory REST API endpoint requests don’t support this feature.

Creating ACIs with OAuth scopes

Executing a request to the REST API using an OAuth bearer token depends on both the configured ACIs in the PingDirectory server and the scopes used to authenticate the request present in the provided OAuth bearer token.

To enable PingDirectory to apply ACIs to specific OAuth scopes, you need to define these ACIs with the desired scopes using the oauthscope bind rule. Learn more about ACIs in ACI syntax and ACI bind rules.

Example

You can add the following ACI to PingDirectory to allow all authenticated users with the OAuth scope example:scope to perform the Get Password Quality Requirements extended operation:

(extop="1.3.6.1.4.1.30221.2.6.43")(version 3.0; acl "Extended op permissions for get password quality requirements"; allow (read) oauthscope="example:scope";)

With the ACI added, the authenticating user can send a POST request to the /directory/v1/passwordRequirements endpoint, which performs this extended operation on the backend. You can find details about this endpoint in Get Password Quality Requirements .

If the example:scope OAuth scope is validated in the bearer token included in the HTTP Authorization Header of the request (and no other ACIs explicitly deny the user’s privilege to perform the extended operation), then the user will get a successful HTTP response.