A SAML (Security Assertion Markup Language) attribute assertion contains
information about a user in the form of a series of attributes. The
Retrieve from SAML Attribute Assertion filter can retrieve
these attributes and store them in the
attribute.lookup.list
message attribute.
The following SAML attribute assertion contains three attributes, "role",
"email", and "dept". The
Retrieve from SAML Attribute Assertion filter stores all three
attributes and their values in the
attribute.lookup.list
message attribute.
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"> <soap:Header> <wsse:Security> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="Id-0000010a3c4ff12c-0000000000000002" IssueInstant="2006-03-27T15:26:12Z" Version="2.0"> <saml:Issuer Format="urn:oasis ... WindowsDomainQualifiedName"> TestCA </saml:Issuer> <saml:Subject> <saml:NameIdentifier Format="urn:oasis ... WindowsDomainQualifiedName"> TestUser </saml:NameIdentifier> </saml:Subject> <saml:Conditions NotBefore="2005-03-27T15:20:40Z" NotOnOrAfter="2028-03-27T17:20:40Z"/> <saml:AttributeStatement> <saml:Attribute Name="role" NameFormat="http://www.oracle.com"> <saml:AttributeValue>admin</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="email" NameFormat="http://www.oracle.com"> <saml:AttributeValue>joe@oracle.com</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="dept" NameFormat=""> <saml:AttributeValue>engineering</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion> </wsse:Security> </soap:Header> <soap:Body> <product> <name>API Gateway</name> <company>Oracle</company> <description>Web Services Security</description> </product> </soap:Body> </soap:Envelope>
The following fields are available on the Details configuration tab:
Name:
Enter a name for this filter here.
SOAP Actor/Role:
If you expect the SAML assertion to be embedded within a WS-Security block, you can identify this block by specifying the SOAP Actor or Role of the WS-Security header that contains the assertion.
XPath Expression:
Alternatively, if the assertion is not contained within a WS-Security block, you can enter an XPath expression to locate the attribute assertion. XPath expressions can be added by selecting the Add button. Expressions can be edited and deleted by selecting an XPath expression and clicking the Add and Delete buttons respectively.
SAML Namespace:
Select the SAML namespace that must be used on the SAML assertion in order for this filter to succeed. If you do not wish to check the namespace, select the "Do not check version" option from the dropdown.
SAML Version:
Enter the SAML Version that the assertion must adhere to by entering the major version in the 1st field, followed by the minor version in the 2nd field. For example, for SAML version 2.0, enter "2" in the 1st field and "0" in the 2nd field.
Drift Time:
When the API Gateway receives a SAML attribute assertion, it first checks to
make sure that it has not expired. The lifetime of the assertion is
specified using the "NotBefore" and "NotOnOrAfter" attributes of the
<Conditions>
element in the assertion itself.
The API Gateway makes sure that the time at which it validates
the assertion is between the "NotBefore" and "NotOnOrAfter" times.
The Drift Time is used to account for differences in the clock time of the machine that generated the assertion and the machine hosting the API Gateway. The time specified here will be subtracted from the time at which the API Gateway attempts to validate the assertion.
You can use the table on this tab to select the issuers that you consider trusted. In other words, this filter will only accept assertions that have been issued by the SAML Authorities selected here.
Click the Add button to display the Trusted Issuers screen. Select the Distinguished Name of a SAML Authority whose certificate has been added to the Certificate Store and click the OK button. Repeat this step to add more SAML Authorities to the list of trusted issuers.
The API Gateway can perform some very basic authentication checks on the
subject or sender of the assertion using the options available on the
Subject tab. The API Gateway can compare the subject of the
assertion (i.e. the <NameIdentifier>
) to
one of the following values:
-
Subject of the Authentication Filter:
Select this option if the user specified in the
<NameIdentifier>
element must match the user that authenticated to the API Gateway. The subject of the authentication event is stored in theauthentication.subject.id
message attribute. -
A User-Specified Value:
This option can be used if the
<NameIdentifier>
must match a user-specified value. Select this radio button and enter the value in the field provided. -
No Authentication:
If the Neither of the above radio button is selected, the API Gateway will not attempt to match the
<NameIdentifier>
to any value.
The Lookup Attributes tab is used to determine what
attributes the API Gateway should extract from the SAML attribute assertion.
Extracted attributes and their values will be set to the
attribute.lookup.list
message attribute.
The table lists the attributes that the API Gateway will extract from the
assertion and set to the attribute.lookup.list
.
Alternatively, check the
Extract all of the attributes from the SAML assertion
check box to configure the API Gateway to extract all attributes from the
assertion. All attributes will be set to the
attribute.lookup.list
message attribute.
To configure a specific attribute to lookup in the message, click the
Add button to display the
Attribute Lookup dialog. Enter the value of the "Name"
attribute of the <Attribute>
element in the
Name field. Enter the value of the "NameFormat"
attribute of the <Attribute>
element in the
Namespace field.