Security Policy Manager

Home > Developing > Authorization Web Service

Authorization Web Service

The authorization web service is available as a way to query the runtime security services server for authorization decisions. This model can be used in any environment where a web service client can be deployed.

1 Setting up the environment
2 Operations:
3 Authorization requests
- 3.1 Subject:
- 3.2 Resource:
- 3.3 Action:
- 3.4 Environment:
4 Entitlement requests

The authorization web service allows you to send XACML requests to your runtime security services server using the SOAP protocol. While IBM does not provide a pre-built web service client, the WSDL and associated files are provided as an attachment so you can generate your own client.

Setting up the environment

Before you can send authorization requests to the server, be sure the following items are configured.

Your runtime security services server is installed and registered. The runtime security services client does not provide the web service, so be sure that you've installed the server.
You've distributed policy to your server.

You'll also need to know the context ID (or Application ID) of your service in Tivoli Security Policy Manager and the names and values of any attributes that you plan to send in the XACML request (that information is collected during policy configuration).

Finally, you'll need to generate a web service client using the attached WSDL and schemas. Consult the documentation for your web service runtime for information on how to perform that task.

Operations:

The authorization web service provides the following operations:

evaluateXACML:
This operation receives an evaluateXACMLRequest message which is the standard XACML authorization request and produces a standardized authorization decision in the form of a valuateXACMLResponse.

evaluateEntitlements:
This operation receives a proprietary EntitlementRequest message containing the required information to produce a list of entitlements for the designated subject.

Authorization requests

Once you've generated your client, you're ready to send an authorization request to the runtime security services server. Use the following URL, customized to your environment.

http://<rtss host>:<web container port>/rtss/authz/services/AuthzService

The protocol for a simple Permit or Deny authorization decision is an XACML request over SOAP. The attributes contained within this request should follow a few guidelines:

Four elements are required for authorization: a set of subjects, a set of resources, an action performed against the resources and
the environment, or application context, which scopes the context for evaluation.

Attributes are included in each section in the following XML format:

<xacml-context:Attribute AttributeId="\<AttributeId\>" DataType="\<DataType\>" >
    <xacml-context:AttributeValue>value</xacml-context:AttributeValue>
</xacml-context:Attribute>

The tables below will reference the "AttributeId" and "DataType" fields.

Subject:

An XACML subject consists of a set of attributes that describe the principals involved in the authorization request. For example, one subject can be the user requesting access to the resource while another subject represents the Policy Enforcement Point (PEP) or code sending the request to the Policy Decision Point (PDP). The subject-category defines the type of subject. In an XACML request, at least one "access-subject" must be defined.

The user's subject-id and a set of group-ids are usually specified here as distinguished names.

AttributeId	DataType	Value
urn:oasis:names:tc:xacml:1.0:subject:subject-id	http://www.w3.org/2001/XMLSchema#string	The user's login name as a string
urn:oasis:names:tc:xacml:1.0:subject:subject-id	urn:oasis:names:tc:xacml:1.0:data-type:x500Name	The user's login name as an X500Name
urn:oasis:names:tc:xacml:1.0:subject:group-id	http://www.w3.org/2001/XMLSchema#string	The groups the user is a member of as a string
urn:oasis:names:tc:xacml:1.0:subject:group-id	urn:oasis:names:tc:xacml:1.0:data-type:x500Name	The groups the user is a member of as an X500Name

To add custom attributes for the user, add more elements in the Subject block. Use a custom AttributeId that describes the attribute (it must be a URI) and an appropriate data type.

Resource:

The XACML resource elements describe the resource that the subject is requesting access to. Examples of resources are web services operations, a URL, or custom service IDs (if using custom applications). The contents of this element will depend on the type of service the policy is authored for, such as "Application" or "Web Service"

For "Application":

AttributeId	DataType	Value
urn:oasis:names:tc:xacml:1.0:resource:resource-id	http://www.w3.org/2001/XMLSchema#string	The element name of the resource being accessed

For "Web Services":

