In this article, I will list the various OIF/SP settings that affect how an AuthnRequest message is created in OIF in a Federation SSO flow.

The AuthnRequest message is used by an SP to start a Federation SSO operation and to indicate to the IdP how the operation should be executed:

• How the user should be challenged at the IdP
• Whether or not the user should be challenged at the IdP, even if a session already exists at the IdP for this user
• Which NameID format should be requested in the SAML Assertion
• Which binding (Artifact or HTTP-POST) should be requested from the IdP to send the Assertion
• Which profile should be used by OIF/SP to send the AuthnRequest message

Enjoy the reading!

Protocols

---

The SAML 2.0, SAML 1.1 and OpenID 2.0 protocols define different message elements and rules that allow an administrator to influence the Federation SSO flows in different manners, when the SP triggers an SSO operation:

• SAML 2.0 allows extensive customization via the AuthnRequest message
• SAML 1.1 does not allow any customization, since the specifications do not define an authentication request message
• OpenID 2.0 allows for some customization, mainly via the OpenID 2.0 extensions such as PAPE or UI

SAML 2.0

OIF/SP allows the customization of the SAML 2.0 AuthnRequest message for the following elements:

• ForceAuthn:
• Boolean indicating whether or not the IdP should force the user for re-authentication, even if the user has still a valid session
• By default set to false
• IsPassive
• Boolean indicating whether or not the IdP is allowed to interact with the user as part of the Federation SSO operation.
• If false, the Federation SSO operation might result in a failure with the NoPassive error code, because the IdP will not have been able to identify the user
• By default set to false
• RequestedAuthnContext
• Element indicating how the user should be challenged at the IdP
• If the SP requests a Federation Authentication Method unknown to the IdP or for which the IdP is not configured, then the Federation SSO flow will result in a failure with the NoAuthnContext error code
• By default missing
• NameIDPolicy
• Element indicating which NameID format the IdP should include in the SAML Assertion
• If the SP requests a NameID format unknown to the IdP or for which the IdP is not configured, then the Federation SSO flow will result in a failure with the InvalidNameIDPolicy error code
• If missing, the IdP will generally use the default NameID format configured for this SP partner at the IdP
• By default missing
• ProtocolBinding
• Element indicating which SAML binding should be used by the IdP to redirect the user to the SP with the SAML Assertion
• Set to Artifact or HTTP-POST
• By default set to HTTP-POST

OIF/SP also allows the administrator to configure the server to:

• Set which binding should be used by OIF/SP to redirect the user to the IdP with the SAML 2.0 AuthnRequest message:
• Redirect or HTTP-POST
• By default set to Redirect
• Set which binding should be used by OIF/SP to redirect the user to the IdP during logout with SAML 2.0 Logout messages:
• Redirect or HTTP-POST
• By default set to Redirect

SAML 1.1

The SAML 1.1 specifications do not define a message for the SP to send to the IdP when a Federation SSO operation is started. As such, there is no capability to configure OIF/SP on how to affect the start of the Federation SSO flow.

OpenID 2.0

OpenID 2.0 defines several extensions that can be used by the SP/RP to affect how the Federation SSO operation will take place:

• OpenID request:
• mode:
• String indicating if the IdP/OP can visually interact with the user
• checkid_immediate does not allow the IdP/OP to interact with the user
• checkid_setup allows user interaction
• By default set to checkid_setup
• PAPE Extension:
• max_auth_age :
• Integer indicating in seconds the maximum amount of time since when the user authenticated at the IdP. If MaxAuthnAge is bigger that the time since when the user last authenticated at the IdP, then the user must be re-challenged.
• OIF/SP will set this attribute to 0 if the administrator configured ForceAuthn to true, otherwise this attribute won't be set
• Default missing
• preferred_auth_policies
• Contains a Federation Authentication Method
• Element indicating how the user should be challenged at the IdP
• By default missing
• Only specified in the OpenID request if the IdP/OP supports PAPE in XRDS, if OpenID discovery is used.
• UI Extension
• Popup mode
• Boolean indicating the popup mode is enabled for the Federation SSO
• By default missing
• Language Preference
• String containing the preferred language, set based on the browser's language preferences.
• By default missing
• Icon:
• Boolean indicating if the icon feature is enabled. In that case, the IdP/OP would look at the SP/RP XRDS to determine how to retrieve the icon
• By default missing
• Only specified in the OpenID request if the IdP/OP supports UI Extenstion in XRDS, if OpenID discovery is used.

