X

Tips and HowTos for Single Sign-On & Federation Oracle Identity Management Integrations

  • October 22, 2014

Determining which IdP to use for Federation SSO

As a Service Provider, when triggering a Federation SSO operation, the main challenge sometimes lies with determining which IdP will be selected for the SSO flow, in cases where the SP has trust agreements with multiple IdPs.

OIF/SP has different mechanism to select the IdP for the Federation SSO operation, including:

  • Having the OAM Federation Scheme indicating the IdP to be used
  • Having a custom OAM Authentication Plugin setting the IdP to be used
  • Using a SAML 2.0 IdP Discovery Service if the IdP was neither specified by the Scheme nor by a custom plugin
  • Using the Default SSO IdP if no IdP Discovery Service is used

This article will explore each mechanism more closely.

OAM Federation Scheme


OIF provides administration tools to create an OAM Authentication Scheme which will be:

  • A Federation Scheme
  • Bound to a specific IdP Partner

When a resource is protected with that kind of Authentication Scheme, and if a non authenticated user requests access, a Federation SSO flow will be triggered with the IdP Partner to which the scheme is bound.

Creating such schemes allows an administrator to have specific resources which will result in a Federation SSO with specific IdP Partners.

Note: if the user is already authenticated with a valid session which has a level strong enough, accessing resources protected by other Federation Schemes might not result in a new Federation SSO

OAM Administration Console

To create an OAM Authentication Scheme for a specific IdP Partner, execute 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 for which you want to create the scheme
  • Click on the "Create Authentication Scheme and Module" button

The OAM Administration Console will create:

  • An OAM Authentication Module bound to this IdP Partner named <PARTNER_NAME>FederationPlugin
  • An OAM Authentication Scheme bound to the newly created OAM Authentication Module named <PARTNER_NAME>FederationScheme

WLST Command

To create an OAM Authentication Scheme for a specific IdP Partner using the OIF WLST createAuthnSchemeAndModule() command, 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()
  • Execute the createAuthnSchemeAndModule() command
    • Specify the IdP Partner Name
    • An example would be:
      createAuthnSchemeAndModule("AcmeIdP")
  • Exit the WLST environment:
    exit()

Note: to delete such a Federation Scheme/Module, execute the OIF WLST deleteAuthnSchemeAndModule() command.

Protecting a Resource

To protect a resource with a <PARTNER_NAME>FederationScheme that will trigger Federation SSO with that specific IdP Partner, , execute the following steps:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Access Manager -> Application Domain
  • Click Search and open the Application Domain containing the resources you wish to protect with the new FederationScheme
  • Click on the Authentication Policies tab
  • Create a new Authentication Policy or edit an existing one
  • Select the new FederationScheme
  • Apply

After this change, whenever a user requests resources protected by this Authentication Policy and that the user needs to be authenticated, then a Federation SSO will be executed with the specific IdP Partner (AcmeIdP in this example).

Custom OAM Authentication Plugin


Overview

An OAM Authentication Module is:

  • A collection of Authentication Plugins
  • An orchestration determining the order of the execution of the plugins

The OOTB Federation Authentication Module, called FederationPlugin, is made of two plugins:

  • FedAuthnRequestPlugin: starts the Federation SSO flow, determines which IdP to use, creates an SSO request and redirects the user to the IdP
  • AssertionProcessing: processes an incoming SAML/OpenID SSO Response and maps the message to a local user record in the LDAP directory

The orchestration can be seen by:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Access Manager -> Authentication Modules
  • Open FederationScheme
  • Click on the Steps tab to see the plugins
  • Click on the Steps Orchestration tab to see the orchestration between the different plugins, and the plugin that will be used to start the operation

Implementing a Custom Plugin

