Creating SAML 2.0 SP Partners in OIF / IdP

In this article, I will discuss about the various kinds of information one has to know in order to be able to set up a Federation agreement between OIF acting as a SAML 2.0 IdP and a remote SAML 2.0 SP Partner, including:

  • Set up a remote SAML 2.0 SP Partner with SAML 2.0 Metadata
  • Set up a remote SAML 2.0 SP Partner without SAML 2.0 Metadata

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.

SAML 2.0 with Metadata


OAM Administration Console

To create a new SAML 2.0 SP 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 -> Identity Provider Administration
  • Click on the “Create Service Provider Partner” button
  • In the Create screen:
    • Enter a name for the partner
    • Select SAML 2.0 as the Protocol
    • Click Load Metadata and upload the SAML 2.0 Metadata file for the SP
    • Select the NameID format to set in the SAML 2.0 Assertion (for example Email Address NameID format)
    • Enter how the NameID value will be set:
      • If selecting User ID Store Attribute, this means that the NameID value will be set to the LDAP Attribute specified in the field next to the drop down
      • If selecting Expression, this means that the NameID value will be set based on the expression specified in the field next to the drop down. See my next article on how to Configure IdP to send Attributes for more information on expressions.
    • Select the Attribute Profile that will be used to populate the SAML Assertion with attributes.
    • 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.
    • Encrypt Assertion: if the Assertion sent by the IdP should be encrypted using the SP’s encryption certificate (note: the SP must support encrypted assertions, and the SP’s encryption certificate must have been present in the SAML 2.0 SP Metadata)
    • SSO Response Binding: how the Assertion should be sent to the SP, if the SP did not request any particular binding
    • Note: the “Attribute Query User Mapping” sub-section 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.


WLST

To create a new SAML 2.0 SP 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 SP Partner with Metadata that will be called acmeSP in OIF:
    addSAML20SPFederationPartner("acmeSP", "/tmp/acme-sp-metadata-saml20.xml")
  • By default, the new SP partner will be configured to:
    • Use Email Address as the NameID format
    • User the mail LDAP user attribute as the NameID value
    • Not encrypt the Assertion
    • Use HTTP-POST as the Default SSO Response Binding
  • 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):

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Identity Federation -> Identity Provider Administration
  • Click on the “Create Service Provider Partner” button
  • In the Create screen:
    • Enter a name for the partner
    • Select SAML 2.0 as the Protocol
    • Select Enter Manually
    • Enter the Issuer / ProviderID of the SP Partner
    • Enter the Assertion Consumer Service URL for that SP Partner: this is the URL where the user will be redirected from OIF/IdP with the SAML Assertion.
    • 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
    • If the SP Partner will sign SAML messages, upload the 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 SAML Assertion will need to be encrypted and that the SP 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
    • Enter how the NameID value will be set:
      • If selecting User ID Store Attribute, this means that the NameID value will be set to the LDAP Attribute specified in the field next to the drop down
      • If selecting Expression, this means that the NameID value will be set based on the expression specified in the field next to the drop down. See my next article on how to Configure IdP to send Attributes for more information on expressions.
    • Select the Attribute Profile that will be used to populate the SAML Assertion with attributes.
    • 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.
    • Encrypt Assertion: if the Assertion sent by the IdP should be encrypted using the SP’s encryption certificate (note: the SP must support encrypted assertions, and the SP’s encryption certificate must have been present in the SAML 2.0 SP Metadata)
    • SSO Response Binding: how the Assertion should be sent to the SP, if the SP did not request any particular binding
    • Note: the “Attribute Query User Mapping” sub-section 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.