ForceAuthn and IsPassive

---

WLST Command

OIF/SP provides the WLST configureIdPAuthnRequest() command to set:

• ForceAuthn as a boolean:
• In a SAML 2.0 AuthnRequest, the ForceAuthn field will be set to true or false
• In an OpenID 2.0 request, if ForceAuthn in the configuration was set to true, then the max_auth_age field of the PAPE request will be set to 0, otherwise, max_auth_age won't be set
• IsPassive as a boolean:
• In a SAML 2.0 AuthnRequest, the IsPassive field will be set to true or false
• In an OpenID 2.0 request, if IsPassive in the configuration was set to true, then the mode field of the OpenID request will be set to checkid_immediate, otherwise set to checkid_setup

Test

In this test, OIF/SP is integrated with a remote SAML 2.0 IdP Partner, with the OOTB configuration. Based on this setup, when OIF/SP starts a Federation SSO flow, the following SAML 2.0 AuthnRequest would be generated:

<samlp:AuthnRequest ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" ID="id-E4BOT7lwbYK56lO57dBaqGUFq01WJSjAHiSR60Q4" Version="2.0" IssueInstant="2014-04-01T21:39:14Z" Destination="https://acme.com/saml20/sso">
   <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://sp.com/oam/fed</saml:Issuer>
   <samlp:NameIDPolicy AllowCreate="true"/>
</samlp:AuthnRequest>

Let's configure OIF/SP for that IdP Partner, so that the SP will require the IdP to re-challenge the user, even if the user is already authenticated:

• 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()
• Execute the configureIdPAuthnRequest() command:
  configureIdPAuthnRequest(partner="AcmeIdP", forceAuthn="true")
• Exit the WLST environment:
  exit()

After the changes, the following SAML 2.0 AuthnRequest would be generated:

<samlp:AuthnRequest ForceAuthn="true" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" ID="id-E4BOT7lwbYK56lO57dBaqGUFq01WJSjAHiSR60Q4" Version="2.0" IssueInstant="2014-04-01T21:39:14Z" Destination="https://acme.com/saml20/sso">
   <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://sp.com/oam/fed</saml:Issuer>
   <samlp:NameIDPolicy AllowCreate="true"/>
</samlp:AuthnRequest>

To display or delete the ForceAuthn/IsPassive settings, perform the following operatons:

• 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()
• Execute the configureIdPAuthnRequest() command:
• To display the ForceAuthn/IsPassive settings on the partner
  configureIdPAuthnRequest(partner="AcmeIdP", displayOnly="true")
• To delete the ForceAuthn/IsPassive settings from the partner
  configureIdPAuthnRequest(partner="AcmeIdP", delete="true")
• Exit the WLST environment:
  exit()

Requested Fed Authn Method

---

In my earlier "Fed Authentication Method Requests in OIF / SP" article, I discussed how OIF/SP could be configured to request a specific Federation Authentication Method from the IdP when starting a Federation SSO operation, by setting elements in the SSO request message.

WLST Command

The OIF WLST commands that can be used are:

• setIdPPartnerProfileRequestAuthnMethod() which will configure the requested Federation Authentication Method in a specific IdP Partner Profile, and accepts the following parameters:
• partnerProfile: name of the IdP Partner Profile
• authnMethod: the Federation Authentication Method to request
• displayOnly: an optional parameter indicating if the method should display the current requested Federation Authentication Method instead of setting it
• delete: an optional parameter indicating if the method should delete the current requested Federation Authentication Method instead of setting it
• setIdPPartnerRequestAuthnMethod() which will configure the specified IdP Partner entry with the requested Federation Authentication Method, and accepts the following parameters:
• partner: name of the IdP Partner
• authnMethod: the Federation Authentication Method to request
• displayOnly: an optional parameter indicating if the method should display the current requested Federation Authentication Method instead of setting it
• delete: an optional parameter indicating if the method should delete the current requested Federation Authentication Method instead of setting it

This applies to SAML 2.0 and OpenID 2.0 protocols. See the "Fed Authentication Method Requests in OIF / SP" article for more information.

Test

In this test, OIF/SP is integrated with a remote SAML 2.0 IdP Partner, with the OOTB configuration. Based on this setup, when OIF/SP starts a Federation SSO flow, the following SAML 2.0 AuthnRequest would be generated:

<samlp:AuthnRequest ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" ID="id-E4BOT7lwbYK56lO57dBaqGUFq01WJSjAHiSR60Q4" Version="2.0" IssueInstant="2014-04-01T21:39:14Z" Destination="https://acme.com/saml20/sso">
   <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://sp.com/oam/fed</saml:Issuer>
   <samlp:NameIDPolicy AllowCreate="true"/>
</samlp:AuthnRequest>

Let's configure OIF/SP for that IdP Partner, so that the SP will request the IdP to use a mechanism mapped to the urn:oasis:names:tc:SAML:2.0:ac:classes:X509 Federation Authentication Method to authenticate the user:

• 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()
• Execute the setIdPPartnerRequestAuthnMethod() command:
  setIdPPartnerRequestAuthnMethod("AcmeIdP", "urn:oasis:names:tc:SAML:2.0:ac:classes:X509")
• Exit the WLST environment:
  exit()

After the changes, the following SAML 2.0 AuthnRequest would be generated:

<samlp:AuthnRequest ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" ID="id-E4BOT7lwbYK56lO57dBaqGUFq01WJSjAHiSR60Q4" Version="2.0" IssueInstant="2014-04-01T21:39:14Z" Destination="https://acme.com/saml20/sso">
   <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://sp.com/oam/fed</saml:Issuer>
   <samlp:NameIDPolicy AllowCreate="true"/>
   <samlp:RequestedAuthnContext Comparison="minimum">
      <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
         urn:oasis:names:tc:SAML:2.0:ac:classes:X509
      </saml:AuthnContextClassRef>
   </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

NameID Format

---

The SAML 2.0 protocol allows for the SP to request from the IdP a specific NameID format to be used when the Assertion is issued by the IdP.

Note: SAML 1.1 and OpenID 2.0 do not provide such a mechanism

Configuring OIF

The administrator can configure OIF/SP to request a NameID format in the SAML 2.0 AuthnRequest via:

• The OAM Administration Console, in the IdP Partner entry
• The OIF WLST setIdPPartnerNameIDFormat() command that will modify the IdP Partner configuration

OAM Administration Console

To configure the requested NameID format via the OAM Administration Console, perform 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
• Open the IdP Partner you wish to modify
• In the Authentication Request NameID Format dropdown box with one of the values
• None
• The NameID format will be set
• Default
• Email Address
• The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• X.509 Subject
• The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
• Windows Name Qualifier
• The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
• Kerberos
• The NameID format will be set urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
• Transient
• The NameID format will be set urn:oasis:names:tc:SAML:2.0:nameid-format:transient
• Unspecified
• The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
• Custom
• In this case, a field would appear allowing the administrator to indicate the custom NameID format to use
• The NameID format will be set to the specified format
• Persistent
• The NameID format will be set urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• I selected Email Address in this example
• Save

WLST Command

To configure the requested NameID format via the OIF WLST setIdPPartnerNameIDFormat() command, perform 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()
• Execute the setIdPPartnerNameIDFormat() command:
  setIdPPartnerNameIDFormat("PARTNER", "FORMAT", customFormat="CUSTOM")
• Replace PARTNER with the IdP Partner name
• Replace FORMAT with one of the following:
• orafed-none
• The NameID format will be set
• Default
• orafed-emailaddress
• The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• orafed-x509
• The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
• orafed-windowsnamequalifier
• The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
• orafed-kerberos
• The NameID format will be set urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
• orafed-transient
• The NameID format will be set urn:oasis:names:tc:SAML:2.0:nameid-format:transient
• orafed-unspecified
• The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
• orafed-custom
• In this case, a field would appear allowing the administrator to indicate the custom NameID format to use
• The NameID format will be set to the specified format
• orafed-persistent
• The NameID format will be set urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• customFormat will need to be set if the FORMAT is set to orafed-custom
• An example would be:
  setIdPPartnerNameIDFormat("AcmeIdP", "orafed-emailaddress")
• Exit the WLST environment:
  exit()

Test

In this test, OIF/SP is integrated with a remote SAML 2.0 IdP Partner, with the OOTB configuration. Based on this setup, when OIF/SP starts a Federation SSO flow, the following SAML 2.0 AuthnRequest would be generated:

<samlp:AuthnRequest ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" ID="id-E4BOT7lwbYK56lO57dBaqGUFq01WJSjAHiSR60Q4" Version="2.0" IssueInstant="2014-04-01T21:39:14Z" Destination="https://acme.com/saml20/sso">
   <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://sp.com/oam/fed</saml:Issuer>
<samlp:NameIDPolicy AllowCreate="true"/>
</samlp:AuthnRequest>

After the changes performed either via the OAM Administration Console or via the OIF WLST setIdPPartnerNameIDFormat() command where Email Address would be requested as the NameID Format, the following SAML 2.0 AuthnRequest would be generated:

<samlp:AuthnRequest ForceAuthn="false" IsPassive="false" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" ID="id-E4BOT7lwbYK56lO57dBaqGUFq01WJSjAHiSR60Q4" Version="2.0" IssueInstant="2014-04-01T21:39:14Z" Destination="https://acme.com/saml20/sso">
   <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://sp.com/oam/fed</saml:Issuer>
<samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" AllowCreate="true"/>
</samlp:AuthnRequest>

Protocol Binding

---

The SAML 2.0 specifications define a way for the SP to request which binding should be used by the IdP to redirect the user to the SP with the SAML 2.0 Assertion: the ProtocolBinding attribute indicates the binding the IdP should use. It is set to:

• Either urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST for HTTP-POST
• Or urn:oasis:names:tc:SAML:2.0:bindings:Artifact for Artifact

The SAML 2.0 specifications also define different ways to redirect the user from the SP to the IdP with the SAML 2.0 AuthnRequest message, as the SP can send the message:

• Either via HTTP Redirect
• Or HTTP POST
• (Other bindings can theoretically be used such as Artifact, but these are not used in practice)

Configuring OIF

OIF can be configured:

• Via the OAM Administration Console or the OIF WLST configureSAMLBinding() command to set the Assertion Response binding to be used
• Via the OIF WLST configureSAMLBinding() command to indicate how the SAML AuthnRequest message should be sent

Note: the binding for sending the SAML 2.0 AuthnRequest message will also be used to send the SAML 2.0 LogoutRequest and LogoutResponse messages.

OAM Administration Console

To configure the SSO Response/Assertion Binding via the OAM Administration Console, perform 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
• Open the IdP Partner you wish to modify
• Check the "HTTP POST SSO Response Binding" box to request the IdP to return the SSO Response via HTTP POST, otherwise uncheck it to request artifact
• Save

WLST Command

To configure the SSO Response/Assertion Binding as well as the AuthnRequest Binding via the OIF WLST configureSAMLBinding() command, perform 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()
• Execute the configureSAMLBinding() command:
  configureSAMLBinding("PARTNER", "PARTNER_TYPE", binding, ssoResponseBinding="httppost")
• Replace PARTNER with the Partner name
• Replace PARTNER_TYPE with the Partner type (idp or sp)
• Replace binding with the binding to be used to send the AuthnRequest and LogoutRequest/LogoutResponse messages (should be httpredirect in most case; default)
• httppost for HTTP-POST binding
• httpredirect for HTTP-Redirect binding
• Specify optionally ssoResponseBinding to indicate how the SSO Assertion should be sent back
• httppost for HTTP-POST binding
• artifactfor for Artifact binding
• An example would be:
  configureSAMLBinding("AcmeIdP", "idp", "httpredirect", ssoResponseBinding="httppost")
• Exit the WLST environment:
  exit()
  

Test

In this test, OIF/SP is integrated with a remote SAML 2.0 IdP Partner, with the OOTB configuration which requests HTTP-POST from the IdP to send the SSO Assertion. Based on this setup, when OIF/SP starts a Federation SSO flow, the following SAML 2.0 AuthnRequest would be generated:

<samlp:AuthnRequest ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" ID="id-E4BOT7lwbYK56lO57dBaqGUFq01WJSjAHiSR60Q4" Version="2.0" IssueInstant="2014-04-01T21:39:14Z" Destination="https://acme.com/saml20/sso">
   <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://sp.com/oam/fed</saml:Issuer>
   <samlp:NameIDPolicy AllowCreate="true"/>
</samlp:AuthnRequest>

In the next article, I will cover the various crypto configuration properties in OIF that are used to affect the Federation SSO exchanges.
Cheers,
Damien Carru