Create SAML 2.0 IdP Partners in OAM and SP

This article explains how to set up a Federation agreement between OAM 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 OAM/SP to map an incoming SAML Assertion to an LDAP user

The article describes how to perform the above tasks either via the UI, or via the use of the OAM WLST commands.

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 OAM acting as a Service Provider and delegating user authentication to a remote IdP, the administrator needs to agree with the IdP’s administrator how the user is identified in the SAML Assertion (user information stored in the NameID, or as a SAML Attribute, or in several SAML Attributes..), and then OAM/SP needs to be configured to map the incoming SAML Assertion to an LDAP user record, using the NameID and/or SAML Attribute(s).

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

OAM/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, OAM/SP performs 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, OAM/SP performs 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 contains data from the SAML Assertion:

  • The LDAP query is specified by the administrator

  • The data from the Assertion is 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 is replaced by fed.nameidvalue

• Examples of LDAP queries is:

  • (mail=%email%) that results 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 results in an LDAP lookup for a single LDAP user record whose values for the givenname attribute and sn attribute matches the values of the firstname and lastname SAML Attributes

  • (&(title=manager)(uid=%fed.nameidvalue%)) that results 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

OAM/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 is 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 is used

SAML 2.0 with Metadata

OAM Administration Console

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

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole

2. Navigate to Identity Federation, Service Provider Administration

3. Click on the Create Identity Provider Partner button

4. In the Create screen:

   1. Enter a name for the partner

   2. 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 .

   3. Select SAML 2.0 as the Protocol

   4. Click Load Metadata and upload the SAML 2.0 Metadata file for the IdP Assertion Mapping section:

      1. Optionally set the OAM Identity Store that should be used Note: In the example, we left the field blank to use the default OAM Identity Store

      2. Optionally set the user search base DN Note: In the example, we left the field blank to use the user search base DN configured in the Identity Store

   5. Select how the mapping occurs Note: In the example, we are mapping the Assertion via the NameID to the LDAP mail attribute

   6. Select the Attribute Profile that is used to map the names of the attributes in the incoming SAML Assertion to local names.

5. Click Save

Description of the illustration Create_IDP_Partner.jpg

After the partner is created, the Edit Partner screen is shown with:

• The settings set in the previous screen modifiable

• An Advanced Settings section displayed:

• Enable Global Logout: Indicates whether or not OAM 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 OAM/SP requests the IdP to send the Assertion back to the SP. If checked, OAM/SP requests the IdP to send the Assertion using the HTTP-POST binding, otherwise requests the Artifact binding.

  • HTTP Basic Authentication: If the Artifact binding is used, OAM/SP needs to connect to the IdP directly over SOAP to retrieve the SAML Assertion. Sometimes the IdP enables HTTP Basic Authentication on the SOAP channel, and OAM/SP needs to provide username/password to the IdP (those credentials is agreed between the IdP’s and SP’s administrators).

  • Authentication Request NameID Format: Indicates if OAM/SP should request via the SAML AuthnRequest a specific NameID to be used. If set to None, OAM/SP won’t request anything and the IdP selects 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).

  

  Description of the illustration Edit_Partner_Screen.jpg

WLST

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

1. Enter the WLST environment by executing: $IAM_ORACLE_HOME/common/bin/wlst.sh

2. Connect to the WLS Admin server: connect()

3. Navigate to the Domain Runtime branch: domainRuntime()

4. Create SAML 2.0 IdP Partner with Metadata that is called acmeIdP in OAM: addSAML20IdPFederationPartner("acmeIdP", "/tmp/acme-idp-metadata-saml20.xml")

5. By default, the new IdP partner is configured to:

   1. Use the default OAM Identity Store

   2. Use the user search base DN of the Identity Store (not overridden)

   3. Map the SAML Assertion using the NameID, matching the LDAP mail attribute

   4. Set the Authentication Request NameID Format to None

   5. Use HTTP-POST as the Default SSO Response Binding

   6. Use the default Identity Provider Attribute Profile

6. 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):

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole

2. Navigate to Identity Federation , Service Provider Administration

3. Click on the Create Identity Provider Partner button

4. In the Create screen:

   1. Enter a name for the partner

   2. 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 .

   3. Select SAML 2.0 as the Protocol

   4. Select Enter Manually

   5. Enter the Issuer / ProviderID of the IdP Partner

   6. If the SuccinctID is left blank, OAM/SP computes it by digesting the Provider ID using the SHA-1 algorithm (should be left blank)

   7. Enter the SSO Service URL for that IdP Partner: This is the URL where the user is redirected from OAM/SP with a SAML AuthnRequest to the IdP.

   8. If the partner supports the SAML 2.0 Artifact protocol, enter the SOAP Service URL where OAM/SP connects to retrieve the SAML Assertion during an SSO Artifact operation

   9. If the partner supports the SAML 2.0 Logout protocol:

      1. Enter the SAML 2.0 Logout Request URL where the partner can process a SAML 2.0 LogoutRequest message

      2. Enter the SAML 2.0 Logout Response URL where the partner can process a SAML 2.0 LogoutResponse message

   10. Upload the IdP Signing Certificate file:

       1. 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—–)

       2. or in DER format where the certificate is stored in binary encoding

   11. If the IdP has an Encryption Certificate, upload the file:

       1. 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—–)

       2. or in DER format where the certificate is stored in binary encoding

   12. Assertion Mapping section:

       1. Optionally set the OAM Identity Store that should be used Note: In the example, we left the field blank to use the default OAM Identity Store

       2. Optionally set the user search base DN Note: In the example, we left the field blank to use the user search base DN configured in the Identity Store

   13. Select how the mapping occurs Note: In the example, we are mapping the Assertion via the NameID to the LDAP mail attribute

   14. Select the Attribute Profile that is used to map the names of the attributes in the incoming SAML Assertion to local names.

