Create SAML 2.0 IdP Partners in OIF/ SP

After having discussed in previous articles how to manage OIF/IdP, I will cover the administration of OIF/SP. In this post, I will explain how to set up a Federation agreement between OIF acting as a SAML 2.0 SP and a remote SAML 2.0 IdP Partner, including:

  • Set up a remote SAML 2.0 IdP Partner with SAML 2.0 Metadata
  • Set up a remote SAML 2.0 IdP Partner without SAML 2.0 Metadata
  • Configuring OIF/SP to map an incoming SAML Assertion to an LDAP user

The article will describe how to perform the above tasks either via the UI, or via the use of the OIF WLST commands.

Enjoy the reading!

Establishing Federation Trust


Establishing Trust between Federation partners is a pre-requisite before being able to perform any Federation SSO operation between the Federation servers.

Trust establishment involves exchanging certificate information, if the protocol used relies on PKI X.509 certificates to secure message exchanges, as well as the locations/URLs of the services implementing the federation protocol.

Assertion Mapping


With OIF acting as a Service Provider and delegating user authentication to a remote IdP, the administrator will need to agree with the IdP’s administrator how the user will be identified in the SAML Assertion (user information stored in the NameID, or as a SAML Attribute, or in several SAML Attributes..), and then OIF/SP will need to be configured to map the incoming SAML Assertion to an LDAP user record, using the NameID and/or SAML Attribute(s).

Note: OAM requires the incoming Assertion to be mapped to an LDAP user record in order to create an OAM session.

OIF/SP can map an incoming SAML Assertion to an LDAP user record via:

  • The SAML Assertion NameID, mapped to an attribute in the LDAP user record: in this case, OIF/SP will perform an LDAP lookup for a single LDAP user record whose value for the attribute specified in the mapping matches the value of the SAML NameID.
  • A SAML Attribute from the Assertion, mapped to an attribute in the LDAP user record: in this case, OIF/SP will perform an LDAP lookup for a single LDAP user record whose value for the attribute specified in the mapping matches the value of the specified SAML Attribute.
  • The use of an LDAP query that will contain data from the SAML Assertion:
    • The LDAP query will be specified by the administrator
    • The data from the Assertion will be identified in the LDAP query as %NAME%, with NAME being:
      • Either the name of a SAML Attribute from the Assertion
      • Or the NameID: in this case, NAME will be replaced by fed.nameidvalue
    • Examples of LDAP queries would be:
      • (mail=%email%) that will result in an LDAP lookup for a single LDAP user record whose value for the mail attribute matches the value of the email SAML Attribute
      • (&(givenname=%firstname%)(sn=%lastname%)) that will result in an LDAP lookup for a single LDAP user record whose values for the givenname attribute and sn attribute matche the values of the firstname and lastname SAML Attributes
      • (&(title=manager)(uid=%fed.nameidvalue%)) that will result in an LDAP lookup for a single LDAP user record whose value for the uid attribute matches the value of the NameID, and whose title attribute is equals to manager

OIF/SP also provides the capabilities to use a specific Identity Store and user search base DN when mapping the Assertion to an LDAP user record. This is optional, and:

  • If no specific Identity Store is specified in the Assertion Mapping rules, then the default OAM Identity Store will be used
  • If no specific user search base DN is specified in the Assertion Mapping rules, then the user search base DN configured in the Identity Store will be used

SAML 2.0 with Metadata


OAM Administration Console

To create a new SAML 2.0 IdP Partner with Metadata, execute the following steps:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Identity Federation -> Service Provider Administration
  • Click on the “Create Identity Provider Partner” button
  • In the Create screen:
    • Enter a name for the partner
    • Check whether or not this partner should be used as the IdP by default when starting a Federation SSO operation, if no IdP partner is specified.
    • Select SAML 2.0 as the Protocol
    • Click Load Metadata and upload the SAML 2.0 Metadata file for the IdP
    • Assertion Mapping section:
      • Optionally set the OAM Identity Store that should be used (note: in the example, I left the field blank to use the default OAM Identity Store)
      • Optionally set the user search base DN (note: in the example, I left the field blank to use the user search base DN configured in the Identity Store)
      • Select how the mapping will occur (note: in the example, I am mapping the Assertion via the NameID to the LDAP mail attribute)
    • Select the Attribute Profile that will be used to map the names of the attributes in the incoming SAML Assertion to local names. See my next article on IdP Attribute Profile for more information. In this example, I will use the default IdP Attribute Profile.
    • Click Save

