Defining operations for protected actions - PingOne - PingOne Cloud Platform

PingOne Cloud Platform

bundle
pingone
ft:publication_title
PingOne Cloud Platform
Product_Version_ce
PingOne
PingOne Cloud Platform
category
Product
p1
p1cloudplatform
ContentType_ce
Page created: 18 May 2023 |
Page updated: 18 May 2023
| 4 min read

PingOne Cloud Platform PingOne Product

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.

  1. Go to Authorize > API Services.
  2. Click your API service, and then click the Operations tab.
  3. To create a new operation, click Define Operation.
  4. Click Methods, and then select one or more methods for the operation. Press Tab or click outside the list to close it.
    Screen capture showing the expanded Methods list in the Create Operation window.
  5. 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

    /accounts/{accountId}/transactions/*

    /accounts/123/transactions

    /accounts/123/transactions/

    /accounts/123/transactions/456

    /accounts/123/transactions/details

    /accounts/*/transactions/*

    /accounts/123/transactions

    /accounts/123/transactions/

    /accounts/123/transactions/456

    /accounts/123/transactions/details

    /accounts/{accountId}/**

    /accounts/123/transactions

    /accounts/123/transactions/

    /accounts/123/transactions/456

    /accounts/123/transactions/details

    /accounts/123/transactions/details/statement

    /accounts/123/settings

    /accounts/{accountId}/transactions/

    /accounts/123/transactions/

    Note:

    Matching requests must end with a slash (/).

    /accounts/{accountId}/transactions

    /accounts/123/transactions

    Note:

    Matching requests must not end with a slash (/).

    For more information, see Path Parameter Pattern Syntax.

    To add another path, click + Add Path.

  6. For Name, enter a name that describes the operation.
    Note:

    You can change the default name, which consists of the method and path separated by request for.

    Screen capture of the Create Operation window showing Method, Paths, and Name settings.
  7. Click Next.
  8. Define either basic or custom access rules for the operation.
    Important:

    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.

    Screen capture of the Create Operation window showing Define Access Rules settings.

Adding basic rules

Page created: 5 Jan 2023 |
Page updated: 9 Jan 2023
| 2 min read

PingOne Cloud Platform PingOne Product
  1. Optional: Define group-based access control rules:
    1. Select the The user must be a member of any of these groups check box.
    2. Click the Groups list, and then select one or more groups. Press Tab or click outside the list to close it.
      Screen capture showing the expanded Groups list in the Create Operation window.
  2. Optional: Define scope-based access control rules:
    1. Select the Client must be authorized with these scopes check box.
    2. Click the Scopes list, and then select one or more scopes. Press Tab or click outside the list to close it.
      Screen capture showing the expanded Scopes list in the Create Operation window.
    3. Optional: To add a new scope, type the name of the scope, and then press Enter.
    4. Click the toggle to change whether all or any of the scopes must be authorized:
      • 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.
      Note:

      All and Any have the same effect when there’s only one scope.

  3. 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

Page created: 9 Mar 2023 |
Page updated: 9 Mar 2023
| 2 min read

PingOne Cloud Platform PingOne Product
  1. Click the Custom toggle, and then click Save.
  2. In the Custom Rules window, select the I understand check box, and then click Switch to Custom Rules.
    Screen capture showing the I Understand check box in the Custom Rules window.

    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.

  3. Expand the new operation and copy the ID. You'll need it later.
    Screen capture showing the ID and the icon to copy it in the expanded operation.
  4. Go to Authorize > Policies, and add a policy.
  5. Target the protected operation in the policy:
    1. In the Applies When section, click + Comparison.
    2. In Select an attribute, select PingOne > API Access Management > Operation > ID.
    3. For the comparator, select Equals.
    4. For the constant, enter the operation ID that you copied in step 3.
      Screen capture showing an Applies When comparison using the operation ID attribute.
  6. Add rules and anything else that you need to complete the policy.
    Tip:

    In addition to attributes defined for your organization, there are many built-in attributes that you can use in custom policies.

  7. 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.