A custom plugin can be implemented based on the OAM Custom Authentication Plugin framework that will determine the IdP to be used for a specific Federation SSO operation:

  • The plugin will determine which IdP needs to be used via a specific approach (cookie, user selection via a page, programmatic...)
  • Once the selection is done, the plugin will need to save the IdP Partner name in Credential instance that will be saved into the AuthenticationContext
  • The plugin would return a success status
  • OAM would invoke the next plugin (FedAuthnRequestPlugin) which would retrieve the IdP Partner Name from the AuthenticationContext
  • The Federation SSO would be started with that IdP

The code to save the IdP Partner name in the AuthenticationContext would be similar to:

public ExecutionStatus process(AuthenticationContext context)
{
   ...
   CredentialParam param = new CredentialParam();
   param.setName("KEY_FEDIDP");
   param.setType("string");
   param.setValue(IDP_PARTNER_NAME);
   context.getCredential().addCredentialParam("KEY_FEDIDP", param);
   ...
   return ExecutionStatus.SUCCESS;
}

Once that plugin is implemented:

  • It will need to be packaged, uploaded, distributed and activated
  • A new Authentication Module will need to be created with three plugins
    • The custom plugin
    • FedAuthnRequestPlugin
    • AssertionProcessing
  • The orchestration will need to be set with:
    • The custom plugin being the Initial Step
    • Custom Plugin:
      • On Success, FedAuthnRequestPlugin should be invoked
      • On Failure, failure should be returned
      • On Error, failure should be returned
    • FedAuthnRequestPlugin :
      • On Success, success should be returned
      • On Failure, AssertionProcessing should be invoked
      • On Error, failure should be returned
    • Custom Plugin:
      • On Success, success should be returned
      • On Failure, failure should be returned
      • On Error, failure should be returned
  • A new OAM Authentication Scheme should be created, using the new OAM Authentication Module. The new scheme should be similar to the OOTB FederationScheme

Finally, resources can now be protected using the new OAM Scheme that will use the custom Authentication Module/Plugins to perform the Federation SSO operation.

Note: see more information about custom plugins in the OAM Developer's guide.

IdP Discovery Service


Overview

The "Identity Provider Discovery Service Protocol and Profile" SAML 2.0 specification defines a way for SAML 2.0 SPs to delegate the IdP selection to a remote service.

The flow is described in the SAML 2.0 specification and is made of the following steps:

  • SP is configured to use a remote IdP Discovery Service to determine the IdP to be used for the Federation SSO operation
  • The SP redirects the user to the IdP Discovery Service via a 302 HTTP redirect and provides the following parameters in the query string
    • entityID: the Issuer/ProviderID of OIF/SP
    • returnIDParam: the name of the query string parameter that the service needs to use for the parameter containing the IdP ProviderID value, when redirecting the user back to OIF/SP
    • return: the URL to use to redirect the user to OIF/SP
  • The service determines the IdP to use
  • The service redirects the user to OIF/SP via a 302 HTTP redirect based on the query parameter "return" specified by the SP and provides the following parameters in the query string
  • A query parameter containing the the IdP ProviderID value; the name of that query parameter is specified by the SP in the returnIDParam query parameter.

Configuring OIF/SP

OIF/SP can be configured to use any remote IdP Discovery Service.

Also, OIF includes a simple IdP Discovery Service that can be used and that lets user choose which IdP to perform Federation SSO with.

To configure OIF/SP to use an IdP Discovery Service, 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()
  • Enable/disable OIF/SP to use an IdP Discovery Service:
    putBooleanProperty("/spglobal/idpdiscoveryserviceenabled", "true/false")
    • To enable:
      putBooleanProperty("/spglobal/idpdiscoveryserviceenabled", "true")
    • To disable
      putBooleanProperty("/spglobal/idpdiscoveryserviceenabled", "false")
  • Set the location of the remote IdP Discovery Service:
    putStringProperty("/spglobal/idpdiscoveryserviceurl", "URL")
    • Replace URL by the location of the service
    • For the bundled simple IdP Discovery Service, replace URL by /oamfed/discovery.jsp (this is the OOTB value for this property):
      putStringProperty("/spglobal/idpdiscoveryserviceurl", "/oamfed/discovery.jsp")
    • For a remote service, an example would be:
      putStringProperty("/spglobal/idpdiscoveryserviceurl", "http://sp.com/discovery")
  • Exit the WLST environment:
    exit()

