AuthnRequest Settings in OAM and SP

This article lists the various OAM/SP settings that affect how an AuthnRequest message is created in OAM 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 OAM/SP to send the AuthnRequest message

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

OAM/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 is not 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 results 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 results in a failure with the InvalidNameIDPolicy error code
• If missing, the IdP generally uses 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

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

• Set which binding should be used by OAM/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 OAM/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 OAM/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 takes 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.
• OAM/SP sets 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 looks 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 Extension in XRDS, if OpenID discovery is used.

ForceAuthn and IsPassive

WLST Command

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

ForceAuthn as a boolean:

• In a SAML 2.0 AuthnRequest, the ForceAuthn field is 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 is set to 0, otherwise, max_auth_age won’t be set

IsPassive as a boolean:

• In a SAML 2.0 AuthnRequest, the IsPassive field is 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 is set to checkid_immediate, otherwise set to checkid_setup

Test

In this test, OAM/SP is integrated with a remote SAML 2.0 IdP Partner, with the OOTB configuration. Based on this setup, when OAM/SP starts a Federation SSO flow, the following SAML 2.0 AuthnRequest is 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:nameidformat:entity">https://sp.com
/oam/fed</saml:Issuer>
   <samlp:NameIDPolicy AllowCreate="true"/> </samlp:AuthnRequest>

Let’s configure OAM/SP for that IdP Partner, so that the SP requires the IdP to re-challenge the user, even if the user is already authenticated:

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

After the changes, the following SAML 2.0 AuthnRequest is 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:nameidformat: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 operations:

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

Requested Fed Authn Method

In “Fed Authentication Method Requests in OAM / SP” article, we discussed how OAM/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 OAM WLST commands that can be used are:

• setIdPPartnerProfileRequestAuthnMethod() which configures 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 configures 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 OAM / SP” article for more information.

Test

In this test, OAM/SP is integrated with a remote SAML 2.0 IdP Partner, with the OOTB configuration. Based on this setup, when OAM/SP starts a Federation SSO flow, the following SAML 2.0 AuthnRequest is 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:nameidformat:entity">https://sp.com
/oam/fed</saml:Issuer>
   <samlp:NameIDPolicy AllowCreate="true"/> </samlp:AuthnRequest>

Let’s configure OAM/SP for that IdP Partner, so that the SP requests 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:

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

After the changes, the following SAML 2.0 AuthnRequest is 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:nameidformat: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 OAM

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

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

OAM Administration Console

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

Description of the illustration OAM_Administration_Console.jpg

Description of the illustration OAM Administration Console.jpg

WLST Command

To configure the requested NameID format via the OAM WLST setIdPPartnerNameIDFormat() command, perform 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. 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:nameidformat:emailAddress
   • orafed-x509: The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameidformat:X509SubjectName
   • orafed-windowsnamequalifier: The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameidformat:WindowsDomainQualifiedName
   • orafed-kerberos: The NameID format will be set urn:oasis:names:tc:SAML:2.0:nameidformat:Kerberos
   • orafed-transient: The NameID format will be set urn:oasis:names:tc:SAML:2.0:nameidformat:transient
   • orafed-unspecified: The NameID format will be set urn:oasis:names:tc:SAML:1.1:nameidformat:unspecified
   • orafed-custom: In this case, a field appears 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:nameidformat:persistent
     • customFormat will need to be set if the FORMAT is set to orafed-custom An example is: setIdPPartnerNameIDFormat("AcmeIdP", "orafed-emailaddress")
5. Exit the WLST environment: exit()

Test

In this test, OAM/SP is integrated with a remote SAML 2.0 IdP Partner, with the OOTB configuration. Based on this setup, when OAM/SP starts a Federation SSO flow, the following SAML 2.0 AuthnRequest is 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:nameidformat: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 OAM WLST setIdPPartnerNameIDFormat() command where Email Address is requested as the NameID Format, the following SAML 2.0 AuthnRequest is 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:nameidformat:entity">https://sp.com
/oam/fed</saml:Issuer>
<samlp:NameIDPolicy
Format="urn:oasis:names:tc:SAML:1.1:nameidformat: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:HTTPPOST 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 OAM

OAM can be configured:

• Via the OAM Administration Console or the OAM WLST configureSAMLBinding() command to set the Assertion Response binding to be used
• Via the OAM 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:

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole.
2. Navigate to Identity Federation, Service Provider Administration.
3. Open the IdP Partner you wish to modify.
4. 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.
5. Click Save.

Description of the illustration SSO_Response_Assertion_Configuration.jpg

WLST Command

To configure the SSO Response/Assertion Binding as well as the AuthnRequest Binding via the OAM WLST configureSAMLBinding() command, perform 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. Execute the configureSAMLBinding() command: configureSAMLBinding("PARTNER", "PARTNER_TYPE", binding, ssoResponseBinding="httppost")
5. Replace PARTNER with the Partner name
6. Replace PARTNER_TYPE with the Partner type (idp or sp)
7. 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
8. Specify optionally ssoResponseBinding to indicate how the SSO Assertion should be sent back
• httppost for HTTP-POST binding
• artifactfor for Artifact binding An example is: configureSAMLBinding("AcmeIdP", "idp", "httpredirect", ssoResponseBinding="httppost")
9. Exit the WLST environment: exit()

Test

In this test, OAM/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 OAM/SP starts a Federation SSO flow, the following SAML 2.0 AuthnRequest is 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:nameidformat:entity">https://sp.com
/oam/fed</saml:Issuer>
   <samlp:NameIDPolicy AllowCreate="true"/> </samlp:AuthnRequest>

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

AuthnRequest Settings in OAM and SP

F59885-01

September 2022

Copyright © 2022, Oracle and/or its affiliates.