Configuring SAML Policies for Identity Bridging

As part of the required SAML credential source workflow, a Policy Manager policy must be configured for the shared web service with:
gateway
As part of the required SAML credential source workflow, a Policy Manager policy must be configured for the shared web service with:
  • The Require SAML Token Profile assertion
  • The federated identities (users, groups, and/or virtual groups) containing credentials shared by the Trusted Authority and Federated Gateway.
Before constructing a policy, ensure that the Policy Validation Messages window is enabled. This window provides you with policy and assertion-level confirmation, warning, or error messages that you can use during the configuration process.
The Policy Manager's policy development window is the repository for the assertions used to develop a policy for a published web service. Most assertions require configuration either before or after being added to the policy development window. After adding the Require SAML Token Profile assertion and federated users, groups, and/or virtual groups to the policy, configure additional policy assertions for the web service as outlined in Policy Assertions Overview and Configure a Policy.
To configure a SAML policy for identity bridging
:
  1. Require SAML Token Profile assertion to a policy.
  2. Configure the SAML Token Profile Wizard as follows:
    Step 2: SAML Version
    Specify which SAML versions will be accepted by the
    API Gateway
    : version 1.x, version 2.x, or any supported version.
    Step 3
    :
    SAML Statement Type
    Select the Authentication Statement option.
    Step 4
    :
    Authentication Methods
    1. Select at least one check box that corresponds to a SAML-specified authentication method that must be enforced by the Require SAML Token Profile assertion.
    2. Click All to select all of the supported authentication methods or None to clear all the check boxes. Select the Unspecified check box to allow authentication by an unspecified method. This page only allows selection of methods applicable to the SAML version chosen in Step 2 of the wizard.
    The "SSL/TLS Certificate Based Client Authentication" method is not related to the Require SSL or TLS Transport assertion in the Policy Manager. This method refers to the original authentication, not to the current request which may or may not have used SSL. The SAML-supported authentication methods are outlined in the SAML 1.x and 2.0 specification documents provided at http://www.oasis-open.org/.
    Proceed to Step 7: Subject Confirmation.
    Step 7
    :
    Subject Confirmation
    Select one or both of the following subject confirmation methods:
    Holder-of-Key
    Select the
    Holder-of-Key
    check box to allow SAML tokens that use the Holder-of-Key subject confirmation method (with the standard URI urn:oasis:names:tc:SAML:1.0:cm:holder-of-key or urn:oasis:names:tc:SAML:2.0:cm:holder-of-key, depending on the selected SAML version in Step 2 of the wizard). For such assertions, the
    API Gateway
    will require that the subject demonstrate possession of the private key corresponding to the public key in the Subject certificate.  
    The Holder-of-Key subject confirmation method currently requires that the request ticket's "SubjectConfirmation" element contain a "KeyInfo" element that contains a complete copy of the Subject's X.509 certificate. Any other type of Holder-of-Key ticket will be rejected by the
    API Gateway
    .
    The request Subject may use one of two methods to prove that they hold this key:
    • The request includes at least one element covered by a valid WSS message signature, and the signing certificate is the Subject certificate. Or,
    • The request arrived over SSL/TLS with client certificate authentication, and the client certificate exactly matches the Subject certificate.
    When the Holder-of-Key subject confirmation method is selected, you can optionally select the Require Message Signature check box to require proof-of-possession using a WSS message signature. If the Require Message Signature check box is not selected, then the policy must contain the Require SSL or TLS Transport assertion.
    Sender Vouches
    Select the Sender Vouches check box to allow SAML tokens that use the Sender Vouches subject confirmation method (with the standard URI urn:oasis:names:tc:SAML:1.0:cm:sender-vouches or urn:oasis:names:tc:SAML:2.0:cm:sender-vouches, depending on the selected SAML version in Step 2 of the wizard). For such assertions, the
    API Gateway
    will require that the sender, presumably different from the subject, vouches for the verification of the subject.
    The
    Sender Vouches
    subject confirmation method is typically used only in a SAML identity bridging policy.
    Three conditions must be met in order to use the Sender Vouches confirmation method:
    • An existing trust relationship with the sender ( "Attesting Entity") must be configured in the
      API Gateway
      . To do this, import the sender's certificate, configured as a "SAML Attesting Entity" certificate, into the Trust Store. For more information, see Add a New Certificate.
    • The SAML ticket used by the SAML Assertion must be bound to the request message by one of the following methods:
    • Send the request over SSL using the sender certificate as the SSL client certificate, or
    • If SSL is not used, then the SAML ticket needs to be bound to the message with a WSS signature. One complication here is that the SAML ticket does not necessarily contain or refer to the sender certificate; it usually contains or refers to the subject certificate and, assuming that the ticket is signed, contains or refers to the certificate of the ticket issuer. In this method, therefore, the WSS signature must cover both the SAML token and the relevant portions of the rest of the message that use the sender certificate as the signing certificate.  
    • The format of the request message must conform to the OASIS Web Services Security standards: SAML Token Profile 1.0 (for SAML 1.x) or SAML Token Profile 1.1 (for SAML 2.x). The
      API Gateway
      does not support references to SAML tokens that are not included with the request message.
    The OASIS Web Services Security: SAML Token Profile 1.0 standards document is available online at: www.oasis-open.org/committees/download.php/1048/WSS-SAML-06.pdf.
    You can optionally select the Require Message Signature check box to require proof-of-possession using an SSL client certificate. If this check box is not selected, then the policy must contain the Require SSL or TLS Transport assertion.
    Step 8: Name Identifier
    • If incoming messages must contain a particular NameQualifier value, enter the value into the Name Qualifier field (for example, "www.example.com").
    • Select the X.509 Subject Name, Email Address, and/or Windows Qualified Domain Name check boxes. If configuring one or more virtual groups for the Federated Identity Provider, you must select the X.509 Subject Name option.
  3. Complete the remainder of the wizard as outlined in SAML Token Profile Wizard.
  4. Add one of these assertions to the policy: Authenticate User or Group or Authenticate Against Identity Provider.
  5. In the Search Identity Provider dialog that appears, add the shared federated user configured in Workflow Using SAML to the policy as follows:
    Field
    Description
    Search
    Select the Federated Identity Provider name from the drop-down list.
    Type
    Select the "Users" search target from the Type drop-down list.
    Name
    If necessary, specify any search criteria using the Name drop-down list and field. You can use the asterisk (*) wildcard to match any number of characters, or the question mark (?) to match any single character.
  6. Click [Search]. The search results are displayed.
  7. In the Search Results window, select the target federated user either by double-clicking the name, or selecting it and clicking [Select].
  8. Repeat to add additional federated users, groups, and/or virtual groups as required.
    A policy with more than one Authenticate User or Group or Authenticate Against Identity Provider assertions must organize the identities into "At least one assertion must evaluate to true" assertion folders. To quickly add one of these folders to the policy development window, right-click anywhere within the window and select Add 'At least one...' Folder from the context menu. Drag and drop federated users, groups, and/or virtual groups into the individual folders as required.
  9. Configure additional policy assertions for the web service. When completed, click [
    Save
    ] in the Policy Tool Bar. Note any error or warning messages in the Policy Validation Messages window. If necessary, correct policy errors as outlined in Validate a Policy.
Proceed to configure the required Gateway Accounts in the CA API Gateway - XML VPN Client. For more information, see Configure Gateway Accounts.