To use the bundled simple IdP Discovery Service, 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()
  • Enable/disable the bundled IdP Discovery Service:
    putBooleanProperty("/spglobal/idpdiscoveryservicepageenabled", "true/false")
    • To enable:
      putBooleanProperty("/spglobal/idpdiscoveryservicepageenabled", "true")
    • To disable
      putBooleanProperty("/spglobal/idpdiscoveryservicepageenabled", "false")
  • Exit the WLST environment:
    exit()

Test

In my test environment, I have three IdPs:

  • AcmeIdP: SAML 2.0 IdP
  • Google: the Google OpenID OP
  • Yahoo: the Yahoo OpenID OP

OIF/SP has been configured to:

  • Use an IdP Discovery Service
  • Redirect the user to the bundled simple IdP Discovery Service
  • Have the  bundled simple IdP Discovery Service enabled

If the user requests access to a resource protected by the FederationScheme, the bundled simple IdP Discovery Service will prompt the user to select an IdP to perform Federation SSO with:

Default SSO Identity Provider


If none of the previous methods were used to indicate which IdP to be used for Federation SSO, OIF/SP will use the IdP Partner that was marked as the Default SSO Identity Provider.

OAM Administration Console

To indicate that a specific IdP Partner should be the Default SSO Identity Provider 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
  • Check the "Default Identity Provider Partner" box
  • Apply

WLST Command

To indicate that a specific IdP Partner should be the Default SSO Identity Provider using the OIF WLST setDefaultSSOIdPPartner() 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 setDefaultSSOIdPPartner() command
    • Specify the IdP Partner Name
    • An example would be:
      setDefaultSSOIdPPartner("AcmeIdP")
  • Exit the WLST environment:
    exit()


In the next article, I will create a custom authentication plugin in OIF/SP that will be invoked after a Federation SSO operation and will process Assertion data.
Cheers,
Damien Carru

Join the discussion

Comments ( 6 )
  • guest Tuesday, February 2, 2016

    Hi,

    How can we setup a deep linking with OAM as an IDP..

    So that if user hits a url such as

    https://sp.com/idp_id/page.aspx?returnUrl=https://sp.com/index1.jsp

    it will take user to https://sp.com/index1.jsp after authentication instead of the assertion URL

    Thanks


  • Damien Monday, February 29, 2016

    Hi,

    I think there is a problem with the SP's implementation: after OAM/IdP authenticates the user and redirects the user to the SP's Assertion Consumer Service URL with the SAML Assertion, the SP needs to determine what to do (i.e.: redirect the user somewhere else).

    Either the IdP needs to have a default redirect URL, or the SP needs to use the SAML 2.0 Relay State parameter during the Federation SSO operation.

    Regards,

    Damien


  • Suresh Tuesday, June 21, 2016

    Hi Damien,

    Can we set a Relaystate parameter for SP Partners in OAM/IdP?

    Appreciate your response.

    Thanks,

    Suresh


  • Poorani Friday, August 12, 2016

    Where multiple URLs(MyIT, application saml URL) can be configured on Assertion consumer field at OAM end?


  • Damien Wednesday, November 30, 2016

    Hi Suresh,

    You can set a default Relay State in OAM/IdP for SP partners: this would only be used in IdP initiated SSO flows, when no return URL query parameter was specified on the /oamfed/idp/initiatesso endpoint.

    To do so, use the WLST command to set the providerrelaystate string property for the SP partner

    updatePartnerProperty("AcmeSP", "sp", "providerrelaystate", "fooo", "string")

    Damien


  • Damien Wednesday, November 30, 2016

    Hi Poorani,

    Can you clarify your use case, so I get the picture?

    Damien


Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.