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