After the partner is created, the “Edit Partner” screen will be shown with:

  • The settings set in the previous screen modifiable
  • An Advanced Settings section displayed:
    • Enable Global Logout, indicating whether or not OIF should execute the SAML 2.0 Logout exchange with the partner as part of the logout process.
    • HTTP POST SSO Response Binding: indicates how the OIF/SP will request the IdP to send the Assertion back to the SP. If checked, OIF/SP will request the IdP to send the Assertion using the HTTP-POST binding, otherwise will request the Artifact binding.
    • HTTP Basic Authentication: if the Artifact binding is used, OIF/SP will need to connect to the IdP directly over SOAP to retrieve the SAML Assertion. Sometimes the IdP will enable HTTP Basic Authentication on the SOAP channel, and OIF/SP will need to provide username/password to the IdP (those credentials will be agreed between the IdP’s and SP’s administrators).
    • Authentication Request NameID Format: indicates if OIF/SP should request via the SAML AuthnRequest a specific NameID to be used. If set to None, OIF/SP won’t request anything and the IdP will select the NameID format that was agreed upon out of band. If you set a value, be sure that it corresponds to what was agreed upon between the IdP’s and SP’s administrators. (Can be left blank)

WLST

To create a new SAML 2.0 IdP Partner with Metadata using the OIF WLST commands, execute the following steps:

  • Enter the WLST environment by executing:
    $IAM_ORACLE_HOME/common/bin/wlst.sh
  • Connect to the WLS Admin server:
    connect()
  • Navigate to the Domain Runtime branch:
    domainRuntime()
  • Create SAML 2.0 IdP Partner with Metadata that will be called acmeIdP in OIF:
    addSAML20IdPFederationPartner("acmeIdP", "/tmp/acme-idp-metadata-saml20.xml")
  • By default, the new IdP partner will be configured to:
    • Use the default OAM Identity Store
    • Use the user search base DN of the Identity Store (not overridden)
    • Map the SAML Assertion using the NameID, matching the LDAP mail attribute
    • Set the Authentication Request NameID Format to None
    • Use HTTP-POST as the Default SSO Response Binding
    • Use the default Identity Provider Attribute Profile
  • Exit the WLST environment:
    exit()

SAML 2.0 without Metadata


OAM Administration Console

To create a new SAML 2.0 IdP Partner without Metadata, execute the following steps (ensure first that you have all the data from the IdP partner, such as certificates, IdP identifiers and URLs):

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Identity Federation -> Service Provider Administration
  • Click on the “Create Identity Provider Partner” button
  • In the Create screen:
    • Enter a name for the partner
    • Check whether or not this partner should be used as the IdP by default when starting a Federation SSO operation, if no IdP partner is specified.
    • Select SAML 2.0 as the Protocol
    • Select Enter Manually
    • Enter the Issuer / ProviderID of the IdP Partner
    • If the SuccinctID is left blank, OIF/SP will compute it by digesting the Provider ID using the SHA-1 algorithm (should be left blank)
    • Enter the SSO Service URL for that IdP Partner: this is the URL where the user will be redirected from OIF/SP with a SAML AuthnRequest to the IdP.
    • If the partner supports the SAML 2.0 Artifact protocol, enter the SOAP Service URL where OIF/SP will connect to retrieve the SAML Assertion during an SSO Artifact operation
    • If the partner supports the SAML 2.0 Logout protocol:
      • Enter the SAML 2.0 Logout Request URL where the partner can process a SAML 2.0 LogoutRequest message
      • Enter the SAML 2.0 Logout Response URL where the partner can process a SAML 2.0 LogoutResponse message
    • Upload the IdP Signing Certificate file:
      • either in PEM format (where the file contains as the first line -----BEGIN CERTIFICATE-----, then the certificate in Base64 encoded format, then the last line as -----END CERTIFICATE-----)
      • or in DER format where the certificate is stored in binary encoding
    • If the IdP has an Encryption Certificate, upload the file:
      • either in PEM format (where the file contains as the first line -----BEGIN CERTIFICATE-----, then the certificate in Base64 encoded format, then the last line as -----END CERTIFICATE-----)
      • or in DER format where the certificate is stored in binary encoding
    • Assertion Mapping section:
      • Optionally set the OAM Identity Store that should be used (note: in the example, I left the field blank to use the default OAM Identity Store)
      • Optionally set the user search base DN (note: in the example, I left the field blank to use the user search base DN configured in the Identity Store)
      • Select how the mapping will occur (note: in the example, I am mapping the Assertion via the NameID to the LDAP mail attribute)
    • Select the Attribute Profile that will be used to map the names of the attributes in the incoming SAML Assertion to local names. See my next article on IdP Attribute Profile for more information. In this example, I will use the default IdP Attribute Profile.
    • Click Save