WLST

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

  • 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 SP Partner without Metadata that will be called acmeSP in OIF:
    addSAML20SPFederationPartnerWithoutMetadata("acmeSP", "https://sp.com", "https://sp.com/saml20/sso")
  • By default, the new SP partner will be configured to:
    • Use Email Address as the NameID format
    • User the mail LDAP user attribute as the NameID value
    • Not encrypt the Assertion
    • Not perform Logout
    • Use HTTP-POST as the Default SSO Response Binding
    • Use the default Service Provider Attribute Profile
    • No certificate has been uploaded for this SP 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 2.0 Logout
  • SAML Signing Certificate
  • SAML Encryption Certificate
  • SP Partner Attribute Profile for an SP Partner
  • SAML NameID settings
  • SAML SSO Request and Response bindings
  • SAML 2.0 Encrypted Assertion

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

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

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

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

  • The configureSAML20Logout() command:
    configureSAML20Logout("acmeSP", "sp", "false")
  • With acmeSP being the name of partner created earlier
  • sp 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("acmeSP", "sp")
    • With acmeSP being the name of partner created earlier
    • sp indicates the partner type
  • setFederationPartnerSigningCert() which uploads the signing certificate file passed as a parameter to the SP Partner configuration:
    setFederationPartnerSigningCert("acmeSP", "sp", "/tmp/cert.file")
    • With acmeSP being the name of partner created earlier
    • sp 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 SP partner entry:
    deleteFederationPartnerSigningCert("acmeSP", "sp")
    • With acmeSP being the name of partner created earlier
    • sp 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("acmeSP", "sp")
    • setFederationPartnerEncryptionCert("acmeSP", "sp", "/tmp/cert.file")
    • deleteFederationPartnerEncryptionCert("acmeSP", "sp")

SP Partner Attribute Profile

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

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

SAML SSO Request and Response bindings

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

  • To configure the SP partner, execute:
    configureSAMLBinding(partnerName, partnerType, binding, ssoResponseBinding="httppost")
    • partnerName is the name that was used to create the SP Partner
    • partnerType should be set to "sp" 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 SP; httppost for HTTP-POST binding, or artifact for Artifact binding

SAML NameID Settings

To configure NameID settings for a SAML SP Partner:

  • Use the following command:
    setSPSAMLPartnerNameID(partnerName, nameIDFormat, nameIDValue="", customFormat="", nameIDValueComputed="false")
    • partnerName is the name that was used to create the SP Partner
    • nameIDFormat: possible values are
      • orafed-emailaddress for urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
      • orafed-x509 for urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
      • orafed-windowsnamequalifier for urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
      • orafed-kerberos for urn:oasis:names:tc:SAML:2.0:nameid-format:Kerberos
      • orafed-transient for urn:oasis:names:tc:SAML:2.0:nameid-format:transient
      • orafed-persistent for urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
      • orafed-unspecified for urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
      • orafed-custom for a custom NameID format that will be specified in the customFormat parameter.
    • customFormat containing the format to be used, if nameIDFormat was set to orafed-custom
    • nameIDValueComputed: true or false, and indicates whether or not to generate the NameID from a hash of the UserID, if the nameIDFormat is set to orafed-persistent (SAML 2.0 only)

SAML 2.0 Encrypted Assertion

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

  • To configure OIF/IdP to encrypt the SAML 2.0 Assertion for an SP Partner, execute:
    updatePartnerProperty(partnerName, "sp", "sendencryptedassertion", "true", "boolean")
    • partnerName is the name that was used to create the SP Partner
  • To configure OIF/IdP to send a plain (default) the SAML 2.0 Assertion for an SP Partner, execute:
    updatePartnerProperty(partnerName, "sp", "sendencryptedassertion", "false", "boolean")
    • partnerName is the name that was used to create the SP Partner

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", "orafed-emailaddress", nameIDValue="$user.attr.mail")

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

addSAML20SPFederationPartner("acmeSP", "/tmp/acme-sp-metadata-saml20.xml")
setSPSAMLPartnerNameID("acmeSP", "orafed-emailaddress", nameIDValue="$user.attr.mail")


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


Comments:

Hi Damien,

Thank you. It's very nice blog on how to configure SAML. I've a similar set up in our environment but I'm facing "webpage not available" error when trying to access Provider ID in browser(eg: https://sp.com). It's not redirecting me to OAM SSO.

Can you please help me to troubleshoot the issue.

Regards,
Sunil

Posted by Sunil on January 05, 2015 at 11:53 AM EST #

The Provider ID is an identifier used to uniquely reference a Federation server. It is a URI that can be a URL (like http://sp.com), or not (like urn:fed:sp:acme).

When the Provider ID is a URL, it is not required to that the URL points to an actual service that can be accessed by entering the Provider ID URL in a browser.
To access services, refer to the documentation of the product you are using to determine what are the URLs where the federation services for your server are published, as they vary depending on the product.

Hope this helps.
Damien

Posted by Damien on January 27, 2015 at 11:55 AM EST #

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
« July 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
29
30
31
 
       
Today