--- title: Protecting an API with PingAccess in a gateway deployment description: You can protect an application programming interface (API) from unwanted access using PingAccess. component: pingaccess version: 9.1 page_id: pingaccess:pingaccess_use_cases:pa_protecting_an_api_with_pa_in_a_gateway_deployment canonical_url: https://docs.pingidentity.com/pingaccess/9.1/pingaccess_use_cases/pa_protecting_an_api_with_pa_in_a_gateway_deployment.html llms_txt: https://docs.pingidentity.com/pingaccess/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: March 27, 225 section_ids: prerequisites: Prerequisites steps: Steps configuring-a-virtual-host: Configuring a virtual host about-this-task: About this task steps-2: Steps configuring-a-site: Configuring a site about-this-task-2: About this task steps-3: Steps configuring-a-rule: Configuring a rule about-this-task-3: About this task steps-4: Steps configuring-an-identity-mapping: Configuring an identity mapping about-this-task-4: About this task steps-5: Steps configuring-an-application: Configuring an application about-this-task-5: About this task steps-6: Steps configuring-a-resource: Configuring a resource about-this-task-6: About this task steps-7: Steps --- # Protecting an API with PingAccess in a gateway deployment You can protect an application programming interface (API) *(tooltip: \
\

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

\
)* from unwanted access using PingAccess. ## Prerequisites Before configuring your PingAccess deployment to protect an API: * PingAccess must be installed and running. You can find the full procedure in [Installing and Uninstalling PingAccess](../installing_and_uninstalling_pingaccess/pa_installing_and_uninstalling_pa.html). * You must have a configured token provider. The procedures vary depending on the token provider. Learn more in: * [PingFederate](../pingaccess_user_interface_reference_guide/pa_pf.html). * [PingOne](../pingaccess_user_interface_reference_guide/pa_p1.html). * [Common token provider](../pingaccess_user_interface_reference_guide/pa_common_token_provider.html). ## Steps Complete the following steps to protect your API: 1. Configure a virtual host. A virtual host represents the external face of the API you'll protect. 2. Configure a site. A site contains the internal details of the API you'll protect, including its actual location. 3. Configure a rule. Rules determine who can access what content and under which circumstances. 4. Configure an identity mapping. An identity mapping enables you to pass identity information to the protected application using headers. 5. Configure an application. An application joins the other pieces together, giving users access to the API according to the configured rules. 6. Configure a resource. A resource specifies an API endpoint *(tooltip: \
\

One end in a communication channel, typically a URI.\

\
)* and the methods that can be used to access it. ## Configuring a virtual host ### About this task The virtual host is the external-facing portion of an API. In a proxy deployment, the virtual host contains the host name and port that your users use to reach the protected API. For more information about this procedure, including optional steps that are not included here, see [Creating new virtual hosts](../pingaccess_user_interface_reference_guide/pa_creating_new_virtual_hosts.html). ### Steps 1. Click **Applications**, then go to **Applications > Virtual Hosts**. 2. Click **[icon: plus, set=fa]Add Virtual Host**. 3. In the **Host** field, enter the name for the virtual host. This is the host name used by end users to reach the site. For example, myHost.com. You can use a wildcard (`*`) for part or all of the host name. For example, `*.example.com` matches all host names ending in .example.com, and `*` matches all host names. 4. In the **Port** field, enter the port number for the virtual host. For example, `443`. 5. Click **Save**. ## Configuring a site ### About this task A site is only used in a proxy deployment. It contains the target address for the protected API and any other information necessary to access the application. For more information about this procedure, including optional steps that are not included here, see [Adding sites](../pingaccess_user_interface_reference_guide/pa_adding_sites.html). ### Steps 1. Click **Applications**, then go to **Sites > Sites**. 2. Click **[icon: plus, set=fa]Add Site**. 3. In the **Site Name** field, enter a unique name of up to 64 characters, including special characters and spaces. This name is used internally. 4. In the **Targets** field, enter one or more targets. These targets are the actual locations of the site. The format for this is `hostname:port` or `IP address:port`. For example, `www.example.com:80`. 5. Select the **Secure** check box if the site is expecting HTTPS connections. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This decision depends on whether the target expects an HTTPS connections from the PingAccess system to the protected web application.If you select **Secure**, you must also select a **Trusted Certificate Group** from the list, or select **Trust Any** to trust any certificate *(tooltip: \
\

