19 Configuring Single Sign-On for an Enterprise Deployment

You need to configure the Oracle HTTP Server WebGate in order to enable single sign-on with Oracle Access Manager.

About Oracle Webgate

Oracle WebGate is a web server plug-in that intercepts HTTP requests and forwards them to an existing Oracle Access Manager instance for authentication and authorization.

Oracle WebGate software is installed as part of the Oracle HTTP Server software installation. See Registering and Managing OAM Agents in Adminstrator’s Guide for Oracle Access Management. Oracle WebGate is available for Oracle HTTP Server.

General Prerequisites for Configuring Oracle HTTP Server WebGate

Before you can configure Oracle HTTP Server WebGate, you must have installed and configured a certified version of Oracle Access Manager.

For the most up-to-date information, see the certification document for your release on the Oracle Fusion Middleware Supported System Configurations page.

For WebGate certification matrix, click and open Certification Matrix for 14c Access Management WebGates.

Note:

It is required that you use the WebGate version that is certified with your Oracle Access Manager deployment.

For more information about Oracle Access Manager, see the latest Oracle Identity and Access Management documentation, which you can find in the Middleware documentation on the Oracle Help Center.

Configuring Oracle HTTP Server WebGate for an Enterprise Deployment

You need to configure Oracle HTTP Server WebGate for Oracle Access Manager on both WEBHOST1 and WEBHOST2.

In the following procedure, replace the directory variables, such as WEB_ORACLE_HOME and WEB_CONFIG_DIR, with the values, as defined in File System and Directory Variables Used in This Guide.

  1. Perform a complete backup of the web tier domain.

  2. Change directory to the following location in the Oracle HTTP Server Oracle home:

    cd WEB_ORACLE_HOME/webgate/ohs/tools/deployWebGate/

    For Example:

    cd /u02/oracle/products/ohs/webgate/ohs/tools/deployWebGate
  3. Run the following command to create the WebGate Instance directory and enable WebGate logging on OHS Instance:
    ./deployWebGateInstance.sh -w WEB_CONFIG_DIR -oh WEB_ORACLE_HOME
    For example:
    ./deployWebGateInstance.sh -w /u02/oracle/config/domains/ohsDomain/config/fmwconfig/components/OHS/ohs1 -oh /u02/oracle/products/ohs
  4. Verify that a webgate directory and subdirectories was created by the deployWebGateInstance command:

    ls -lat WEB_ORACLE_HOME/ohs

    For Example:

    ls -lat /u02/oracle/products/ohs/webgate/ohs

    Output

    total 4
    drwxr-x---. 2 oracle oinstall 47 Dec 5 16:29 lib
    drwxr-x---. 2 oracle oinstall 103 Dec 5 16:29 config
    drwxr-x---. 8 oracle oinstall 88 Dec 5 16:29 .
    drwxr-x---. 4 oracle oinstall 40 Dec 5 16:29 tools
    drwxr-x---. 3 oracle oinstall 146 Dec 5 16:29 oamsso-bin
    drwxr-x---. 3 oracle oinstall 39 Dec 5 16:29 oamsso
    drwxr-x---. 29 oracle oinstall 4096 Dec 5 16:29 lang
    drwxr-x---. 3 oracle oinstall 17 Dec 5 16:29 ..
  5. Run the following command to ensure that the LD_LIBRARY_PATH environment variable contains WEB_ORACLE_HOME/lib directory path:

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:WEB_ORACLE_HOME/lib

    For Example:

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/u02/oracle/products/ohs/lib
  6. Change directory to the following directory

    WEB_ORACLE_HOME/webgate/ohs/tools/setup/InstallTools

    For Example:

    cd /u02/oracle/products/ohs/webgate/ohs/tools/setup/InstallTools
  7. Run the following command from the InstallTools directory.
    ./EditHttpConf -w $WEB_CONFIG_DIR -oh $WEB_ORACLE_HOME -o output_file_name
    For example:
    ./EditHttpConf -w /u02/oracle/config/domains/ohsDomain/config/fmwconfig/components/OHS/ohs1 -oh /u02/oracle/products/ohs

    Note:

    The -oh WEB_ORACLE_HOME and -o output_file_name parameters are optional.

    This command:

    • Copies the apache_webgate.template file from the Oracle HTTP Server Oracle home to a new webgate.conf file in the Oracle HTTP Server configuration directory.

    • Updates the httpd.conf file to add one line, so it includes the webgate.conf.

    • Generates a WebGate configuration file. The default name of the file is webgate.conf, but you can use a custom name by using the -o output_file_name argument to the command.