AttributeId	DataType	Value
urn:oasis:names:tc:xacml:1.0:resource:resource-id	http://www.w3.org/2001/XMLSchema#anyURI	The HTTP URL of the web service being accessed
urn:ibm:xacml:profiles:web-services:1.0:wsdl:1.1:service	http://www.w3.org/2001/XMLSchema#string	The service name in the WSDL of the service being accessed, in the format {namespace}Service.
urn:ibm:xacml:profiles:web-services:1.0:wsdl:1.1:port	http://www.w3.org/2001/XMLSchema#string	The port name in the WSDL of the service being accessed, in the format {namespace}Port.
urn:ibm:xacml:profiles:web-services:1.0:wsdl:1.1:operation	http://www.w3.org/2001/XMLSchema#string	The operation name in the WSDL of the service being accessed, in the format {namespace}Operation.

Action:

The action element describes the action the subject is trying to perform on the resource. The XACML standard dictates that an action element needs to provide one urn:oasis:names:tc:xacml:1.0:action:action-id attribute.

AttributeId	DataType	Value
urn:oasis:names:tc:xacml:1.0:action:action-id	http://www.w3.org/2001/XMLSchema#string	The action being performed on the resource

Environment:

The environment element is required to have an attribute contextId that specifies the application ID.

<xacml-context:Environment>
    <xacml-context:Attribute AttributeId="ContextId" DataType="http://www.w3.org/2001/XMLSchema#string" Issuer="http://security.tivoli.ibm.com/policy/distribution">
        <xacml-context:AttributeValue>test-app</xacml-context:AttributeValue>
    </xacml-context:Attribute>
</xacml-context:Environment>

If the full DN is being provided for the subject-id and group-id attributes, then they MUST be included as both DataType "http://www.w3.org/2001/XMLSchema#string" and "urn:oasis:names:tc:xacml:1.0:data-type:x500Name".
For the Application service type in TSPM, the resource-id and action-id should be of type "http://www.w3.org/2001/XMLSchema#string".

This an example showing what a SOAP message containing an XACML request looks like:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header/>
   <soapenv:Body>
      <xacml-context:Request xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
         <xacml-context:Subject SubjectCategory="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject">
            <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="http://www.w3.org/2001/XMLSchema#string">
            <xacml-context:AttributeValue>cn=craig,o=ibm,c=us</xacml-context:AttributeValue>
          </xacml-context:Attribute>
          <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="urn:oasis:names:tc:xacml:1.0:data-type:x500Name">
            <xacml-context:AttributeValue>CN=craig, O=ibm, C=us</xacml-context:AttributeValue>
          </xacml-context:Attribute>
          <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:group-id" DataType="http://www.w3.org/2001/XMLSchema#string">
            <xacml-context:AttributeValue>cn=test-group,o=ibm,c=us</xacml-context:AttributeValue>
          </xacml-context:Attribute>
          <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:group-id" DataType="urn:oasis:names:tc:xacml:1.0:data-type:x500Name">
            <xacml-context:AttributeValue>CN=test-group, O=ibm, C=us</xacml-context:AttributeValue>
          </xacml-context:Attribute>
         </xacml-context:Subject>
         <xacml-context:Resource>
            <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" DataType="http://www.w3.org/2001/XMLSchema#string">
               <xacml-context:AttributeValue>foo-1</xacml-context:AttributeValue>
            </xacml-context:Attribute>
         </xacml-context:Resource>
         <xacml-context:Action>
            <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#string">
               <xacml-context:AttributeValue>read</xacml-context:AttributeValue>
            </xacml-context:Attribute>
         </xacml-context:Action>
         <xacml-context:Environment>
            <xacml-context:Attribute AttributeId="ContextId" DataType="http://www.w3.org/2001/XMLSchema#string" Issuer="http://security.tivoli.ibm.com/policy/distribution">
               <xacml-context:AttributeValue>test-app</xacml-context:AttributeValue>
            </xacml-context:Attribute>
         </xacml-context:Environment>
      </xacml-context:Request>
   </soapenv:Body>
</soapenv:Envelope>

The response to this request will be an XACML response element:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header/>
  <soapenv:Body>
    <xacml-context:Response xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
      <xacml-context:Result>
        <xacml-context:Decision>Permit</xacml-context:Decision>
        <xacml-context:Status>
          <xacml-context:StatusCode Value="urn:oasis:names:tc:xacml:1.0:status:ok"/>
        </xacml-context:Status>
      </xacml-context:Result>
    </xacml-context:Response>
  </soapenv:Body>
</soapenv:Envelope>

Entitlement requests

