Determining which IdP to use for Federation SSO

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

OAM/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

The following section explores each mechanism in detail.

OAM Federation Scheme

OAM 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 results in a Federation SSO with specific IdP Partners.

Note: If the user is already authenticated with a valid session that 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:

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 for which you want to create the scheme.

4. Click on the Create Authentication Scheme and Module button.

Description of the illustration OAM_Admin_Console.jpg

The OAM Administration Console creates:

• 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.

Description of the illustration OAM_Admin_Console_with_message.jpg

WLST Command

To create an OAM Authentication Scheme for a specific IdP Partner using the OAM WLST createAuthnSchemeAndModule() command, execute 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 createAuthnSchemeAndModule() command: Specify the IdP Partner Name An example is: createAuthnSchemeAndModule("AcmeIdP").

5. Exit the WLST environment: exit().

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

Protecting a Resource

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

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole.

2. Navigate to Access Manager , Application Domain.

3. Click Search and open the Application Domain containing the resources you wish to protect with the new FederationScheme.

4. Click on the Authentication Policies tab.

5. Create a new Authentication Policy or edit an existing one.

6. Select the new FederationScheme.

7. Click Apply.

Description of the illustration Authentication_Policies.jpg

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

Custom OAM Authentication Plug

Overview

An OAM Authentication Module is:

• A collection of Authentication Plugins

• An orchestration that 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:

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole.

2. Navigate to Access Manager , Authentication Modules.

3. Open FederationScheme.

4. Click on the steps tab to see the plugins.

5. Click on the Steps Orchestration tab to see the orchestration between the different plugins, and the plugin that is used to start the operation.

Description of the illustration Steps_Orchestration.jpg

Implementing a Custom Plugin

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

• The plugin determines which IdP needs to be used via a specific approach (cookie, user selection via a page, programmatic…)

• After the selection is done, the plugin needs to save the IdP Partner name in Credential instance that is saved into the AuthenticationContext

• The plugin returns a success status

• OAM invokes the next plugin (FedAuthnRequestPlugin) which retrieves the IdP Partner Name from the AuthenticationContext

• The Federation SSO is started with that IdP

The code to save the IdP Partner name in the AuthenticationContext is 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;
 }

After the plugin is implemented:

• It needs to be packaged, uploaded, distributed and activated

• A new Authentication Module needs to be created with three plugins

  • The custom plugin

  • FedAuthnRequestPlugin

  • AssertionProcessing

• The orchestration needs to be set with:

  • The custom plugin being the Initial Step Custom Plugin:

    • On Success, FedAuthnRequestPlugin is invoked

    • On Failure, failure is returned On Error

  • 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, you can protect resources by using the new OAM Scheme, which uses 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 OAM/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 OAM/SP

  • return: The URL to use to redirect the user to OAM/SP

• The service determines the IdP to use

  • The service redirects the user to OAM/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 OAM/SP

You can configure OAM/SP to use any remote IdP Discovery Service. OAM includes a simple IdP Discovery Service that is used and lets user to choose which IdP to perform Federation SSO with. To configure OAM/SP to use an IdP Discovery Service, 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. Enable/disable OAM/SP to use an IdP Discovery Service: putBooleanProperty("/spglobal /idpdiscoveryserviceenabled", "true/false").

   1. To enable: putBooleanProperty("/spglobal /idpdiscoveryserviceenabled", "true")

   2. To disable putBooleanProperty("/spglobal /idpdiscoveryserviceenabled", "false")

5. Set the location of the remote IdP Discovery Service: putStringProperty("/spglobal /idpdiscoveryserviceurl", "URL").

6. Replace URL by the location of the service.

   1. 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").

   2. For a remote service, an example is: putStringProperty("/spglobal /idpdiscoveryserviceurl", "http://sp.com/discovery").

7. Exit the WLST environment: exit().

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

   1. To enable: putBooleanProperty("/spglobal /idpdiscoveryservicepageenabled", "true").

   2. To disable putBooleanProperty("/spglobal /idpdiscoveryservicepageenabled", "false").

5. 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

OAM/SP is 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 prompts the user to select an IdP to perform Federation SSO with:

Description of the illustration Access_Manager.jpg

Default SSO Identity Provider

If none of the previous methods are used to indicate which IdP to be used for Federation SSO, OAM/SP uses 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:

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.

4. Check the Default Identity Provider Partner box.

5. Click Apply.

Description of the illustration Default_Identity_Provider.jpg

WLST Command

To indicate a specific IdP Partner should be the Default SSO Identity Provider using the OAM WLST setDefaultSSOIdPPartner() 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 setDefaultSSOIdPPartner() command.

5. Specify the IdP Partner Name An example is: setDefaultSSOIdPPartner("AcmeIdP").

6. Exit the WLST environment: exit().

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

Determining which IdP to use for Federation

F60233-01

September 2022

Copyright © 2022, Oracle and/or its affiliates.