Adding a Load Balancer Certificate to WebGate

Oracle WebGate 14c uses REST calls to interact with Oracle Access Manager 14c. To ensure that the communication works properly, you have to copy the load balancer certificates to WebGate Config and ensure that the REST endpoints are set correctly.

Copying the LoadBalancer Certificates to WebGate Config

WebGate needs to trust your load balancer certificate. To ensure this trust, you should add the load balancer's certificate to the cacert.pem file, which is located in WEB_CONFIG_DIR/webgate/config.

You can obtain the certificate from the load balancer using a browser, such as Firefox. However, the easiest way to obtain the certificate is to use the openssl command. The syntax of the command is as follows:
openssl s_client -connect LOADBALANCER:PORT -showcerts </dev/null 2>/dev/null|openssl x509 -outform PEM > LOADBALANCER.pem
For example:
openssl s_client -connect login.example.com:443 -showcerts </dev/null 2>/dev/null|openssl x509 -outform PEM > login.example.com.pem

This command saves the certificate to a file named login.example.com.pem.

If you do not have load balancer certificates in your WebGate truststore, copy the login.example.com.pem file to WEB_CONFIG_DIR/webgate/config renaming it to cacert.pem.

For example:
cp login.example.com.pem WEB_CONFIG_DIR/webgate/config/cacert.pem

If you already have trusted certificates in WebGate, append the certificate to the cacert.pem file.

For example:
cp login.example.com.pem >> WEB_CONFIG_DIR/webgate/config/cacert.pem

Ensuring that the REST Endpoints are Set Correctly

To ensure that the REST endpoints are set correctly:

  1. Log in to the OAM Console using the URL in URLs Used in This Chapter. Login using the OAM Administration user (oamadmin).
  2. Click Agents.
  3. Click Search.
  4. Locate and click the name of the WebgGate agent from the search results to bring up the edit screen.
  5. Expand the User Properties screen and check that the following parameters are defined correctly:
    • OAMRestEndPointHostName = login.example.com
    • OAMRestEndPointPort = 443
    • OAMServerCommunicationMode = HTTPS

    These values should reflect the login point of your Oracle Access Manager installation. If unsure about these values, contact your OAM administrator.

Copying WebGates Artifacts to Web Tier

When you created your Oracle Access Management installation, a WebGate called Webgate_IDM was created. In order for WebGate to communicate with the Access servers, you must copy the artifacts associated with this WebGate to the web tier.

Copying Generated Artifacts to the Oracle HTTP Server WebGate Instance Location

After you run the idmTool configOAM, it creates a WebGate agent called Webgate_IDM. The process creates a number of artifacts relating to that agent in IAD_ASERVER_HOME/output/Webgate_IDM. These artifacts have to be copied to the Oracle HTTP Server configuration directory on the Web Tier hosts.

The location of the files in the Oracle HTTP Server configuration directory depends on the Oracle Access Manager security mode setting (OPEN or CERT).

The following table lists the required location of each generated artifact in the Oracle HTTP Server configuration directory.

Table 19-1 Web Tier Host Location to Copy the Generated Artifacts

File Location in WEB_CONFIG_DIR
wallet/cwallet.ssoFoot 1 WEB_CONFIG_DIR/webgate/config/wallet/
ObAccessClient.xml WEB_CONFIG_DIR/webgate/config/
password.xml WEB_CONFIG_DIR/webgate/config/
aaa_key.pem WEB_CONFIG_DIR/webgate/config/
aaa_cert.pem WEB_CONFIG_DIR/webgate/config/

Footnote 1 Copy cwallet.sso from the wallet folder and not from the output folder. Even though there are 2 files with the same name they are different. The one in the wallet sub directory is the correct one.

