PingAccess

Configuring API authentication

Configure authentication for the administrative application programming interface (API) in PingAccess.

About this task

For more information on the PingAccess Administrative API, see Administrative API Endpoints.

You can configure roles for Administrative API users. Each role grants access to specific features.

  • The Administrator role has full read and write access to the Admin API, unless the Platform Administrator role is enabled. If the Platform Administrator role is enabled, the Administrator only has read access to the Admin API endpoints under the /auth, /users, and /environment paths, and has both read and write access to all other endpoints.

  • The Platform Administrator role has full read and write access to the Admin API. This role can be used with the Administrator role to grant full access to most features without the possibility of accidental lockout, with only the Platform Administrator able to change authorization configurations.

  • The Auditor role has read access to all Admin API endpoints except for the /config/*, /backup/, and /agent/*/config/ endpoints.

Steps

  1. Click Settings and then go to Admin Authentication → API Authentication.

  2. Go to System → Admin Authentication → Admin API OAuth.

  3. To enable API OAuth authentication, select OAuth.

  4. Click the Properties tab.

  5. Optional: From the Access Token Validator Type list, select a local access token validator to use instead of remote token validation for Admin API authentication.

    If you select a local access token validator, the OAuth configuration does not require client credentials or a subject attribute name.

  6. Enter the Client ID assigned to you when you created the OAuth client for validating OAuth access tokens.

    For more information about configuring a client ID in PingFederate, see Configuring a Client.

  7. Optional: Select a Client Credentials Type, then enter the information for the selected credential type.

    Choose from:

    • Secret – Enter the Client Secret you were assigned when you created the PingAccess OAuth client in the token provider.

    • Mutual TLS – Select a configured Key Pair to use for Mutual TLS client authentication.

    • Private Key JWT – Select this option to use Private Key JSON web token (JWT). No additional information is required.

  8. Enter the Subject Attribute Name you want to use from the OAuth access token as the subject for auditing purposes.

    At runtime, the attribute’s value is used as the Subject field in audit log entries for the admin API.

  9. Select the Scope required to successfully access the API. For more information about defining scopes in PingFederate, see Authorization Server Settings.

  10. If you want to enable role-based authorization, perform the following steps:

    1. Click the Roles tab.

    2. To enable role-based authentication, select Enable Roles.

    3. In the Administrator section, click Add Required Attribute as many times as you need.

      For a role to be granted, all configured attribute values must match.

    4. Enter an Attribute Name and Attribute Value for each required attribute.

      If you are using PingFederate as a token provider, the attribute name is defined in PingFederate under OAuth Settings → OpenID Connect Policy Management → Your_Policy → Attribute Contact as an extension to the contract. The value you use depends on the configuration of the Contract Fulfillment tab for the policy.

      Example:

      The attribute named group in your attribute contract can be mapped to an Lightweight Directory Access Protocol (LDAP) server attribute source that contains a groupMembership attribute. A valid group membership for the administrator might be the group cn=pingaccess-admins,o=myorg. In this example, you should use group as the Attribute Name and cn=pingaccess-admins,o=myorg as the Attribute Value.

    5. Optional: If you want to add platform administrators, select Enable Platform Administrator Role, then enter an Attribute Name and Attribute Value for each required attribute. Click Add Required Attribute to add a new attribute.

    6. Optional: If you want to add auditors, select Enable Auditor Role, then enter an Attribute Name and Attribute Value for each required attribute. Click Add Required Attribute to add a new attribute.

  11. To activate API authentication, click Save.