Operations in PingOne Authorize enable you to use basic access control rules or custom policies to control access to API actions.
An API service operation is a method and path combination that matches a client request to the API. Add operations for API requests that you want to protect.
When PingOne is managing user directory services and access token validation for an API service, you can define built-in access control rules or custom policies for an operation. When these services are managed externally, you can only define custom policies for an operation; you can’t configure built-in access control rules.
- Basic rules
Basic rules grant access to protected operations based on:
- User membership in groups. Before you grant access based on group membership, make sure you add users and create groups in PingOne.
- Authorized OAuth scopes. Scopes determine the resources that a client can access. For example, banking applications use scopes to control what data is shared with third-party applications.
PingOne Authorize automatically generates policies for basic rules and deploys them to the API Access Management endpoint.Tip:
For hands-on experience with defining basic rules for an API operation, see Tutorial 2: Controlling access to specific API operations.
- Custom rules
Custom rules enable you to use fine-grained policies that evaluate context to determine access. After you opt into using custom rules for an operation, create a policy that targets the operation and deploy the policy to the decision endpoint specified for the API service.Tip:
For hands-on experience with writing a custom policy for an API operation, see Tutorial 3: Fine-grained API authorization.
- Go to .
- Click your API service, and then click the Operations tab.
- To create a new operation, click Define Operation.
Click Methods, and then select one or more methods for
the operation. Press Tab or click outside the list to close it.
Enter one or more API Paths for the operation.
Paths must start with a slash (/) and match requests for resources and subresources exactly, unless you use wildcards or parameters. A single wildcard (*) represents one path segment. A double wildcard (**) represents one or more segments at the end of the path. Surround parameters with curly braces.
The following table provides examples of path definitions and matching requests for account resources and subresources, such as transactions. For paths with wildcards, only a few of the possible matches are shown.
Path Examples of matching requests
Matching requests must end with a slash (/).
Matching requests must not end with a slash (/).
For more information, see Path Parameter Pattern Syntax.
To add another path, click + Add Path.
For Name, enter a name that describes the
You can change the default name, which consists of the method and path separated by request for.
- Click Next.
Define either basic or custom access rules for the operation.
If you define custom rules, you can’t go back to using basic access rules for the operation.
Basic rules are not available when user directory services and access token validation are managed externally. Instead, use your external providers, such as PingFederate and PingDirectory, to configure authorized scopes and user groups.
Adding basic rules
Define group-based access control rules:
- Select the The user must be a member of any of these groups check box.
Click the Groups list, and then select one or
more groups. Press Tab or click outside the list to close it.
Define scope-based access control rules:
- Select the Client must be authorized with these scopes check box.
Click the Scopes list, and then select one or
more scopes. Press Tab or click outside the list to close it.
- Optional: To add a new scope, type the name of the scope, and then press Enter.
Click the toggle to change whether all or any of the scopes must be
- All: The default option. This allows access if a client is authorized for all of the scopes. This is equivalent to adding a Boolean AND operator between scopes.
- Any: Allows access if a client is authorized for any of the scopes. This is equivalent to adding a Boolean OR operator between scopes.
All and Any have the same effect when there’s only one scope.
- Click Save.
If you defined scope-based rules for the operation, make sure you grant the same scopes to PingOne applications so that clients are allowed to access the API operation. To do this, edit the list of allowed scopes on the application’s Resources tab. For more information, see Editing scopes for an application.
Adding custom rules
- Click the Custom toggle, and then click Save.
In the Custom Rules window, select the I
understand check box, and then click Switch to Custom
If a decision endpoint hasn’t been defined yet for custom policy deployment, you can select an endpoint in the Choose a Decision Endpoint list. The list is not displayed if an endpoint has already been defined for the API service.
Expand the new operation and copy the ID. You'll need it
- Go to add a policy. , and
Target the protected operation in the policy:
- In the Applies When section, click + Comparison.
- In Select an attribute, select .
- For the comparator, select Equals.
For the constant, enter the operation ID that
you copied in step 3.
Add rules and anything else that you need to complete the policy.
In addition to attributes defined for your organization, there are many built-in attributes that you can use in custom policies.
Click Save changes.
You see the new policy on the Policies tab.
Test and then publish your policy. For more information, see Testing a policy and Publishing a version.