Note:

If you need to redeploy the ObAccessClient.xml to WEBHOST1 and WEBHOST2, delete the cached copy of ObAccessClient.xml and its lock file, ObAccessClient.xml.lck from the servers. The cache location on WEBHOST1 is:
WEB_DOMAIN_HOME/servers/ohs1/cache/
And you must perform the similar step for the second Oracle HTTP Server instance on WEBHOST2:
WEB_DOMAIN_HOME/servers/ohs2/cache/

Obtaining WebGate Artifacts

The easiest way to obtain the WebGate artifacts is to download them from the OAM console. To download, complete the following steps:

  1. Log in to the OAM console using the URL in URLs Used in This Chapter. Login using the OAM Administration user (oamadmin).
  2. Click Agents.
  3. On the Search screen, click Search.
  4. From the list of agents, select Webgate_IDM by clicking on its name.
  5. Download the artifacts using the download button. A zip file gets downloaded on the host machine you are using.

Copy the downloaded zip file to the Oracle HTTP Server machine and unzip it to the WEB_CONFIG_DIR/webgate/config location. The files get extracted to the correct locations.

Restarting the Oracle HTTP Server Instance

Restart the Oracle HTTP Server so the configuration changes take effect.

For information about restarting the Oracle HTTP Server instance, see Restarting Oracle HTTP Server Instances by Using WLST in Administering Oracle HTTP Server.

If you have configured Oracle HTTP Server in a WebLogic Server domain, you can also use Oracle Fusion Middleware Control to restart the Oracle HTTP Server instances. See Restarting Oracle HTTP Server Instances by Using Fusion Middleware Control in Administering Oracle HTTP Server.

Setting Up the WebLogic Server Authentication Providers

To set up the WebLogic Server authentication providers, back up the configuration files, set up the Oracle Access Manager Identity Assertion Provider and set the order of providers.

The following topics assumes that you have already configured the LDAP authenticator by following the steps in Creating a New LDAP Authenticator and Provisioning Enterprise Deployment Users and Group. If you have not already created the LDAP authenticator, then do so before you continue with this section.

Note:

You only need to perform these steps in the IAMGovernanceDomain, they will already have been performed in the IAMAccessDomain as part of running configOAM.

Backing Up the Configuration Files

You should first back up the relevant configuration files to ensure their safety.

Back up the following configuration files:

IAD_ASERVER_HOME/config/config.xml
IAD_ASERVER_HOME/config/fmwconfig/jps-config.xml
IAD_ASERVER_HOME/config/fmwconfig/system-jazn-data.xml

Also back up the boot.properties file for the Administration Server:

IAD_ASERVER_HOME/servers/AdminServer/security/boot.properties

Configuring a New Authenticator for Oracle WebLogic Server

After installing Oracle Identity Management, the Oracle WebLogic Server embedded LDAP server is the default authentication source (identity store). To use a new identity store (for example, OID or OUD), as the main authentication source, you must configure the Oracle WebLogic Server domain to use a new authentication provider to use the new store. For more information, see Security Providers in Oracle WebLogic Remote Console Online Help.

