Resources

A resource is the definition of the RESTful API being protected.

The simplistic view of an API is the combination of a HTTP method and path. For example, GET /scim/groups. The API Access Control component provides an extended configuration mechanism which allows more than just the method and path to be specified. It provides a way to:

1. Create the protected object representing the method and path.

2. Specify any URL aliases that should map to the specified path. This includes the ability to use a wildcard character (*). These are applied through the use of a HTTP transformation rule.

3. Specify a rate limiting policy that is applied to any requests to the resource.

4. Set the authentication policy for all requests to the resource.

5. Set static response headers that are set on every response to requests to the resource. These are applied through the use of a HTTP transformation rule.

6. Set a documentation file that can be returned when requests to the resource specify a certain content type in the accept header. This is applied through the use of a HTTP transformation rule. See Resource Documentation.

The base level operations that occur internally when creating a new resource include:

• The protected object is created.
• A new ACL may be created representing the authentication policy. This ACL is then attached to the new protected object.
• The Reverse Proxy configuration file is updated with:
  • A mapping of the resource description to the protected object name.
  • Any new HTTP transformation rule specifications.
  • Activation of the specified rate limiting policy.

• The rate limiting policy is updated to include the new method and path as a resource.
• A new request HTTP Transformation rule is created. This rule:
  • Has a name formatted as : “Request_” + instance name + resource server path + method + path. For example, Request_default_testGET_test.
  • Contains a rule to set the protected object used for the authorisation check to the required API Access Control protected object name.
  • Map any URL aliases back to the main resource path.
  • Forward the request onto the documentation file if the accept header matches the specified documentation content type.

• A new response HTTP transformation rule is created. This rule:
  • Has a name formatted as : “Response_” + instance name + resource server path + method + path. For example, Response_default_testGET_test.

  • Sets any static response headers.

The following is an example API Access Control Request Transformation Rule (Request_default_scimGET_scim_groups):

<?xml version="1.0" encoding="UTF-8"?>
  <xsl:stylesheet version="1.0"
     xmlns:external="http://xsltfunctions.isam.ibm.com"
     xmlns:xsl="http:/www.w3.org/1999/XSL/Transform">

  <!--This stylesheet is used to set static response headers in the HTTP Response for the GET /test resource.-->

  <!--Firstly, strip any space element-->
  <xsl:strip-space elements="*"/>

  <xsl:template match="/">
    <HTTPRequestChange>
      <xsl:apply-templates
        select="//HTTPRequest/Headers/Header[@name = 'accept']"/>
      <xsl:apply-templates select="//HTTPRequest/RequestLine"/>

      <!--Set the ACL bits that will be used for authorisation for this resource.-->
      <AclBits>T</AclBits>

      <!--Set the object name which will be used in the authorization decision.-->
      <ObjectName>/WebSEAL_API/isam.test.ibm.com-default/scim/GET/scim/groups</ObjectName>
    </HTTPRequestChange>
  </xsl:template>
  <!--Handle any URL aliasing-->
  <xsl:template match="//HTTPRequest/RequestLine">
    <xsl:choose>
      <xsl:when test="external:matches(URI, ‘^/scim/groups/.*’)”>
        <URI>
          <xsl:value-of
            select="external:replace(URI, ‘/scim/groups/(.*)’, ‘/scim/groups$1')"/>
        </URI>
      </xsl:when>
    </xsl:choose>
  </xsl:template>
  <!--Manage any requests for documentation using the accept header.-->
  <xsl:template match="//HTTPRequest/Headers/Header[@name = 'accept']">
    <xsl:if test="node()=‘application/swagger.json'">
      <URI>/apiac/scim/groups.json</URI>
    </xsl:if>
  </xsl:template>
</xsl:stylesheet>

The following is an example API Access Control Response Transformation Rule (Response_default_scimGET_scim_groups):

<?xml version="1.0" encoding="UTF-8"?>
  <xsl:stylesheet version="1.0"
    xmlns:external="http://xsltfunctions.isam.ibm.com"
    xmlns:xsl="http:/www.w3.org/1999/XSL/Transform">

  <!--This stylesheet is used to set static response headers in the HTTP Response for the GET /test resource.-->
  <!--Firstly, strip any space element-->

  <xsl:strip-space elements="*"/>
  <xsl:template match="/">
    <HTTPResponseChange>
      <Header action="add" name="Strict-Transport-Security">true</Header>
    </HTTPResponseChange>
  </xsl:template>
</xsl:stylesheet>

Due to the different mix of IBM Security Verify Access operations performed, there are some tasks which are completed immediately (for example, pdadmin tasks) and some tasks that are not completed until the next commit operation is executed. This means there might be orphaned protected objects, ACLs and POPs if the creation is followed by a rollback of the pending changes. Therefore, take precaution if the administrator chooses to roll back the pending changes instead of deploying them. Take the following actions, if a cleanup or audit of orphaned API Access Control artifacts is required:

• Objects under the /WebSEAL_API object space must be reviewed and unnecessary objects removed;
• ACLs that have a suffix of "_resource_access_control_policy" must be reviewed and unnecessary ACLs must be removed.

Deletion of a resource that has a rate limiting policy applied results in the method and path being removed from the rate limiting policy file but the policy is not removed from the Reverse Proxy configuration file. If the rate limiting policy is no longer required, it can be manually removed from the '[rate-limiting]' stanza of the Reverse Proxy configuration file.

Parent topic: Overview of the API Access Control