PingAccess

Protecting an API with PingAccess in a gateway deployment

You can protect an application programming interface (API) from unwanted access using PingAccess.

Prerequisites

Before configuring your PingAccess deployment to protect an API:

Steps

After you have completed the following steps, your API is protected.

  1. Configure a virtual host – A virtual host represents the external face of the API you will protect.

  2. Configure a site – A site contains the internal details of the API you will protect, including its actual location.

  3. Configure a rule – Rules control who can access what content under what circumstances.

  4. Configure an identity mapping – An identity mapping lets you share identity information with the protected API as 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 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.

Steps

  1. Click Applications and then go to Applications → Virtual Hosts.

  2. Click 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.

Steps

  1. Click Applications and then go to Sites → Sites.

  2. Click 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 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 and Creating trusted certificate groups.

  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 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 section according to your needs.

Steps

  1. Click Access and then go to Rules → Rules.

  2. Click 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 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.

Steps

  1. Click Access and then go to Identity Mappings → Identity Mappings.

  2. Click 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 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.

For more information about this procedure, including optional steps that are not included here, see Adding an application.

Steps

  1. Click Applications and then go to Applications → Applications.

  2. Click 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 and then go to Applications → Applications.

  10. Expand the new application in the list and click the pencil icon pin1564006721753.

  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.

Steps

  1. Click Applications and 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 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) 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.