Entitlement requests are also sent over SOAP to the URL above, however the content is an IBM extension to the XACML specification. The general model is that you provide what you know already, and request specific attributes back as entitlements. For example, if we were needed to know what resources a user had access to and what actions they could perform, the request might look as follows:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header/>
  <soapenv:Body>
    <entitlements:EntitlementRequest xmlns:entitlements="http://security.tivoli.ibm.com/schemas/entitlements">
      <!-- In the Request you specify what you already know - the user's identity, group information, etc -->
      <xacml-context:Request xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
        <xacml-context:Subject SubjectCategory="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject">
          <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="http://www.w3.org/2001/XMLSchema#string">
            <xacml-context:AttributeValue>cn=craig,o=ibm,c=us</xacml-context:AttributeValue>
          </xacml-context:Attribute>
          <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="urn:oasis:names:tc:xacml:1.0:data-type:x500Name">
            <xacml-context:AttributeValue>CN=craig, O=ibm, C=us</xacml-context:AttributeValue>
          </xacml-context:Attribute>
          <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:group-id" DataType="http://www.w3.org/2001/XMLSchema#string">
            <xacml-context:AttributeValue>cn=test-group,o=ibm,c=us</xacml-context:AttributeValue>
          </xacml-context:Attribute>
          <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:group-id" DataType="urn:oasis:names:tc:xacml:1.0:data-type:x500Name">
            <xacml-context:AttributeValue>CN=test-group, O=ibm, C=us</xacml-context:AttributeValue>
          </xacml-context:Attribute>
        </xacml-context:Subject>
        <xacml-context:Action/>
        <!-- Remember to specify the TSPM context identifier! -->
        <xacml-context:Environment>
          <xacml-context:Attribute AttributeId="ContextId" DataType="http://www.w3.org/2001/XMLSchema#string" Issuer="http://security.tivoli.ibm.com/policy/distribution">
            <xacml-context:AttributeValue>test-context</xacml-context:AttributeValue>
          </xacml-context:Attribute>
        </xacml-context:Environment>
      </xacml-context:Request>
      <!-- In the AttributeDesignators you specify what you want to get back. In this case we're asking for the resource-id and action-id combination -->
      <entitlements:AttributeDesignators>
        <ResourceAttributeDesignator xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" DataType="http://www.w3.org/2001/XMLSchema#string"/>
        <ActionAttributeDesignator xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#string"/>
      </entitlements:AttributeDesignators>
      <!-- In the Decision you put Permit or Deny.  If Permit, then the return values are the attributes that when combined with the request are permitted; vice versa for Deny. -->
      <xacml-context:Decision xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">Permit</xacml-context:Decision>
    </entitlements:EntitlementRequest>
  </soapenv:Body>
</soapenv:Envelope>

This entitlements request contains three distinct sections:

A partial XACML request, containing the attributes and data that is already known. In this case, it's the subject and their groups.
A set of AttributeDesignators specifying which attributes the response should contain. In this case, we're requesting the resource-id and action-id
The desired Decision, which is almost every use case will by Permit.

The response looks as follows:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <entitlements:EntitlementResponse xmlns:entitlements="http://security.tivoli.ibm.com/schemas/entitlements">
      <xacml-context:Status xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
        <xacml-context:StatusCode Value="urn:oasis:names:tc:xacml:1.0:status:ok"/>
      </xacml-context:Status>
      <!-- The response contains 0 or more of these Entitlement element.  Each Entitlement represents a particular combination of attributes that, when combined with the attributes in the original Request, return the desired result -->
      <entitlements:Entitlement>
        <xacml-context:Subject xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os"/>
        <xacml-context:Resource xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
          <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" DataType="http://www.w3.org/2001/XMLSchema#string">
            <xacml-context:AttributeValue>foo-1</xacml-context:AttributeValue>
          </xacml-context:Attribute>
        </xacml-context:Resource>
        <xacml-context:Action xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
          <xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#string">
            <xacml-context:AttributeValue>read</xacml-context:AttributeValue>
          </xacml-context:Attribute>
        </xacml-context:Action>
        <xacml-context:Environment xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os"/>
      </entitlements:Entitlement>
    </entitlements:EntitlementResponse>
  </soapenv:Body>
</soapenv:Envelope>

This response will contain zero or more "Entitlement" elements, with each element containing a combination of the requested attributes that the user can access. You can see in this response that a combination of resource-id "foo-1" and action "read" was returned. The basic logic if this response is that combining the contents of a particular Entitlement response with the initial Request will result in the desired Decision.