To configure a new authentication provider in Oracle WebLogic Server:
  1. Use WebLogic Remote Console to connect to and manage the WebLogic Server domain through its Administration Server. See Connect to an Administration Server.
  2. In the Edit Tree, go to Security, then Realms, then myrealm, then Authentication Providers.
  3. Click New.
  4. In the Name field, enter OID Provider, or a name of your choosing.
  5. Depending on your back-end LDAP directory, from the Type drop-down list, select OracleInternetDirectoryAuthenticator or OracleUnifiedDirectoryAuthenticator.
  6. From the Control Flag drop-down list, select SUFFICIENT.
  7. Click Create.
  8. On the Configuration page for the new authentication provider, set the values on the Provider-Specific Parameters tab. Specify the settings from the tables below using appropriate values for the identity store you will be using in your environment.

    Table 19-2 OID Authentication Provider Specific Values

    Section Name Field Name Description
    Connection Host

    The LDAP host name. For example, idstore.example.com.

    Connection Port

    The LDAP host listening port number. For example, 1389 or 1636.

    Connection SSL Enabled

    Set to true if you are communicating with your directory over SSL

    Connection Principal

    The LDAP user DN used to connect to the LDAP server.

    For example: cn=oimLDAP,cn=systemids,dc=example,dc=com

    Connection Credential

    The password for the LDAP administrative user entered as the Principal.

    Users User Base DN

    Specifies the DN under which your users start.

    For example: cn=users,dc=example,dc=com

    Users All Users Filter

    The LDAP search filter. For example, (&(uid=*) (objectclass=person)). The asterix (*) filters for all users. Click More Info... for details.

    Users User From Name Filter

    The LDAP search filter. Click More Info... for details.

    Users User Name Attribute

    The attribute that you want to use to authenticate (for example, cn, uid, or mail). Set as the default attribute for user name in the directory server. For example, uid .

    Groups Group Base DN

    Specifies the DN that points to your Groups node.

    For example: cn=groups,dc=example,dc=com

    General GUID attribute

    The attribute used to define object GUIDs in LDAP.

    orclguid

    Note:

    You should not change this default value; in most cases the default value here is sufficient.

    Table 19-3 OUD Authentication Provider Specific Values

    Parameter Sample Value Value Description

    Host

    For example:

    idstore.example.com

    The LDAP server's server ID.

    Port

    For example: 1389 or 1636

    The LDAP server's port number.

    Principal

    For example:

    cn=oimLDAP,cn=systemids,dc=example,dc=com

    Any LDAP user that has ReadOnly access to the users and groups stored in LDAP.

    Credential

    Enter LDAP password.

    The password used to connect to the LDAP server.

    SSL Enabled

    Unchecked (clear)

    Specifies whether SSL protocol is used when connecting to the LDAP server.

    If you select SSL, then you need to ensure that the certificate authority (CA) that issued the certificates for OUD are included in the WebLogic trust store.

    User Base DN

    For example: cn=users,dc=example,dc=com

    Specifies the DN under which your users start.

    All Users Filter

    (&(uid=*)(objectclass=person))

    Instead of a default search criteria for All Users Filter, search all users based on the uid value.

    If the User Name Attribute for the user object class in the LDAP directory structure is a type other than uid, then change that type in the User From Name Filter field.

    For example, if the User Name Attribute type is cn, then this field should be set to:

    (&(cn=*)(objectclass=person)))

    User From Name Filter

    For example:

    (&(uid=%u)(objectclass=person))

    If the User Name Attribute for the user object class in the LDAP directory structure is a type other than uid, then change that type in the settings for the User From Name Filter.

    For example, if the User Name Attribute type is cn, then this field should be set to:

    (&(cn=%u)(objectclass=person))).

    User Name Attribute

    For example: uid

    The attribute of an LDAP user object that specifies the name of the user.

    Use Retrieved User Name as Principal

    Checked

    Must be turned on.

    Group Base DN

    For example: cn=groups,dc=example,dc=com

    Specify the DN that points to your Groups node.

    All Groups Filter

    (&(cn=*)(objectclass=groupOfUniqueNames))

    Specify the group filter.

    GUID Attribute

    entryuuid

    This value is prepopulated with entryuuid when OracleUnifiedDirectoryAuthenticator is used for OUD. Check this value if you are using Oracle Unified Directory as your authentication provider.

    Static Member DN Attribute

    uniquemember

     

    Static Group Name Attribute

    cn

     

    Static Group Object Class

    groupofuniquenames

     

    Static Group DNs from Member DN Filter

    (&(uniquemember=%M)(objectclass=groupofuniquenames))

     

    Dynamic Group Name Attribute

    cn

     

    Dynamic Group Object Class

    groupofURLs

     

    Dynamic Member URL Attribute

    memberURL

     
  9. Click Save.

For more information about configuring authentication providers in Oracle WebLogic Server, see Configuring Authentication Providers in Administering Security for Oracle WebLogic Server.

