|
|
To develop Web Services clients, you use the Web Services Security Service Module (SSM) application programming interfaces (APIs) developed by BEA Systems.
These interfaces are described in the following sections:
To map security service type and SSM configuration and SOAP endpoints, each Web Services SSM process has its own separate Registry Service. The address of the Registry Service should be known to the web services client from its configuration. This service maps the SSM Configuration ID and the service type to the Web Services SSM and SOAP endpoints for the security services. The Configuration ID is defined in the default.properties file for the SSM instance. The Registry Service makes it possible to distinguish between the supported service types (auditing, authentication, authorization, credential mapping, and role mapping). Registry Service operations on a particular machine are limited to the local machine (see Figure 5-1). The Web Services client learns about the Registry Service from its configuration file.
The following topics provide or more information on the Registry Service.
The Registry Service works as follows (Figure 5-2):
default.properties file.| Note: | The Registry Service does not provide lifecycle management functions for the Web Services. |
For more information on the Registry Service interface and the methods it supports, see WSDLdocs for Web Services Interfaces.
The Registry Service supports two methods: locateService() and doesServiceExist(). Both methods accept the requested service type of the Web Server SSM or Web Services SSM that provides the service. The supported service types are: ALES_AUDIT, ALES_AUTHENTICATION, ALES_AUTHORIZATION, ALES_CREDENTIAL, and ALES_ROLE. The type for all service types is string.
For the locateService() method, the Registry Service returns the fully qualified URL for the endpoint of the requested service. For the doesServiceExist() method, the service returns a Boolean value (true or false) that indicates whether the service exists and can be requested.
The following methods are supported by all Web Services interfaces, except for the Registry Service interface.
getServiceType()—This method takes an empty request and returns a structure that contains the service. The Web Services SSM supports these security service types: ALES_AUDIT, ALES_AUTHENTICATION, ALES_AUTHORIZATION, ALES_CREDENTIAL, and ALES_ROLE. The type for all service types is string.getServiceVersion()—This method takes an empty request and returns a structure that contains the version of the service. The Web Service SSM supports these version types: MajorVersion (type int), MinorVersion (type int), PatchLevel (type string), and Version (type long).isCompatible()—This method accepts service version information and returns compatibility information. The method accept these values: MajorVersion (type int), MinorVersion (type int), PatchLevel (type string), and Version (type long). It returns these compatibility responses: ALES_NOT_COMPATIBLE, ALES_COMPATIBLE, ALES_COMPATIBLE_DEPRECATED, ALES_COMPATIBLE_UNKNOWN. All compatibility responses are returned as strings. You use this method to determine whether the version of the service interface specified in the web services client is compatible with the current version of the service interface in the instance of the Web Services SSM.
The Authentication Service provides security functions to an application so as to establish, verify, and transfer a person or process identity. Thus, the Authentication Service provides two main security functions: authentication and identity assertion.
The Authentication Service accepts user credentials and/or identity assertion tokens and verifies that they match the user identity stored in the existing user profile. The following types of identity assertion tokens are supported:
The Extensible Markup Language (XML) structures used by the Authentication Service for transmitting identity assertion tokens and other credential types are defined the WSDL interface.
To ensure secure handling of credentials, all credentials presented to the Web Services Security Service Module must satisfy the following requirements:
The Web Services SSM only accepts clear-text passwords. However, the credentials presented are always be protected by SSL, either one-way or two-way. The Web Services SSM returns credentials to clients over SSL as well.
The SOAP authentication interface enables the Web Services SSM to return challenges to clients if they fail to provides the information necessary to complete the authentication process. In such cases, the client can respond with the requested information. In order to avoid expensive round trips, however, the web services client should pass in all available credentials information with the initial SOAP request.
The following topics provide more information on the Authentication Service interface:
The authentication process is as follows (see Figure 5-3):
AuthenticationFailure SOAP Fault to the caller.For more information on the Authentication Service Interface and the methods it supports, see WSDLdocs for Web Services Interfaces.
To support authentication functions the authentication provides the following methods:
This method accepts any credential type supported by the authentication provider or a response to an earlier authentication challenge, and, optionally, the type of requested identity assertion that represents the identity and application context of the authenticated user. In response, it returns either the requested identity assertion token and status information or an authentication challenge.
| Note: | In addition to the identity assertion types, the Web Services SSM supports user credentials in form of usernames with passwords. |
Table 5-1 describes the authenticate() method parameters.
This method accepts any supported identity assertion type or a response to an earlier authentication challenge, and, optionally, the type of requested identity assertion that represents the identity and application context of the authenticated user. In response, it returns either the requested identity assertion token and status information or an authentication challenge.
Table 5-2 describes the assertIdentity() method parameters.
This method accepts an identity assertion credential type that represents the authenticated user’s identity. It returns a Boolean value (true or false) to indicate whether this token type is supported by this instance of the Web Services SSM.
Table 5-3 describes the isAssertionTokenSupported() method parameters.
This method accepts any supported identity assertion type that represents the identity of the authenticated user. It returns a structure with a Boolean value (true or false) that indicates whether the token is valid.
Table 5-4 describes the validateIdentity() method parameter.
The Authorization Service is a service that allows an application to determine if a specific identity is permitted to access a specific resource. This decision may then be enforced in the application directly at the policy enforcement point.
The Authorization Service is primarily based on a single method: isAccessAllowed(). This method accepts a supported type of user credential or an identity token, a runtime resource, and a runtime action. Optionally, this method can accept the type of the requested identity assertion token that represents the identity of the authenticated user, the application context, and direction parameters. The isAccessAllowed() method requires that a valid, authenticated identity or a null identity token (representing an anonymous identity) be present when requesting an access decision. The following topics provide more information on the Authorization Service.
The authorization process is as follows (see Figure 5-4):
AuthorizationFailure SOAP Fault is returned to the caller.For more information about the Authorization Service interface, see the WSDLdocs for Web Services Interfaces.
The Authorization Service supports the following methods:
This method accepts a supported type of an identity assertion token and runtime resource and action structures. Optionally, it can accept the requested identity assertion credential type, application context, and authorization direction parameters. In response, this method returns the authorization decision and authorization data, or, if required by the authorization provider, additional context requests.
Table 5-5 describes the isAccessAllowed() method parameters.
The Authorization Service interface also supports the isAuthenticationRequired() method. This method accepts a runtime resource and a runtime action. It returns a Boolean value (true or false) that indicates whether authentication is require to access this resource. The web services client uses this method to test whether privileges are required to access a particular resource.
Table 5-6 describes the isAuthenticationRequired() method parameters.
This version of AquaLogic Enterprise Security allows external applications to ask authorization questions using the XACML protocol. This capability is supported only in the Web Services SSM.
The XACML service is implemented as an extension to the existing Authorization Service in the Web Service SSM, and uses the same configuration and administration scripts of the Web Service SSM. The XACML service is silently installed together with the Web Service SSM. The XACML service is not viewable or configurable through the Administration Console.
| Note: | The XACML service supports XACML 2.0 only. It does not support a XACML 1.0 context. In addition, the SAML 2.0 profile for XACML 2.0 is not supported in this release. |
As described in Client Trust Model, the Web Services SSM supports both one-way and two-way SSL (see Figure 2-5). However, the connection between the PEP and the XACML service should be over two-way SSL.
This section describes a typical use case for the XACML service.
The following new terms are used in this section: PEP and PDP. The policy enforcement point (PEP) is the system entity that performs access control by making decision requests and enforcing authorization decisions. The policy decision point (PDP) is the system entity that evaluates applicable policy and renders an authorization decision. The XACML service implements a PDP: it provides a XACML-based Authorization service (inside the Web Service SSM) to your client PEP.
The basic use case for the XACML service is similar to the following:
This version of AquaLogic Enterprise Security includes a simple XACML client (PEP) application that does authorization to the Web Service SSM using the XACML protocol. The example demonstrates the following concepts:
The example is located in BEA_HOME\ales30-ssm\webservice-ssm\examples\XACMLClient.
XACML is an OASIS standard language that specifies schemas for authorization policies and for authorization decision requests and responses. It also specifies how to evaluate policies against requests to compute a response. In this release, AquaLogic Enterprise Server implements the authorization process using XACML context. The XACML context is used to convey an authorization decision request and response.
The XACML standard ( http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-core-spec-os.pdf) specifies how the XACML context should be used for authorization, and the behaviors of PEPs and PDPs.
The XACML context is the protocol used by the PEP to ask the PDP for an authorization decision. It defines a <xacml-context:Request> element to convey the request and a <xacml-context:Response> for the response. The request contains four elements for authorization, including:
The PEP sends the authorization request to the PDP using a XACML context, which contains the subject, action, resource, and environment. The PEP is asking the PDP the following question: “Given such a subject, is it allowed to perform the specified action on the specified resource in the specified environment?”.
The XACML service takes the XACML request, converts the request to a format understood by the AquaLogic Enterprise Server, and calls the Java API (specifically, the Authorization Service’s isAccessAllowed method) to authorize the user.
When a decision has been made, the XACML service wraps the AquaLogic Enterprise Server returned values into the XACML response. The XACML service returns a SOAP fault if the PEP sends a malformed request that does not follow the XACML context schema. Otherwise, the XACML service will always return a decision of “Permit”, “Deny”, “Indeterminate” or “NotApplicable”.
The PEP then interprets the result and enforces the decision. For the “Permit” decision, the PEP allows the request, and for the “Deny” decision, the PEP denies the request. For results of “Indeterminate” or “NotApplicable,” it is up to the PEP to interpret them. For “Permit-biased” PEP, the access will be allowed; for “Deny-biased” PEP, access will be denied.
The policy enforcement point (PEP) that sends the authorization request to the XACML service is responsible for authenticating the user and supplying a valid AquaLogic Enterprise Server token as the subject.
The following types of identity assertion tokens are supported:
The Extensible Markup Language (XML) structures used by the Authentication Service for transmitting identity assertion tokens and other credential types are defined the WSDL interface.
The XACML service accepts the token supplied by the PEP and tries to assert that token (assertion) in AquaLogic Enterprise Server.
As described in Overview of XACML Context, the request contains an <xacml-context:Request> and the response contains an <xacml-context:Response> element. These two elements are directly enclosed in the SOAP body.
One, and only one, request or response should be in the SOAP body.
There are currently two defined XACML namespaces. Policies are defined using the identifier urn:oasis:names:tc:xacml:2.0:policy:schema:os, and request and response contexts are defined using the identifier urn:oasis:names:tc:xacml:2.0:context:schema:os.
This implementation uses the following identifier to represent the XACML service:http://security.bea.com/ssmws/ssm-ws-1.0.wsdl.
Listing 5-1 shows a sample SOAP request.
POST /XACMLAuthorization HTTP/1.0
Host: pdp-01
Connection: Keep-Alive
Content-Type: application/soap+xml; charset=utf-8
SOAPAction: ssmws:xacml:authorization
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<xacml-context:Request xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
<xacml-context:Subject>…</xacml-context:Subject>
<xacml-context:Resource>…</xacml-context:Resource>
<xacml-context:Action>…</xacml-context:Action>
<xacml-context:Environment>…</xacml-context:Environment>
</xacml-context:Request>
</soap:Body>
</soap:Envelope>
If a malformed SOAP request is sent to the server (for example, a non-XML request or an XML request that does not follow the schema definition), a SOAP fault is returned to the client (PEP).
The request element defined by the XACML standard ( http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-core-spec-os.pdf) is as follows:
<xs:element name="Request" type="xacml-context:RequestType"/>
<xs:complexType name="RequestType">
<xs:sequence>
<xs:element ref="xacml-context:Subject" maxOccurs="unbounded"/>
<xs:element ref="xacml-context:Resource" maxOccurs="unbounded"/>
<xs:element ref="xacml-context:Action"/>
<xs:element ref="xacml-context:Environment"/>
</xs:sequence>
</xs:complexType>
As detailed in the standard, the <Request> element contains <Subject>, <Resource>, <Action> and <Environment> elements. There may be multiple <Subject> elements and, under some conditions, multiple <Resource> elements. Each child element contains a sequence of <xacml-context:Attribute> elements associated with the subject, resource, action, and environment, respectively.
The sections that follow describe how the <Subject>, <Resource>, <Action> and <Environment> elements are interpreted.
XACML subject, resource, action, and environment elements usually contain XACML context attributes, <xacml-context:Attribute>.
The context attributes contain metadata (such as AttributeId, DataType), and one or more <AttributeValue> element. As described in the XACML standard (
http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-core-spec-os.pdf), the schema of Attribute is as follows:
<xs:element name="Attribute" type="xacml-context:AttributeType"/>
<xs:complexType name="AttributeType">
<xs:sequence>
<xs:element ref="xacml-context:AttributeValue" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="AttributeId" type="xs:anyURI" use="required"/>
<xs:attribute name="DataType" type="xs:anyURI" use="required"/>
<xs:attribute name="Issuer" type="xs:string" use="optional"/>
</xs:complexType>
Different attributes in different elements will have different AttributeId and DataType.
The <AttributeValue>, by definition, can carry anything. It contains any element under any namespace, as well as any attributes. Any valid XML data can be put in. However, it must be meaningful for its parent <Attribute>’s AttributeId and DataType.
There can be multiple <AttributeValue> elements in an <Attribute>; however, the XACML service allows only one of them. If there is more than one, an indeterminate result is returned and a processing-error status is reported.
An <Attribute> without an <AttributeValue> results in a SOAP fault because it does not follow the schema.
If there is an Issuer attribute in <Attribute>, it is currently ignored by the XACML service.
The DataType of the <Attribute> is usually ignored, because the content of the <AttributeValue> is regarded only as a string type.
The <Subject> consists of a sequence of <xacml-context:Attribute> elements associated with the subject.
<xs:element name="Subject" type="xacml-context:SubjectType"/>
<xs:complexType name="SubjectType">
<xs:sequence>
<xs:element ref="xacml-context:Attribute" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="SubjectCategory" type="xs:anyURI"
default="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject"/>
</xs:complexType>
The <Subject> element has an optional attribute, SubjectCategory. This represents the subject’s role of this request. For example, ‘access-subject’, ‘requesting-machine’, ‘code-base’.
Inside a <Subject>, there could be an <Attribute> with AttributeId of “urn:oasis:names:tc:xacml:1.0:subject-category”, and the <AttributeValue> of this <Attribute> also represents the subject category. This is equal to the “SubjectCategory” attribute of the <Subject>.
For example, the following two <Subject> elements are functionally equal:
<Subject>
<Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject-category" DataType="xs:anyURI">
<AttributeValue>urn:oasis:names:tc:xacml:1.0:subject-category:access-subject</AttributeValue>
</Attribute>
</Subject>
<Subject SubjectCategory=”urn:oasis:names:tc:xacml:1.0:subject-category:access-subject”>
</Subject>
There can be multiple subjects in a <Request> element.
The XACML context specifies that these subjects should be "disjunctive," which is defined in the standard as a sequence of predicates combined using the logical ‘OR’ operation.
For example, one subject may represents the human user who initiates the request, another may represent the code that is doing the request. They are specified by subject categories.
The rules of handling multiple subjects are as follows:
<Subject> element. <Subject> having the “access-subject” category, which represents the direct accessing subject. For the <Attribute> elements of this category, there should be no more than one <Attribute> element with the following AttributeId, which represents the requester’s identity: urn:oasis:names:tc:xacml:1.0:subject:subject-id.<Attribute> is described in The subject id <Attribute>.<Subject> elements or other <Attribute> elements that are not a subject-id, they are converted as an AquaLogic Enterprise Security authorization context (AppContext).
The DataType attribute of the subject-id <Attribute> element indicates the subject type. The type is of “anyURI” type, but in order to be understood, the DataType should be prefixed with the
identifier that represents the XACML service: http://security.bea.com/ssmws/ssm-ws-1.0.wsdl.
In addition, a fragment should be suffixed after this URL indicating the subject type that could be asserted in AquaLogic Enterprise Security; that is, the first parameter of the assertIdentity() method in the Authentication service API.
For example, if the subject contains ALESIdentityAssertion, it should have the DataType http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#ALESIdentityAssertion, and the <AttributeValue> of this <Attribute> is taken as the subject.
However, if a valid <AttributeValue> is provided and correctly recognized by the Web Service SSM, the DataType may not be checked.
If the <Subject> (which is of ‘access-subject’ category) does not contain an <Attribute> with “subject-id”, this subject will be considered as an anonymous user. The service will construct an anonymous identity and pass it to the authorization service.
Also note that this implementation reuses the Web Service SSM’s identity cache for better performance, as described in Optimizing Web Services Performance with Caches.
For other <Subject> elements and <Attribute> elements that are not in the ‘access-subject’ category, or are in the ‘access-subject’ category but without a “subject-id” id, those <Attribute> elements are converted as authorization context (AppContext) of AquaLogic Enterprise Security.
If there are multiple <Attribute> elements with the same id, a later one will override the previous one.
Also, only text values in <AttributeValue> are acceptable; child XML elements are ignored.
The rule for converting an attribute to an AquaLogic Enterprise Security context key-value pair is as follows:
urn:oasis:names:tc:xacml:1.0: subject:authn-locality:authentication-method”), the last field of the URN, that is, the string after the last colon, is taken as the context key, and the AttributeValue is the context value. For example, if the previous URN has an AttributeValue of “username/password”, the resulting ALES context will be “authentication-method” : “username/password”.Note that this is a XACML extension: the XACML standard does not have this type of URL as AttributeId, but the PEP could use this method to pass some context to AquaLogic Enterprise Server system.
At least one of the resource attributes should have the following AttributeId: urn:oasis:names:tc:xacml:2.0:resource:resource-id.
The AttributeValue of this resource attribute should be the resource that can be understood by AquaLogic Enterprise Security; that is, the resource under the binding point of the SSM. The example queries the user for the resource name, and suggests a value of "store/book."
The DataType of this attribute should always be the XML schema standard “string” type: http://www.w3.org/2001/XMLSchema#string.
Other attributes in <Resource>, except for the one associated with the naming authority, are converted as authorization context attributes for authorization evaluation in AquaLogic Enterprise Security, using the same rule as <Subject> attributes.
At least one of the attributes in the <Action> element must have the following AttributeId: urn:oasis:names:tc:xacml:1.0:action:action-id.
The attribute value of this attribute is the action performed on the resource. For example: GET, POST. The example queries the user for the action name.
The DataType of this attribute should be the XML schema standard string http://www.w3.org/2001/XMLSchema#string.
Other attributes in <Action> are converted as context attributes for authorization evaluation in AquaLogic Enterprise Security, using the same rule as <Subject> attributes.
The XACML service converts environment attributes to AquaLogic Enterprise Security application context. The rule to convert environment elements to AquaLogic Enterprise Security contexts is the same as for the subject. All attributes in <Environment> elements are converted.
For example, a sample environment element is as follows:
<Environment>
<Attribute AttributeId="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#DOB"
DataType="http://www.w3.org/2001/XMLSchema#dateTime">
<AttributeValue>1979-03-29</AttributeValue>
</Attribute>
</Environment>
The fragment (the string after the ‘#’ character) of the URL is taken as the context key and the AttributeValue is the context value, which results in an AquaLogic Enterprise Security context of DOB:1979-03-29.
Listing 5-2 shows a full sample of a XACML request, without the SOAP envelope.
<Request xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os">
<Subject>
<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="
http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#ALESIdentityAssertion">
<AttributeValue>
<ALESIdentityAssertion xmlns=”…”>……</ALESIdentityAssertion>
</AttributeValue>
</Attribute>
</Subject>
<Resource>
<Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:resource:resource-id"
DataType="http://www.w3.org/2001/XMLSchema#string">
<AttributeValue>/cgi-bin/j_security_check</AttributeValue>
</Attribute>
</Resource>
<Action>
<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
DataType="http://www.w3.org/2001/XMLSchema#string">
<AttributeValue>POST</AttributeValue>
</Attribute>
</Action>
<Environment/>
</Request>
The <Response> element is the root element of a response. It contains one or more <Result> elements, which contain authorization decision results. The XACML service supports only one <Result> element.
The <Result> element is defined as follows:
<xs:element name="Result" type="xacml-context:ResultType"/>
<xs:complexType name="ResultType">
<xs:sequence>
<xs:element ref="xacml-context:Decision"/>
<xs:element ref="xacml-context:Status" minOccurs="0"/>
<xs:element ref="xacml:Obligations" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="ResourceId" type="xs:string" use="optional"/>
</xs:complexType>
The <Result> element has a ResourceId attribute that indicates the identifier of the request resource element. This implementation does not use this value.
Decision is the evaluation result. It contains a string value of “Permit”, “Deny”, “Indeterminate”, or “NotApplicable”. “Permit” or “Deny” are typically returned. For example: <Decision>Permit</Decision>.
If some required attribute is required, “Indeterminate” is returned, with the “missing-attribute” status.
The <Status> element is an optional element of <Result>. It contains the following elements:
<StatusCode> has an attribute named “Value,” which can be one of the following values:
If any exception occurred during the authorization process, processing-error is returned.
If some attribute is required for evaluating the policy, missing-attribute is returned.
<StatusMessage> is simply a string to show the message accompanying the status. If an exception occurs, the exception will be in the <StatusMessage> for information purpose.
<StatusDetail> is an extension point and it can contain anything. This implementation puts a <MissingAttributeDetail> value in it if the status is “missing-attribute”. In that case, the AttributeId is the missing attribute key, prefixed with the XACML service namespace (http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#) and there is no <AttributeValue> in the <MissingAttributeDetail> element.
A XACML obligation is an operation specified in a policy or policy set that should be performed by the PEP in conjunction with the enforcement of an authorization decision.
This implementation places the AquaLogic Enterprise Server evaluation returned values, like roles or the report_as values, in an obligation. Obligations are used only when the authorization result is “Permit.”
<xs:element name="Obligations" type="xacml:ObligationsType"/>
<xs:complexType name="ObligationsType">
<xs:sequence>
<xs:element ref="xacml:Obligation" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:element name="Obligation" type="xacml:ObligationType"/>
<xs:complexType name="ObligationType">
<xs:sequence>
<xs:element ref="xacml:AttributeAssignment" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="ObligationId" type="xs:anyURI" use="required"/>
<xs:attribute name="FulfillOn" type="xacml:EffectType" use="required"/>
</xs:complexType>
<xs:element name="AttributeAssignment" type="xacml:AttributeAssignmentType"/>
<xs:complexType name="AttributeAssignmentType" mixed="true">
<xs:complexContent mixed="true">
<xs:extension base="xacml:AttributeValueType">
<xs:attribute name="AttributeId" type="xs:anyURI" use="required"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
Obligations consist of one or more <Obligation> elements. An <Obligation> has the following attributes:
The <Obligation> element has zero or more <AttributeAssignment> elements. <AttributeAssignment> has an AttributeId and text content. The AttributeId is the returned attribute key, prefixed with the namespace http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#, and the content is the attribute value.
For example, the response attribute “currency” : ”USD” is returned as:
<AttributeAssignment AttributeId="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#currency"
DataType="http://www.w3.org/2001/XMLSchema#string">USD
</AttributeAssignment>
<AttributeAssignment AttributeId="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#role"
DataType="http://www.w3.org/2001/XMLSchema#string">Admin
</AttributeAssignment>
Listing 5-3 shows a complete sample response, without the SOAP envelope.
<?xml version="1.0" encoding="UTF-8"?>
<Response xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os">
<Result>
<Decision>Deny</Decision>
<Status>
<StatusCode Value="urn:oasis:names:tc:1.0:status:processing-error"/>
<StatusMessage>Authentication required</StatusMessage>
</Status>
<Obligations>
<Obligation FulfillOn="Permit" ObligationId="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#Roles">
<AttributeAssignment DataType="http://www.w3.org/2001/XMLSchema#string"
AttributeId="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#role">
Admin
</AttributeAssignment>
</Obligation>
</Obligations>
</Result>
</Response>
Listing 5-4 shows the WSDL definition of the XACML Service.
<?xml version="1.0" encoding="UTF-8"?>
<definitions
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os"
xmlns:ssm="http://security.bea.com/ssmws/ssm-soap-types-1.0.xsd"
xmlns:tns="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl"
targetNamespace="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl">
<types>
<!-- note this policy schema is not a full one. it is stripped for the XACML runtime only -->
<xs:import namespace="urn:oasis:names:tc:xacml:2.0:policy:schema:os" schemaLocation="access_control-xacml-2.0-policy-schema-os.xsd"/>
<xs:import namespace="urn:oasis:names:tc:xacml:2.0:context:schema:os" schemaLocation="access_control-xacml-2.0-context-schema-os.xsd"/>
<!-- for fault types -->
<xs:import namespace="http://security.bea.com/ssmws/ssm-soap-types-1.0.xsd" schemaLocation="ssm-soap-types.xsd"/>
</types>
<message name="XACMLAtzDecisionRequest">
<part name="param" element="xacml-context:Request"/>
</message>
<message name="XACMLAtzDecisionResponse">
<part name="param" element="xacml-context:Response"/>
</message>
<message name="XACMLFault">
<part name="fault" element="ssm:xacmlFailure"/>
</message>
<message name="serviceFault">
<part name="fault" element="ssm:serviceFailure"/>
</message>
<portType name="XACMLPort">
<operation name="authorize">
<input message="tns:XACMLAtzDecisionRequest"/>
<output message="tns:XACMLAtzDecisionResponse"/>
<fault name="serviceFault" message="tns:serviceFault" />
<fault name="xacmlFault" message="tns:XACMLFault"/>
</operation>
</portType>
<binding name="XACMLBinding" type="tns:XACMLPort">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<!-- Axis has problem support this wrapped style, use document instead. -->
<operation name="authorize">
<soap:operation soapAction="ssmws:xacml:authorization" style="document"/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
<fault name="serviceFault">
<soap:fault use="literal"/>
</fault>
<fault name="xacmlFault">
<soap:fault use="literal"/>
</fault>
</operation>
</binding>
<service name="XACMLService">
<port name="XACMLAuthorization" binding="tns:XACMLBinding">
<soap:address location="http://localhost/XACMLAuthorization"/>
</port>
</service>
</definitions>
The Auditing Service logs events based on activity related to enterprise security. The Web Services Security Service Module (SSM) runtime uses the Auditing Service to log appropriate data when events occur. The Auditing Service is based on an event model. When something of note occurs, an auditing event is automatically logged. A user or a application that wants notification when a particular event occurs can derive a new class from the AuditRecord class.
The following topics provide more information on the Auditing Service.
The auditing process is as follows (see Fig):
recordEvent() method to specify the name of the audit record to be captured, and, optionally, the identity assertion token of the auditing user, and the application context.recordEvent() method, the Auditing Service returns requests for additional application context.AuditingFailure SOAP Fault is returned to the caller.For more information on the Auditing Service interface and the methods it supports, see WSDLdocs for Web Services Interfaces.
The Auditing Service passes the audit event to the Web Services SSM runtime. Based on its configuration, the SSM runtime routes the event to the proper auditing providers so that it can be recorded.
The Auditing Service supports a single method, recordEvent(). This method accepts an audit record, and, optionally, an identity assertion token, representing the auditing user, and an application context.
Table 5-7 describes the recordEvent() method parameters.
The Role Mapping Service allows an application to extract role information about specific identities and resources within the context of the application. These roles can then be used for customizing an interface or for other purposes.
| Note: | Do not use roles by themselves for authorization, because many policies, allowing or disallowing access to a resource, may be written against a role. Use the Authorization Service to determine actual access rights. |
The Role Mapping Service evaluates an interaction of an identity with a resource within an application context and returns a list of role names associated with the configuration of that identity. These roles can change with every resource or be static for the identity across all resources. The roles assigned to an identity are determined by the security policy.
The Web Services SSM is capable of retrieving the roles that a user may have for the given resource and action combination. The user identity is passed as an identity assertion token, instead of a Java object. To obtain roles, authenticated users must be authorized to obtain their roles for the given resource/action combination.
The Role Mapping Service requires that the application pass in a valid identity, a valid resource, and a valid action. The application context is optional and may be set to null if no context is passed in.
The following topics provide more information on the Role Mapping Service.
The role mapping process is as follows (see Figure 5-4):
RoleMappingFailure SOAP Fault is returned to the caller.For more information on the Role Mapping Service interface and the methods it supports, see WSDLdocs for the Web Services Interfaces.
The Role Mapping Service interface supports one method, getRoles(). This method gets the roles for an authenticated user identity in reference to a RuntimeResource, RuntimeAction, and an optional Context.
The getRoles() method accepts a supported type of an identity token, and, optionally, runtime resource and action structures, and an application context. It returns either a list of user roles associated for the identity and a time-to-live parameter for user roles.
Table 5-8 describes the getRoles() method parameters.
The Credential Mapping Service allows an client application to fetch credentials of certain types that are associated with a specific identity for a specific resource. These credentials can then be used on behalf of that identity to execute some privileged function, such as logging into a database or sending e-mail.
The following topics provide more information on the Credential Mapping Service.
The credential mapping process is as follows (see Figure 5-6):
CredentialMappingFailure SOAP Fault to the caller.For more information on the Credential Mapping Service interface and the methods it supports, see WSDLdocs for Web Services Interfaces.
The Credential Mapping Service supports one method: getCredentials(). This method accepts a supported type of an identity assertion token and a list of requested credential types. Optionally, this method can accept an identity assertion token that represents the identity of a different user and a runtime resource structure, which includes the requested resource and action and the application context. In response, the getCredentials() method returns either a list of requested user credentials, identity assertion tokens, and a list of any missing credential types.
| Note: | Since password credentials need to be returned in clear text to the caller in order to be usable for authentication in external systems, you should pay particular attention to providing channel and message security to protect messages in transit between clients and the Web Service. At a minimum, you must use a channel security protocol, such as SSL or TLS, for all communication. |
Authenticated users are always authorized to obtain their own credentials for the given resource/action combination. However, authenticated user cannot requests credentials on behalf of another user.
Credential mapping process involves issuing new types of credentials to the specified combination of user, resource, and action. The user identity is passed as an identity assertion token, instead of a Java object.
Table 5-9 describes the getCredentials() method parameters.
|