Retrieve attribute from SAML attribute assertion

Overview

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>

Details

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.

Trusted Issuers

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.

Subject configuration

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 the authentication.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.

Lookup Attributes

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.