5. Click Save

Description of the illustration Create_IDP_Provider_Partner.jpg

After the partner is created, the Edit Partner screen is shown with:

• The settings set in the previous screen modifiable

• An Advanced Settings section displayed:

  • Enable Global Logout: Indicates whether or not OAM 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 OAM/SP requests the IdP to send the Assertion back to the SP. If checked, OAM/SP requests the IdP to send the Assertion using the HTTP-POST binding, otherwise requests the Artifact binding.

  • HTTP Basic Authentication: if the Artifact binding is used, OAM/SP needs to connect to the IdP directly over SOAP to retrieve the SAML Assertion. Sometimes the IdP enables HTTP Basic Authentication on the SOAP channel, and OAM/SP needs to provide username/password to the IdP (those credentials is agreed between the IdP’s and SP’s administrators).

  • Authentication Request NameID Format: Indicates if OAM/SP should request via the SAML AuthnRequest a specific NameID to be used. If set to None, OAM/SP won’t request anything and the IdP selects 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).

  

  Description of the illustration Edit_Partner_withAdvOption_Screen.jpg

WLST

To create a new SAML 2.0 IdP Partner without Metadata using the OAM 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):

1. Enter the WLST environment by executing: $IAM_ORACLE_HOME/common/bin/wlst.sh

2. Connect to the WLS Admin server: connect()

3. Navigate to the Domain Runtime branch: domainRuntime()

4. Create SAML 2.0 IdP Partner without Metadata that calls acmeIdP in OAM: addSAML20IdPFederationPartnerWithoutMetadata("acmeIdP","https://acme.com/idp", "https://acme.com/saml20/sso", "https://acme.com/saml20/soap")

5. By default, the new SP partner is configured to:

   1. Use the default OAM Identity Store

   2. Use the user search base DN of the Identity Store (not overridden)

   3. Map the SAML Assertion using the NameID, matching the LDAP mail attribute

   4. Set the Authentication Request NameID Format to None

   5. Use HTTP-POST as the Default SSO Response Binding

   6. Use the default Identity Provider Attribute Profile

   7. No certificate has been uploaded for this IdP partner

6. Exit the WLST environment: exit()

Modifying Federation Settings via WLST

This section lists how to change the common SP Partner settings via the OAM 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

Assume that you are already in the WLST environment and connected using:

1. Enter the WLST environment by executing: $IAM_ORACLE_HOME/common/bin/wlst.sh

2. Connect to the WLS Admin server: connect()

3. Navigate to the Domain Runtime branch: domainRuntime()

SAML Assertion Mapping setting

To configure mapping settings for a SAML IdP Partner:

1. Use the following command to map the Assertion via the 1: setIdPPartnerMappingNameID(partnerName, userstoreAttr)

   1. partnerName is the name that was used to create the IdP Partner

   2. userstoreAttr: LDAP user attribute to match the NameID value.

2. Use the following command to map the Assertion via a SAML Attribute: setIdPPartnerMappingAttribute(partnerName, assertionAttr, userstoreAttr)

   1. partnerName is the name that was used to create the IdP Partner

   2. assertionAttr: Name of the SAML Attribute.

   3. userstoreAttr: LDAP user attribute to match the SAML Attribute value.

3. Use the following command to map the Assertion via an LDAP query: setIdPPartnerMappingAttributeQuery(partnerName, attrQuery)

   1. partnerName is the name that was used to create the IdP Partner

   2. attrQuery: The LDAP query to be used (for example (&(givenname=%firstname%) (sn=%lastname%))).

OAM Identity Store and User Search Base DN

To configure OAM/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 manages the partner’s encryption certificate:

  • getFederationPartnerEncryptionCert("acmeIdP","idp")

  • setFederationPartnerEncryptionCert("acmeIdP","idp", "/tmp/cert.file")

  • deleteFederationPartnerEncryptionCert("acmeIdP","idp")

IdP Partner AMribute ProQl

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 HTTPPOST 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/saml2 /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, we are using the default OAM Identity Styore):

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

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

---

Title and Copyright Information

Create SAML 2.0 IdP Partners in OAM and SP

F59901-01

September 2022

Copyright © 2022, Oracle and/or its affiliates.