After the partner is created, the “Edit Partner” screen will be shown with:

  • The settings set in the previous screen modifiable
  • An Advanced Settings section displayed:
    • Enable Global Logout, indicating whether or not OIF should execute the SAML 2.0 Logout exchange with the partner as part of the logout process.
    • HTTP POST SSO Response Binding: indicates how the OIF/SP will request the IdP to send the Assertion back to the SP. If checked, OIF/SP will request the IdP to send the Assertion using the HTTP-POST binding, otherwise will request the Artifact binding.
    • HTTP Basic Authentication: if the Artifact binding is used, OIF/SP will need to connect to the IdP directly over SOAP to retrieve the SAML Assertion. Sometimes the IdP will enable HTTP Basic Authentication on the SOAP channel, and OIF/SP will need to provide username/password to the IdP (those credentials will be agreed between the IdP’s and SP’s administrators).
    • Authentication Request NameID Format: indicates if OIF/SP should request via the SAML AuthnRequest a specific NameID to be used. If set to None, OIF/SP won’t request anything and the IdP will select the NameID format that was agreed upon out of band. If you set a value, be sure that it corresponds to what was agreed upon between the IdP’s and SP’s administrators. (Can be left blank)

WLST

To create a new SAML 2.0 IdP Partner without Metadata using the OIF WLST commands, execute the following steps (ensure first that you have all the data from the IdP partner, such as certificates, IdP identifiers and URLs):

  • Enter the WLST environment by executing:
    $IAM_ORACLE_HOME/common/bin/wlst.sh
  • Connect to the WLS Admin server:
    connect()
  • Navigate to the Domain Runtime branch:
    domainRuntime()
  • Create SAML 2.0 IdP Partner without Metadata that will be called acmeIdP in OIF:
    addSAML20IdPFederationPartnerWithoutMetadata("acmeIdP", "https://acme.com/idp", "https://acme.com/saml20/sso", "https://acme.com/saml20/soap")
  • By default, the new SP partner will be configured to:
    • Use the default OAM Identity Store
    • Use the user search base DN of the Identity Store (not overridden)
    • Map the SAML Assertion using the NameID, matching the LDAP mail attribute
    • Set the Authentication Request NameID Format to None
    • Use HTTP-POST as the Default SSO Response Binding
    • Use the default Identity Provider Attribute Profile
    • No certificate has been uploaded for this IdP partner
  • Exit the WLST environment:
    exit()

Modifying Federation Settings via WLST

In this section, I will list how to change the common SP Partner settings via the OIF WLST commands:

  • SAML Assertion Mapping settings
  • OAM Identity Store and User Search Base DN for SAML Assertion Mapping
  • SAML 2.0 Logout
  • SAML Signing Certificate
  • SAML Encryption Certificate
  • IdP Partner Attribute Profile for an IdP Partner
  • SAML SSO Request and Response bindings

I will assume that you are already in the WLST environment and connected using:

  • Enter the WLST environment by executing:
    $IAM_ORACLE_HOME/common/bin/wlst.sh
  • Connect to the WLS Admin server:
    connect()
  • Navigate to the Domain Runtime branch:
    domainRuntime()

SAML Assertion Mapping settings

