--- title: Configuring API authentication description: Configure authentication for the administrative application programming interface (API) in PingAccess. component: pingaccess version: 9.0 page_id: pingaccess:pingaccess_user_interface_reference_guide:pa_configuring_api_authn canonical_url: https://docs.pingidentity.com/pingaccess/9.0/pingaccess_user_interface_reference_guide/pa_configuring_api_authn.html revdate: May 9, 2024 section_ids: about-this-task: About this task steps: Steps choose-from: Choose from: example: Example: result: Result --- # Configuring API authentication Configure authentication for the administrative application programming interface (API) *(tooltip: \
\

A specification of interactions available for building software to access an application or service.\

\
)* in PingAccess. ## About this task Learn more about the PingAccess Administrative API in [Administrative API Endpoints](../reference_guides/pa_admin_api_endpoints.html). 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 following paths, but has both read and write access to all other endpoints: * `/auth` * `/users` * `/environment` * 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 following: * `/config/\*` * `/backup/` * `/agent/*/config/` To configure API authentication: ## Steps 1. Click **Settings**, 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 *(tooltip: \
\

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

\
)* configuration doesn't require client credentials or a subject attribute name. If you need to create a new access token validator, you can find more information about the field configurations in [Adding access token validators](pa_adding_access_token_validators.html). 5. Enter the **Client ID** assigned to you when you created the OAuth client for validating OAuth access tokens. Learn more about configuring a client ID in PingFederate in [Configuring OAuth clients](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_configuring_oauth_clients.html). 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) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)*. 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. Learn more about defining scopes in PingFederate in [Configuring authorization server settings](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/help_authorizationserversettingstasklet_oauthauthorizationserversettingsstate.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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](pa_token_provider.html) or [admin token provider](pa_configuring_an_admin_token_provider.html): 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](https://www.rfc-editor.org/rfc/inline-errata/rfc9449.html#:~:text=Next%20Nonce%20Value-,9.%20%20Resource%20Server%2DProvided%20Nonce,-Resource%20servers%20can), 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) *(tooltip: \
\

An open, cross platform protocol used for interacting with directory services.\

\
)* 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) *(tooltip: \
\

A name uniquely identifying an object within the hierarchy of a directory tree.\

\
)*. 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](https://www.rfc-editor.org/rfc/rfc1779) or [RFC-2253](https://www.rfc-editor.org/rfc/rfc2253). 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.