Perform the following steps to set up the default authenticator for use with the Identity Asserter:
  1. In the Edit Tree, go to Security, then Realms, then myrealm, then Authentication Providers.
  2. Select the default authentication provider (DefaultAuthenticator) to display its configuration page.
  3. On the Common tab, from the Control Flag drop-down list, select SUFFICIENT.
  4. Click Save.
Perform the following steps to reorder Providers:
  1. In the Edit Tree, go to Security, then Realms, then myrealm, then Authentication Providers.
  2. Select a provider name and use the arrow buttons to order the list of providers as follows:
    1. OID Authenticator (SUFFICIENT)
    2. Default Authenticator (SUFFICIENT)
  3. Restart Oracle WebLogic Server.

Setting Up the Oracle Access Manager Identity Assertion Provider

Set up an Oracle Access Manager identity assertion provider in the Oracle WebLogic Server Remote Console.

To set up the Oracle Access Manager identity assertion provider:
  1. Log in to the WebLogic Remote Console, if not already logged in.
  2. In the Edit Tree, navigate to Security > Realms > myrealm > Authentication Providers.
  3. Click New.
  4. In the Name field, enter OAM Provider or a name of your choice.
  5. From the Type drop-down list, select OAMIdentityAsserter.
  6. Set the control flag to REQUIRED.
  7. Click Create.

Updating the Default Authenticator and Setting the Order of Providers

Set the order of identity assertion and authentication providers in the WebLogic Remote Console.

To update the default authenticator and set the order of the providers:
  1. Use WebLogic Remote Console to connect to and manage the WebLogic Server domain through its Administration Server.
  2. In the Edit tree > navigate to Security > Realms > myrealm > Authentication Providers.
  3. Select an authentication provider by selecting the check box.
  4. From the table of providers, click the DefaultAuthenticator.
  5. Set the Control Flag to SUFFICIENT.
  6. Click Save to save the settings.
  7. From the navigation breadcrumbs, click Providers to return to the list of providers.
  8. Click Reorder.
  9. Sort the providers to ensure that the OAM Identity Assertion provider is first and the DefaultAuthenticator provider is last.

    Table 19-4 Sort order

    Sort Order Provider Control Flag

    1

    OAMIdentityAsserter

    REQUIRED

    2

    LDAP Authentication Provider

    SUFFICIENT

    3

    OIMAuthenticationProvider

    SUFFICIENT

    4

    DefaultIdentityAsserter

    N/A

    5

    Trust Service Identity Asserter

    N/A

    6

    DefaultAuthenticator

    SUFFICIENT

  10. Click OK.
  11. Click Activate Changes to propagate the changes.
  12. Shut down the Administration Server, Managed Servers, and any system components, as applicable.
  13. Restart the Administration Server.
  14. If you are going to configure ADF consoles with SSO, you can keep the managed servers down and restart them later. If not, you need to restart managed servers now.
Setting the Default Authenticator

In an Enterprise deployment, your users are stored in an LDAP directory. In order to be able to use the users in the LDAP directory, you must first change the Default Authenticator from REQUIRED to SUFFICIENT.

Use WebLogic Remote Console to connect to and manage the WebLogic Server domain through its Administration Server.

  1. In the Edit Tree, navigate to Security > Realms > myrealm > Authentication Providers.
  2. In the navigation tree, select the Default Authenticator.
  3. Set the Control Flag to SUFFICIENT and click Save.
Ordering the Authentication Providers

The Authentication providers in the domain need to be in the required order to allow SSO integration.

Perform the following steps to set the order of the integration providers:

  1. In the Edit Tree, navigate to Security > Realms > myrealm > Authentication Providers.
  2. In the navigation tree, select the Default Authenticator.
  3. Select an authentication provider and select the check box next to the Authentication provider name.
  4. Click Move Up or Move Down to position the Authenticator in the required position.
  5. Repeat until all the authenticators are in the order shown in Table 19-4.

    Note:

    Ensure that the control flag of each authenticator is as appears in Table 19-4.

Adding the Administration Role to the New Administration Group

The adding of administration role to a new administration group enables all users that belong to the group to be administrators for the domain.

