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, then the Administrator only has read access to the Admin API endpoints under the /auth, /users, and /environment paths, but 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.

To configure API authentication:

Steps

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

  2. To enable API OAuth authentication, select OAuth.

  3. Click the Properties tab.

  4. Optional: In 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.

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

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

  7. Enter the Subject Attribute Name that 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.

  8. Select the Scope required to successfully access the API.

    For more information about defining scopes in PingFederate, see Authorization Server Settings.

    If the administrative token is validated by a local access validator, the administrative API OAuth doesn’t enforce whether an administrative token contains a scope claim with a configurable value.

  9. Optional: If you want to configure different DPoP settings for API authentication than the global DPoP settings that you configured in the token provider or admin token provider:

    1. Select Override DPoP Settings.

    2. In the DPoP Type list, select the level of OAuth 2.0 Demonstrating Proof of Possession (DPoP) support that you want to enable for access token validation:

      • Off (default): PingAccess doesn’t accept DPoP-bound access tokens, only bearer tokens.

      • Enabled: PingAccess accepts both bearer tokens and DPoP-bound access tokens.

      • Required: PingAccess doesn’t accept bearer tokens, only DPoP-bound access tokens.

    3. To require each DPoP proof to contain a nonce value during validation that was provided by PingAccess when the access token was created, per RFC 9449 section 9, select Require Nonce.

      This check box is cleared by default.

    4. In the DPoP Proof Lifetime (SEC.) field, enter the duration, in seconds, that a DPoP proof should be considered valid after it’s issued.

      As a security best practice, keep this value low and consistent with the DPoP implementation of your API client. The default value is 120 seconds.

  10. If you want to enable role-based authorization:

    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. Select 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 → Access Token Mappings → Your_Policy → Attribute Contact as an extension to the contract.

      The value that you use depends on the configuration of the Contract Fulfillment tab for the policy. Copy-paste your attribute value to ensure accuracy.

      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. In the Matching Strategy list, select the context that you want PingAccess to evaluate requests with when looking for a match.

      Case-Sensitive

      To register as a match, the attribute value in the request must be written in the same case as the attribute value that you specify in step 7. By default, PingAccess uses this matching strategy.

      Case-Insensitive

      Case doesn’t matter when looking for a match. Select this option for more flexibility if you might make changes to the attribute source that don’t alter it semantically.

      DN Matching

      Normalizes both the attribute value that you specify in step 7 and any attribute value that PingAccess gathers at runtime from the user identity attributes as an X.500 distinguished name (DN). PingAccess then looks for a match between the distinguished names.

      • If you select DN Matching, make sure to select an Attribute Name in step 5 that can contain a DN. The administrative console doesn’t provide a warning if you select an invalid attribute type, but you can check your log files to confirm that you don’t have any DN-related errors.

      • PingAccess validates the Attribute Value that you specify in step 7 to make sure that it’s a valid X.500 DN that follows RFC-1779 or RFC-2253. Copy-paste the attribute value to ensure accuracy.

      • Relative DNs that have non-printable or non-UTF-8 string values, such as email and domain component (DC) relative DNs, are case-sensitive. Otherwise, relative DN values are case-insensitive.

    6. Optional: To add platform administrators:

      1. Select the Enable Platform Administrator Role check box.

      2. Select an Attribute Name, Matching Strategy, and Attribute Value for each required attribute.

      3. To add a new attribute, click Add Required Attribute.

    7. Optional: To add auditors:

      1. Select the Enable Auditor Role check box.

      2. Select an Attribute Name, Matching Strategy, and Attribute Value for each required attribute.

      3. To add a new attribute, click Add Required Attribute.

  11. Click Save.

Result

You have activated API authentication.