To configure mapping settings for a SAML IdP Partner:

  • Use the following command to map the Assertion via the NameID:
    setIdPPartnerMappingNameID(partnerName, userstoreAttr)
    • partnerName is the name that was used to create the IdP Partner
    • userstoreAttr: LDAP user attribute to match the NameID value.
  • Use the following command to map the Assertion via a SAML Attribute:
    setIdPPartnerMappingAttribute(partnerName, assertionAttr, userstoreAttr)
    • partnerName is the name that was used to create the IdP Partner
    • assertionAttr: name of the SAML Attribute.
    • userstoreAttr: LDAP user attribute to match the SAML Attribute value.
  • Use the following command to map the Assertion via an LDAP query:
    setIdPPartnerMappingAttributeQuery(partnerName, attrQuery)
    • partnerName is the name that was used to create the IdP Partner
    • attrQuery: the LDAP query to be used (for example (&(givenname=%firstname%)(sn=%lastname%))).

OAM Identity Store and User Search Base DN

To configure OIF/SP to use a specific OAM Identity Store and/or a specific User Search Base DN when mapping the incoming SAML Assertion, execute the following command setPartnerIDStoreAndBaseDN():

  • Use the following command to set the OAM Identity Store only:
    setPartnerIDStoreAndBaseDN(partnerName, "idp", storeName="oid")
    • partnerName is the name that was used to create the IdP Partner
    • idp indicates the partner type
    • storeName: references the OAM Identity Store to use
  • Use the following command to set the Search Base DN only:
    setPartnerIDStoreAndBaseDN(partnerName, "idp", searchBaseDN="ou=managers,dc=acme,dc=com")
    • partnerName is the name that was used to create the IdP Partner
    • idp indicates the partner type
    • searchBaseDN: indicates the search base DN to use
  • Use the following command to set the OAM Identity Store and Search Base DN:
    setPartnerIDStoreAndBaseDN(partnerName, "idp", storeName="oid", searchBaseDN="ou=managers,dc=acme,dc=com")
    • partnerName is the name that was used to create the IdP Partner
    • idp indicates the partner type
    • storeName: references the OAM Identity Store to use
    • searchBaseDN: indicates the search base DN to use
    • Use the following command to remove the OAM Identity Store and Search Base DN from the IdP partner entry:
    • setPartnerIDStoreAndBaseDN(partnerName, "idp", delete="true")
    • partnerName is the name that was used to create the IdP Partner
    • idp indicates the partner type

SAML 2.0 Logout

To enable SAML 2.0 Logout and specify the IdP partner SAML 2.0 logout URLs, execute:

  • The configureSAML20Logout() command:
    configureSAML20Logout("acmeIdP", "idp", "true", saml20LogoutRequestURL="https://acme.com/saml20/logoutReq", saml20LogoutResponseURL="https://acme.com/saml20/logoutResp")
  • With acmeIdP being the name of partner created earlier
  • idp indicates the partner type
  • true indicates that SAML 2.0 Logout is enabled
  • saml20LogoutRequestURL references the IdP partner endpoint that can process a SAML 2.0 LogoutRequest message
  • saml20LogoutResponseURL references the IdP partner endpoint that can process a SAML 2.0 LogoutResponse message

To disable the SAML 2.0 Logout for the IdP partner, execute:

  • The configureSAML20Logout() command:
    configureSAML20Logout("acmeIdP", "idp", "false")
  • With acmeIdP being the name of partner created earlier
  • idp indicates the partner type
  • false indicates that SAML 2.0 Logout is enabled

SAML Certificates