A digital file used for identity verification and other security purposes. The certificate, which is often issued by a CA, contains a public key, which can be used to verify the originator's identity.\

\
)* presented by the listed targets. The trusted certificate group defines what certificates or issuing certificate authorities PingAccess will trust when acting as a client to the backend server. For information about importing a certificate and creating a trusted certificate group, see [Importing certificates](../pingaccess_user_interface_reference_guide/pa_importing_certificates.html) and [Creating trusted certificate groups](../pingaccess_user_interface_reference_guide/pa_creating_trusted_certificate_groups.html). | 6. Click **Save**. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------- | | | If the target site cannot be contacted, PingAccess saves the site and a displays a warning indicating the reason the site could not be reached. | ## Configuring a rule ### About this task Rules are used to control the circumstances under which users can access the protected API. Rules can grant or deny access based on criteria such as user parameters from the token provider, header values, network ranges, or web session attributes. You can configure any number of rules in your environment. You can combine rules into rule sets, which combine multiple rules. You can configure rule sets to allow access to a resource if at least one rule's criteria is met, or to only allow access if all rules have their criteria met. Access control rules are processed before processing rules. Each type of rule is otherwise processed in the order you specify when you create the rule set. You can further combine rule sets into rule set groups, which combine multiple rule sets. As with rule sets, rule set groups can allow access if any one rule set's criteria are met, or only if all rule sets' criteria are met. Rule sets are processed in the order you specify when you create the rule set group. This example uses an HTTP request *(tooltip: \
\

A client transaction sent over HTTP to the server specifying a request method, such as GET, POST, and DELETE, to execute against a resource or resources on the server.\

\
)* header rule to demonstrate how rules are created and used. Each environment has different requirements, and you can use any of the rules explained in the [Rule management](../pingaccess_user_interface_reference_guide/pa_rule_management.html) section according to your needs. ### Steps 1. Click **Access**, then go to **Rules > Rules**. 2. Click **[icon: plus, set=fa]Add Rule**. 3. In the **Name** field, enter a unique name. The name can be up to 64 characters long. Special characters and spaces are allowed. 4. From the **Type** menu, select **HTTP Request Header**. 5. In the **Field** column, in the **Header** field, enter the HTTP header *(tooltip: \
\

A section of an HTTP request or response that conveys additional information relevant to the client or server in the transaction.\

