SAML PDP Attributes

Overview

The API Gateway can request information about an authenticated end-user in the form of user attributes from a SAML PDP (Policy Decision Point) using the SAML Protocol (SAMLP). In such cases, the API Gateway presents evidence to the PDP in the form of some user credentials, such as the Distinguished Name of a client's X.509 certificate.

The PDP looks up its configured user store and retrieves attributes associated with that user. The attributes are inserted into a SAML attribute assertion and returned to the API Gateway in a SAMLP response. The assertion and/or SAMLP response is usually signed by the PDP.

When the API Gateway receives the SAMLP response, it performs a number of checks on the response, such as validating the PDP signature and certificate, and examining the assertion. It can also insert the SAML attribute assertion into the original message for consumption by a downstream Web Service.

Request Configuration

This section describes how the API Gateway should package the SAMLP request before sending it to the SAML PDP.

SAML PDP URL Sets

You can configure a group of SAML PDPs to which the API Gateway connects in a round-robin fashion if one or more of the PDPs are unavailable. This is known as a SAML PDP URL Set. You can configure a SAML PDP URL Set using this screen or under the External Connections node in the Policy Studio tree. For more details, see the topic on Configuring URL Groups.

You can configure the following general fields:

  • SAML PDP URL Set:

    Click the button on the right, and select a previously configured SAML PDP URL Set from the tree. To add a URL Set, right-click the SAML PDP URL Sets tree node, and select Add a URL Set. Alternatively, you can configure a SAML PDP URL Set under the External Connections node in the Policy Studio tree.

  • SOAPAction:

    Enter the SOAP Action required to send SAML Protocol requests to the PDP. Click the Use Default button to use the following default SOAP Action as specified by the SAML Protocol:

    http://www.oasis-open.org/committees/security

  • SAML Version:

    Select the SAML version to use in the SAMLP request.

  • Signing Key:

    If the SAMLP request is to be signed, click the Signing Key button, and select the appropriate signing key from the Certificate Store.

SAML Subject:

These details describe the subject of the SAML assertion. Complete the following fields:

  • Subject Attribute:

    Select the message attribute that contains the name of an authenticated username. By default, the authentication.subject.id message attribute is selected, which contains the username of the authenticated user.

  • Subject Format:

    Select the format of the message attribute selected in the Subject Attribute field above.

[Note] Note

There is no need to select a format here if the Subject Attribute field is set to authentication.subject.id

Subject Confirmation:

The settings on the Confirmation Method tab determine how the <SubjectConfirmation> block of the SAML assertion is generated. When the assertion is consumed by a downstream Web Service, the information contained in the <SubjectConfirmation> block can be used to authenticate either the end-user that authenticated to the API Gateway, or the issuer of the assertion, depending on what is configured.

The following is a typical <SubjectConfirmation> block:

<saml:SubjectConfirmation>
  <saml:ConfirmationMethod>
    urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
  </saml:ConfirmationMethod>
    <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
      <dsig:X509Data>
        <dsig:X509SubjectName>CN=oracle</dsig:X509SubjectName>
        <dsig:X509Certificate>
          MIICmzCCAY ...... mB9CJEw4Q=
        </dsig:X509Certificate>
      </dsig:X509Data>
    </dsig:KeyInfo>
  </saml:SubjectConfirmation>
</saml:SubjectConfirmation>

You must configure the following fields on the Subject Confirmation tab:

Method:

The selected value determines the value of the <ConfirmationMethod> element. The following table shows the available methods, their meanings, and their respective values in the <ConfirmationMethod> element:

Method Meaning Value
Holder Of Key A <SubjectConfirmation> is inserted into the SAMLP request. The <SubjectConfirmation> contains a <dsig:KeyInfo> section with the certificate of the user selected to sign the SAMLP request. The user selected to sign the SAMLP request must be the authenticated subject (authentication.subject.id).

Select the Certificate is included if the signer's certificate is to be included in the SubjectConfimration block. Alternatively, select the Only key name is included radio button if only the key name is to be included.

Select the user whose private key is used to sign part of the message in the User Name drop-down list on the Sign Request tab.
urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
Bearer A <SubjectConfirmation> is inserted into the SAMLP request. urn:oasis:names:tc:SAML:1.0:cm:bearer
SAML Artifact A <SubjectConfirmation> is inserted into the SAMLP request. urn:oasis:names:tc:SAML:1.0:cm:artifact
Sender Vouches A <SubjectConfirmation> is inserted into the SAMLP request. The SAMLP request must be signed by a user. urn:oasis:names:tc:SAML:1.0:cm:bearer


If the Method field is left blank, no <ConfirmationMethod> block is inserted into the assertion.

Include Certificate:

Select this option if you wish to include the SAML subject's certificate in the <KeyInfo> section of the <SubjectConfirmation> block.

Include Key Name:

Alternatively, if you do not want to include the certificate, you can select this option to only include the key name in the <KeyInfo> section.

Attributes:

You can list a number of user attributes to include in the SAML attribute assertion that is generated by the API Gateway. If no attributes are explicitly listed in this section, the API Gateway inserts all attributes associated with the user (all user attributes in the attribute.lookup.list message attribute) in the assertion.

To add a specific attribute to the SAML attribute assertion, click the Add button. A user attribute can be configured using the Attribute Lookup dialog.

Enter the name of the attribute that is added to the assertion in the Attribute Name field. Enter the namespace that is associated with this attribute in the Namespace field.

You can edit and remove previously configured attributes using the Edit and Remove buttons.

Response Configuration

The fields on this tab relate to the SAMLP Response returned from the SAML PDP. The following fields are available:

SOAP Actor/Role:

If the SAMLP response from the PDP contains a SAML attribute assertion, the API Gateway can extract it from the response and insert it into the downstream message. The SAML assertion is inserted into the WS-Security block identified by the specified SOAP actor/role.

Drift Time:

The SAMLP request to the PDP is time stamped by the API Gateway. To account for differences in the times on the machines running the API Gateway and the SAML PDP the specified time is subtracted from the time at which the API Gateway generates the SAMLP request.