There are various WLST commands available to manage signing and encryption certificates:

  • getFederationPartnerSigningCert() which prints the partner’s signing certificate in Base64 encoded format:
    getFederationPartnerSigningCert("acmeIdP", "idp")
    • With acmeIdP being the name of partner created earlier
    • idp indicates the partner type
  • setFederationPartnerSigningCert() which uploads the signing certificate file passed as a parameter to the IdP Partner configuration:
    setFederationPartnerSigningCert("acmeIdP", "idp", "/tmp/cert.file")
    • With acmeIdP being the name of partner created earlier
    • idp indicates the partner type
    • the third parameter indicates the location on the file system of the file containing the certificate:
      • either in PEM format (where the file contains as the first line -----BEGIN CERTIFICATE-----, then the certificate in Base64 encoded format, then the last line as -----END CERTIFICATE-----)
      • or in DER format where the certificate is stored in binary encoding
  • deleteFederationPartnerSigningCert() which removes the signing certificate from the IdP partner entry:
    deleteFederationPartnerSigningCert("acmeIdP", "idp")
    • With acmeIdP being the name of partner created earlier
    • idp indicates the partner type
  • the getFederationPartnerEncryptionCert(),  setFederationPartnerEncryptionCert() and deleteFederationPartnerEncryptionCert() commands are similar to the above ones, except they will manage the partner’s encryption certificate:
    • getFederationPartnerEncryptionCert("acmeIdP", "idp")
    • setFederationPartnerEncryptionCert("acmeIdP", "idp", "/tmp/cert.file")
    • deleteFederationPartnerEncryptionCert("acmeIdP", "idp")

IdP Partner Attribute Profile

To configure the IdP Partner Attribute Profile for a specific IdP Partner, use the following commands:

  • To configure an IdP Partner to use a specific IdP Partner Attribute Profile, execute:
    setIdPPartnerAttributeProfile(partnerName, attrProfileID)
    • partnerName is the name that was used to create the IdP Partner
    • attrProfileID is the IdP Partner Attribute Profile ID
  • To list the existing the IdP Partner Attribute Profiles, execute:
    listIdPPartnerAttributeProfileIDs()

SAML SSO Request and Response bindings

To configure the SAML bindings for a specific IdP Partner, use the following commands:

  • To configure the IdP partner, execute:
    configureSAMLBinding(partnerName, partnerType, binding, ssoResponseBinding="httppost")
    • partnerName is the name that was used to create the IdP Partner
    • partnerType should be set to "idp" since the partner is an SP
    • binding: the binding to use httppost for HTTP-POST binding, or httpredirect for HTTP-Redirect binding, for SAML 2.0 AuthnRequest and LogoutRequest/LogoutResponse messages. SAML 2.0 only
    • ssoResponseBinding: The binding to use to send the SAML Assertion back to the IdP; httppost for HTTP-POST binding, or artifact for Artifact binding

Examples

The below commands could be used to add an IdP partner without SAML 2.0 Metadata:

addSAML20IdPFederationPartnerWithoutMetadata("acmeIdP", "https://acme.com/idp", "https://acme.com/saml20/sso", "https://acme.com/saml20/soap")
configureSAML20Logout("acmeIdP", "idp", "true", "https://acme.com/saml20/logoutReq", "https://acme.com/saml20/logoutResp")
setFederationPartnerSigningCert("acmeIdP", "idp", "/tmp/acme-idp-cert.pem")
setPartnerIDStoreAndBaseDN("acmeIdP", "idp", "oid")
setIdPPartnerMappingNameID("acmeIdP", "mail")

The below commands could be used to add an IdP partner with SAML 2.0 Metadata (in this example, I am using the default OAM Identity Styore):

addSAML20IdPFederationPartner("acmeIdP", "/tmp/acme-idp-metadata-saml20.xml")
setIdPPartnerMappingNameID("acmeIdP", "mail")

In the next article, I will be covering SAML 1.1 and OpenID 2.0 IdP Partner creation.
Cheers,
Damien Carru

Comments:

I've been working with a customer to set up a SAML federated URL within OAM. We manually created the IdP, and when the challenge URL is accessed, we observe the following in the OAM logs:

FED-10119 - The specified binding (httpredirect) for single sign-on with **** is not supported by the peer provider.

Might you have any insights into this error, such as what precisely is the "peer provider?"

Posted by guest on April 24, 2014 at 03:53 PM EDT #

Hi,

Sometimes a remote Federation partner is also called a peer provider (as in Service Provider or Identity Provider)

Damien

Posted by Damien on October 07, 2014 at 05:45 PM EDT #

Post a Comment:
  • HTML Syntax: NOT allowed
About

Damien Carru is a member of the Oracle Identity Management organization, focusing on Federation and SSO. This blog will cover Federation use cases involving Oracle Access Manager, Oracle Identity Federation and Oracle Security Token Service

Search

Categories
Archives
« February 2015
SunMonTueWedThuFriSat
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
       
       
Today