AuthnRequest Settings in OIF / SP
- by Damien Carru
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 partnerconfigureIdPAuthnRequest(partner="AcmeIdP", displayOnly="true")
To delete the ForceAuthn/IsPassive settings from the partnerconfigureIdPAuthnRequest(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
