Creating SAML 2.0 SP Partners in OAM and IdP

This article discusses the various kinds of information one has to know to set up a Federation agreement between OAM acting as a SAML 2.0 IdP and a remote SAML 2.0 SP Partner, including:

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.

SAML 2.0 with Metadata

OAM Administration Console

To create a new SAML 2.0 SP 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 , Identity Provider Administration.

  3. Click on the Create Service Provider Partner button.

  4. In the Create screen:

    1. Enter a name for the partner.

    2. Select SAML 2.0 as the Protocol.

    3. Click Load Metadata and upload the SAML 2.0 Metadata file for the SP.

    4. Select the NameID format to set in the SAML 2.0 Assertion (for example Email Address NameID format).

  5. Enter how the NameID value to be set:

    1. If selecting User ID Store Attribute, this means that the NameID value to be set to the LDAP Attribute specified in the field next to the drop down.

    2. If selecting Expression, this means that the NameID value to be set based on the expression specified in the field next to the drop down.

  6. Select the Attribute Profile that to be used to populate the SAML Assertion with attributes.

  7. Click Save.

Description of the illustration Service_provider_partner_Screen.jpg

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

Note: The “Attribute Query User Mapping” subsection is only relevant to the SAML Attribute Authority/Request flow, when the SAML Attribute Query exchange is exercised. This flow is not part of the Federation SSO flow.

Description of the illustration Edit_Partner_Screen.jpg

WLST

To create a new SAML 2.0 SP 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 SP Partner with Metadata that will be called acmeSP in OAM: addSAML20SPFederationPartner("acmeSP", "/tmp/acme-sp-metadata-saml20.xml").

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

    1. Use Email Address as the NameID format

    2. User the mail LDAP user attribute as the NameID value

    3. Not encrypt the Assertion

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

  6. Exit the WLST environment: exit().

SAML 2.0 without Metadata

OAM Administration Console

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

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

  2. Navigate to Identity Federation, Identity Provider Administration.

  3. Click on the Create Service Provider Partner button.

  4. In the Create screen:

    1. Enter a name for the partner.

    2. Select SAML 2.0 as the Protocol.

    3. Select Enter Manually.

    4. Enter the Issuer / ProviderID of the SP Partner.

    5. Enter the Assertion Consumer Service URL for that SP Partner: This is the URL where the user is redirected from IdP with the SAML Assertion.

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

    7. If the SP Partner signs SAML messages, upload the 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

    8. If the SAML Assertion needs to be encrypted and that the SP 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

  5. Enter how the NameID value to be set:

    1. If selecting User ID Store Attribute, this means that the NameID value to be set to the LDAP Attribute specified in the field next to the drop down.

    2. If selecting Expression, this means that the NameID value to be set based on the expression specified in the field next to the drop down.

  6. Select the Attribute Profile that is used to populate the SAML Assertion with attributes.

  7. Click Save.

Description of the illustration Create_Service_Provider_Screen.jpg

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

Note: The “Attribute Query User Mapping” subsection is only relevant to the SAML Attribute Authority/Request flow, when the SAML Attribute Query exchange is exercised. This flow is not part of the Federation SSO flow.

Description of the illustration Edit_Partner_withAdvOption_Screen.jpg

WLST

To create a new SAML 2.0 SP Partner without Metadata using the OAM WLST commands, execute the following steps (ensure first that you have all the data from the SP partner, such as certificates, SP 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 SP Partner without Metadata that will be called acmeSP in OAM: addSAML20SPFederationPartnerWithoutMetadata("acmeSP","https://sp.com", "https://sp.com/saml20/sso")

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

    1. Use Email Address as the NameID format

    2. User the mail LDAP user attribute as the NameID value

    3. Not encrypt the Assertion

    4. Not perform Logout

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

    6. Use the default Service Provider Attribute Profile

    7. No certificate has been uploaded for this SP 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:

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 2.0 Logout

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

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

SAML Certificates

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

SP Partner Attribute Profile

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

SAML SSO Request and Response bindings

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

SAML NameID Settings

To configure NameID settings for a SAML SP Partner:

SAML 2.0 Encrypted Assertion

To configure IdP to send or not encrypted SAML 2.0 assertions, execute the following commands:

Examples

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

addSAML20SPFederationPartnerWithoutMetadata("acmeSP","https://sp.com","https://sp.com/saml20/sso")configureSAML20Logout("acmeSP","sp","true",saml20LogoutRequestURL="https://sp.com/saml20/logoutReq",saml20LogoutResponseURL="https://sp.com/saml20/logoutResp")setFederationPartnerSigningCert("acmeSP","sp","/tmp/cert.file")setFederationPartnerEncryptionCert("acmeSP","sp","/tmp/cert.file")setSPSAMLPartnerNameID("acmeSP","orafedemailaddress",nameIDValue="$user.aZr.mail")

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

addSAML20SPFederationPartner("acmeSP", "/tmp/acme-sp-metadata-saml20.xml") setSPSAMLPartnerNameID("acmeSP","orafedemailaddress", nameIDValue="$user.attr.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.