Defining operations for protected actions - PingOne Cloud Platform - PingOne Services - PingOne Authorize - PingOne

PingOne Cloud Platform
bundle
pingone
ft:publication_title
PingOne Cloud Platform
Product_Version_ce
PingOne Cloud Platform
PingOne
category
Administratorguide
ContentType
Guide
Product
Productdocumentation
p1
p1cloudplatform
ContentType_ce
Guide > Administrator Guide
Guide
Product documentation

Operations in PingOne Authorize enable you to use basic access control rules or custom policies to control access to APIapplication programming interface (API) A specification of interactions available for building software to access an application or service. 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 and custom policies for an operation. When these services are managed externally, you can define custom policies for an operation, but 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 that you add users and create groups in PingOne.
  • Authorized OAuthOAuth A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server. scopes. Scopes determine the resources that a client can access. For example, a banking application might use scopes to control the kinds of data shared with third-party applications.

PingOne Authorize automatically generates policies for basic rules and deploys them when you deploy the associated API service.

Tip:

For hands-on experience with defining basic rules for an API operation, see Tutorial 2: Controlling access to specific API operations.

Custom policies

Custom policies handle more complex authorization scenarios, such as evaluating context by pulling in risk scores to determine access. You can enable custom policies when you define an API service, or by editing the API service later.

The following steps provide information about defining an operation with basic rules. For information about custom policies, see Adding custom policies for API services and operations.

  1. Go to Authorization > API Services.
  2. Select 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 ({}). You can add attributes that represent path parameters, to make them easy to use in custom policies. For more information, see API Access Management attributes.

    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. If user directory services and access token validation are managed externally, click Save, then click Deploy.
    Note:

    Basic rules are not available in this situation. Instead, use your external providers, such as PingFederate and PingDirectory, to configure authorized scopes and user groups.

  8. To define basic rules, click Next.
    Screen capture of the Create Operation window showing Define Access Rules settings.
  9. 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.
  10. 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, in the Scopes list, enter 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.

  11. Click Save.
  12. Click Deploy.

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.