Perform the following steps to assign the administration role using the WebLogic Remote Console:

  1. Log into the WebLogic Remote Console.
  2. In the Security Data tree, navigate to Realms > myrealm > Role Mappers > XACMLRoleMapper > Global > Roles.
  3. Select the Admin role.
  4. Click Add Condition.
  5. From the Predicate List drop-down menu, select Group.
  6. In the Group Argument Name field, enter WLSAdministrators and click OK.

    The WLSAdministrators group is now listed.

  7. Click Save.

Configuring Oracle ADF and OPSS Security with Oracle Access Manager

Some Oracle Fusion Middleware management consoles use Oracle Application Development Framework (Oracle ADF) security, which can integrate with Oracle Access Manager Single Sign-on (SSO). These applications can take advantage of Oracle Platform Security Services (OPSS) SSO for user authentication, but you must first configure the domain-level jps-config.xml file to enable these capabilities.

The domain-level jps-config.xml file is located in the following location after you create an Oracle Fusion Middleware domain:
$IAD_ASERVER_HOME/config/fmwconfig/jps-config.xml

Note:

The domain-level jps-config.xml should not be confused with the jps-config.xml that is deployed with custom applications.

  1. Change to the following directory:
    cd $ORACLE_COMMON_HOME/common/bin
  2. If your WebLogic domain is running in secure mode set the environment variable WLST_PROPERTIES to include the location of your trust store. For example:
    export WLST_PROPERTIES="-Dweblogic.security.TrustKeyStore=CustomTrust -Dweblogic.security.CustomTrustKeyStoreFileName=/u01/oracle/config/keystores/idmTrustStore.p12 -Dweblogic.security.CustomTrustKeyStorePassPhrase=password -Dweblogic.security.SSL.ignoreHostnameVerification=true"
  3. Start the WebLogic Server Scripting Tool (WLST):
    ./wlst.sh

    Note:

    If you are using an SSL enabled Admin Server, you must set the following environment variable before invoking WLST:
    export WLST_PROPERTIES="-Dweblogic.security.TrustKeyStore=CustomTrust -Dweblogic.security.CustomTrustKeyStoreFileName=/u01/oracle/config/keystores/idmTrustStore.p12 -Dweblogic.security.CustomTrustKeyStorePassPhrase=password -Dweblogic.security.SSL.ignoreHostnameVerification=true"
  4. Connect to the Administration Server, by using the following WLST command:
    connect(‘admin_user’,’admin_password’,’admin_url’)

    For example SSL Terminated

    connect('weblogic','Manager1','t3://iadadminvhn.example.com:7001')

    For example End to End SSL

    connect('weblogic','password','t3s://iadadminvhn.example.com:9002')
  5. Run the addOAMSSOProvider command, as shown:
    addOAMSSOProvider(loginuri="/${app.context}/adfAuthentication", logouturi="/oam/logout.html")

    The following table defines the expected value for each argument in the addOAMProvider command.

    Note:

    Perform this action for each domain in your configuration.

    Table 19-5 Expected Values for the Argument in the addOAMProvider command

    Argument Definition

    loginuri

    Specifies the URI of the login page

    Note:

    For ADF security enabled applications, "/context-root/adfAuthentication" should be provided for the 'loginuri' parameter.

    For example:

    /${app.context}/adfAuthentication

    Note:

    ${app.context} must be entered as shown. At runtime, the application replaces the variable appropriately.

    Here is the flow:

    1. User accesses a resource that has been protected by authorization policies in OPSS, fox example.

    2. If the user is not yet authenticated, ADF redirects the user to the URI configured in loginuri.

    3. Access Manager, should have a policy to protect the value in loginuri: for example, "/context-root/adfAuthentication".

    4. When ADF redirects to this URI, Access Manager displays a Login Page (depending on the authentication scheme configured in Access Manager for this URI).

    logouturi

    Specifies the URI of the logout page. The value of the loginurl is usually /oam/logout.html.

    autologinuri

    Specifies the URI of the autologin page. This is an optional parameter.

  6. Disconnect from the Administration Server by entering the following command:
    disconnect()
  7. Restart the Administration Server and the managed servers.