\
)* name you want to match in order to grant or not grant the client access. 6. In the **Value** field, enter the values for the header you want to match in order to grant or not grant the client access. The wildcard (`*`) character is supported. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you want to match on the `Host` header, include both the host and port in the **Value** field, or add a wildcard after the host name (`host*` or `host:*`) to match what is in the HTTP request. | 7. If you need additional header pairs, click **Add Row** to add an additional row, then repeat steps 5-6. 8. Click **Save**. ## Configuring an identity mapping ### About this task A header identity mapping can expose one or more attribute values to the protected API in HTTP request headers. For more information about this procedure, including optional steps that are not included here, see [Creating header identity mappings](../pingaccess_user_interface_reference_guide/pa_creating_header_identity_mappings.html). ### Steps 1. Click **Access**, then go to **Identity Mappings > Identity Mappings**. 2. Click **[icon: plus, set=fa]Add Identity Mapping**. 3. In the **Name** field, enter a name for the mapping. 4. From the **Type** list, select **Header Identity Mapping**. 5. In the **Attribute to Header Mapping** section, in the **Attribute Name** field, enter the name of the attribute to retrieve from the user web session. For example, `sub`. 6. In the **Header Name** field, enter the name of the header to contain the attribute value. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The HTTP header you specify here is the actual header name over the HTTP protocol, not an environment variable interpreted format. For example, enter the `User-Agent` browser type by identifying the header as `User-Agent`, not `HTTP_USER_AGENT`. | 7. In the **Certificate to Header Mapping** section, enter the header name included in a PEM-encoded client certificate. The row position correlates to the index in the client certificate chain. For example, the first row always maps to the leaf certificate. If you are using a certificate chain, click **[icon: plus, set=fa]Add Row** to add another row. 8. Click **Save**. ## Configuring an application ### About this task The application represents the protected API as a whole. By including the virtual host and the site, it allows PingAccess to route requests directed at the front-end name to the correct back-end resource. After you create the application and its root resource, you can add one or more rules to control access to the protected API. Within the application, you can add one or more resources. Resources are specific components that require a different degree of security. You can apply different rules to a resource, letting you apply specific controls to portions of an application. This example procedure does not include resources. For information about adding resources to an application, see [Configuring resource ordering in PingAccess](../pingaccess_user_interface_reference_guide/pa_configuring_resource_ordering.html). For more information about this procedure, including optional steps that are not included here, see [Adding an application](../pingaccess_user_interface_reference_guide/pa_adding_an_app.html). ### Steps 1. Click **Applications**, then go to **Applications > Applications**. 2. Click **[icon: plus, set=fa]Add Application**. 3. In the **Name** field, enter a unique name for the application, up to 64 characters, including special characters and spaces. 4. In the **Context Root** field, enter the context root for the API. This represents the context at which all of the API endpoints are accessed at the site. The context root must meet the following criteria: * It must start with `/`. * It can contain additional `/` path separators. * It must not end with `/`. * It must not contain wildcards or regular expression strings. * The combination of the **Virtual Host** and **Context Root** must be unique. 5. From the **Virtual Host** list, select the virtual host you created. 6. In the **Application Type** section, select **API**. 7. In the **Destination** section, select **Site**, then select the site you created. 8. Click **Save**. 9. Click **Applications**, then go to **Applications > Applications**. 10. Expand the new application in the list and click the pencil icon ![pin1564006721753](_images/pin1564006721753.jpg). 11. Click the **Web Policy** tab. 12. Drag your rule from **Available Rules** onto the policy bar. 13. Click **Save**. ## Configuring a resource ### About this task An application resource is a component within an application that requires a different level of security. By configuring resources for your API endpoints, you can add different rules for different endpoints and specify which methods are allowed. For more information about this procedure, including optional steps that are not included here, see [Adding application resources](../pingaccess_user_interface_reference_guide/pa_adding_application_resources.html). ### Steps 1. Click **Applications**, then go to **Applications > Applications**. 2. Click to expand the application you created in the previous procedure. 3. Click the **Pencil** icon. 4. Click the **Resources** tab. 5. Click **[icon: plus, set=fa]Add Resource**. 6. In the **Name** field, enter a unique name up to 64 characters, including special characters and spaces. 7. In the **Path Patterns** field, enter a list of Uniform Resource Locator (URL) *(tooltip: \
\

Identifies a resource according to its internet location.\

\
)* path patterns, within the context root, that identify this resource. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The path pattern must start with a forward slash (/). It begins after the application context root and extends to the end of the URL.When automatic path pattern evaluation ordering is in use (default), patterns can contain one or more wildcard characters (`*`). No use of wildcards is assumed. For example, there is a difference between `/app/` and `/app/*`. If a request matches more than one resource, the most specific match is used. | 8. In the **Resource Authentication** section, select **Standard**, using the same authentication for the resource as for the root application. 9. In the **Methods** field, enter the methods supported by the resource. Leave the asterisk default if the resource supports all HTTP methods, including custom methods. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Defining methods for a resource allows more fine-grained access control policies on API resources. If you have a server optimized for writing data (POST, PUT) and a server optimized for reading data (GET), you might want to segment traffic based on the operation being performed. | 10. To log information about the transaction to the audit store, select the **Audit** check box. 11. To enable the resource, select the **Enabled** check box. 12. Click **Save**.