PingOne

Defining your API in PingOne Authorize

Define a managed API service to represent your API so that PingOne Authorize can help your API gateway enforce access control.

Before you begin

Configure an API gateway integration kit to connect your API gateway to PingOne.

About this task

An API service allows PingOne Authorize to recognize requests for your API and instruct your API gateway to block access from unauthorized clients and allow access only from authorized clients.

An API service definition specifies:

  • Pointers to the API and to specific parts of the API that you want to protect

  • Whether directory services and access token validation for the API service are managed by PingOne or managed externally

  • The PingOne resource associated with the API service (this is specified only when PingOne manages token validation)

  • Whether custom access control policies for complex authorization scenarios are enabled for the API service

For more details, see API services.

You can define up to 25 API services in each environment.

You must deploy the API service after you make configuration changes, such as updating settings, or adding or updating operations or custom policies.

Steps

  1. Go to Authorization > API Services.

  2. Click the icon next to API Services to add an API service.

  3. For the Name, enter a name that identifies the API service.

    The name must be unique across all API services and resources.

  4. Enter one or more Base URLs for the API represented by the API service.

    You can enter multiple URLs to support aliases for the same service, such as a vanity URL in addition to the domain URL. To add another URL, click Add Base URL. URLs must be valid.
    Screen capture showing the Name, Base URLs, directory and token source, PingOne Resource, and custom policy options in the New API Service window.

  5. Select a user directory and token source.

    Choose from:

    • PingOne SSO (default): PingOne manages user directory services and access token validation for the API service.

    • External Services: The API gateway manages access token validation services through external providers, such as PingFederate. This requires you to configure your API gateway to pass validated token claims to PingOne in decision requests.

      After you save the API service, you can’t change whether the directory and token source are managed by PingOne or by external providers.

  6. Do one of the following.

    Choose from:

    • If you selected External Services, click Save. PingOne Authorize is now configured to recognize the API.

    • If you selected PingOne SSO, complete the remaining steps.

  7. Select a PingOne Resource from the list, or select the option to Automatically create a PingOne Resource.

    This resource is managed by the API service, and there are restrictions against deleting the resource while it’s associated with an API service. Resources created automatically will have the same name as the API service.

  8. To enable custom policies for the API service and its operations, select the Enable Custom Policies check box.

    Result:

    This generates a policy tree for the API service, enabling you to add your own custom authorization policies for the APIs managed by this API service.

    After you save the API service, you can’t change this setting. Custom policies are enabled by default if the API service uses External Services for token validation.

  9. Click Save.

  10. Click Deploy.

  11. On the Advanced tab, click the Pencil icon to add a scope.

    Screen capture of the API Services Advanced tab in PingOne.

  12. In the Name field, enter a name for the scope.

    The scope defines which resources an API client can access. An application requests a scope for the resource associated with an API service in order to set the audience for the access token.

    For consistency, use a lowercase version of the API service name and replace spaces with hyphens.
    Screen capture showing the scope name in Configure Scopes on the API Services Advanced tab in PingOne.

  13. Optional: Enter a description for the scope.

  14. Click Save, and then click Deploy.

    Result:

    PingOne Authorize is now configured to recognize the API.

Next steps

  • If PingOne is managing user directory and access token validation services for the protected API service, add a PingOne application that is allowed to access the protected API service. To allow access, grant the application the same scope that you configured for the API service. For more information, see Editing scopes for an application.

  • To configure built-in access control rules, define operations for protected API actions.

  • For more complex access control scenarios, add custom policies for the API service.