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:
-
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 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:
-
Go to the OAM Administration Console:
http(s)://oam-admin-host:oam-adminport/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 AddressNameID
format).
-
-
Enter how the
NameID
value to be set:-
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. -
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.
-
-
Select the Attribute Profile that to be used to populate the SAML Assertion with attributes.
-
Click Save.
Description of the illustration Service_provider_partner_Screen.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, indicating whether or not OAM 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” 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:
-
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 OAM:addSAML20SPFederationPartner("acmeSP", "/tmp/acme-sp-metadata-saml20.xml")
. -
By default, the new SP partner is 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-adminport/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 is redirected from 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 signs 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 needs 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 to be set:
-
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. -
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.
-
-
Select the Attribute Profile that is used to populate the SAML Assertion with attributes.
-
Click Save.
Description of the illustration Create_Service_Provider_Screen.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, indicating whether or not OAM 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” 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):
-
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 OAM:addSAML20SPFederationPartnerWithoutMetadata("acmeSP","https://sp.com", "https://sp.com/saml20/sso")
-
By default, the new SP partner is 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
This section lists how to change the common SP Partner settings via the OAM WLST commands:
-
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
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.0LogoutRequest
message -
saml20LogoutResponseURL
references the SP partner endpoint that can process a SAML 2.0LogoutResponse
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()
anddeleteFederationPartnerEncryptionCert()
commands are similar to the above ones, except they manages 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 tosp
since the partner is an SP -
binding: The binding to use
httppost
for HTTPPOST binding, orhttpredirect
forHTTPRedirect
binding, for SAML 2.0 AuthnRequest andLogoutRequest
/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 areorafed-emailaddress
forurn:oasis:names:tc:SAML:1.1:nameidformat:emailAddress
-
orafed-x509
forurn:oasis:names:tc:SAML:1.1:nameidformat:X509SubjectName
-
orafed-winflowsnamequaliRer
forurn:oasis:names:tc:SAML:1.1:nameidformat:WinflowsDomainQualiRedName
-
orafed-kerberos
forurn:oasis:names:tc:SAML:2.0:nameidformat:Kerberos
-
orafed-transient
forurn:oasis:names:tc:SAML:2.0:nameidformat:transient
-
orafed-persistent
forurn:oasis:names:tc:SAML:2.0:nameidformat:persistent
-
orafed-unspecified
forurn:oasis:names:tc:SAML:1.1:nameidformat:unspecified
-
orafed-custom
for a customNameID
format that is specified in thecustomFormat
parameter.
-
-
-
customFormat
containing the format to be used, ifnameIDFormat
was set toorafedcustom
-
nameIDValueComputed
: True or false, and indicates whether or not to generate theNameID
from a hash of theUserID
, if thenameIDFormat
is set toorafed-persistent
(SAML 2.0 only)
SAML 2.0 Encrypted Assertion
To configure IdP to send or not encrypted SAML 2.0 assertions, execute the following commands:
-
To configure 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 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","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.
Creating SAML 2.0 SP Partners in OAM and IdP
F60926-01
September 2022
Copyright © 2022, Oracle and/or its affiliates.