How to setup and configure SSO with SPNEGO in BPM

Follow

Introduction:

Implementing Single Sign On (SSO) should be relatively simple, but there are a number of areas that can cause problems.  This article attempts to explain more details on the process and each of the components.

This article is intended for BPM version 8.x.

High level steps:

  • Active Directory/LDAP should be implemented on the Websphere cluster.
  • Generate a keytab file.
  • Move the keytab file to the web server you will be implementing SSO on.
  • Start the Websphere Admin console and create the Kerberos config file
  • Configure the WAS console to enable SSO
  • Restart the environment

Information Gathering:

There are several parameters that are needed to properly setup SSO.  To that end, here are the key values and how to find them:

  • Domain name:
    • From the server you will be setting up SSO on, run the following:
    • Windows:
      • From a command prompt: net config workstation
      • Look for "Workstation Domain DNS name"
    • UNIX:
      • From a command prompt: dnsdomainname
  • Kerberos Realm name:
    • From the server you will be setting up SSO on, run the following:
      • klist
    • This will display the currently cached Kerberos tickets and you should look for a "Server" entry.  The format is:
      • Server: <PROTOCOL>/<DNS name of server> @ <KRB DOMAIN NAME>
  • FQDN of BPM host:
    • echo %COMPUTERNAME%.%USERDNSDOMAIN%
  • Service account user:
    • Coordinate this with your Active Directory Administrator
  • Service account password:
    • Coordinate this with your Active Directory Administrator
  • Path to config file:
    • You will choose this path when you run the wsadmin command to create the Kerberos config file.
  • Path to keytab file:
    • You will choose this when you generate the keytab file with the ktpass command.

VALUES TO DETERMINE:

  • Domain name: __________________________
  • Kerberos Realm name: ____________________
  • FQDN of BPM host: _______________________
  • Service account user: _____________________
  • Service account password: _________________
  • Path to config file: ________________________
  • Path to keytab file: _______________________

Details Steps:

  • NOTE: If this is a clustered environment, please pay attention to the next section entitled Configuring SSO in Clustered Environments

Create service account(s). - Must be done by AD administrator.

On a domain controller, create a new Active Directory user, which is used to map to the Kerberos service principal name (SPN) for IBM WebSphere Application server.

  1. On the domain controller, navigate to Start > Administrative Tools > Active Directory Users and Computers.
  2. Make sure the following are set for the new service account:
    1. Disable account expiration
    2. Disable password expiration
    3. Uncheck all other items under Account Options tab
    4. Make sure “Use DES encryption types” is unchecked (DES encryption is disabled by default on Win 2003 and higher, HMAC encryption type will be used)

Generate a keytab file. - Must be done by AD administrator.

Generating the keytab needs to be performed by someone with administrative privileges on the AD forest.

NOTE: If the parameters in this command are not 100% correct then it is very likely you will experience issues later in the process and the root cause will not be apparent.  Please be careful and document precisely what you did in case you need to try again.  This will avoid repeated mistakes/misunderstandings.

First, the general format of the command:

ktpass

-out <KEYTAB_FILE_NAME>

-princ HTTP/<FQDN_BPM_HOST>@<KERBEROS_REALM>

-mapuser <DOMAIN>\<USER>

-mapop set -pass <PASSWORD>

-crypto RC4-HMAC-NT

-ptype KRB5_NT_PRINCIPAL

And here's an example of such a command:

ktpass -out C:\temp\myfile.keytab -princ HTTP/BPMSVR1.bp3.com@BP3.COM -mapuser bp3.com\sa-bpmsso -mapop set -pass passwd1234 -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL

NOTES:

    • On Windows 2008 servers the switches above are denoted using a slash "/" instead of a dash "-".
    • The Kerberos Realm name is case sensitive.
    • Most of the time, the Kerberos Realm name is the same as the domain name in all CAPITAL letters.  For example, if the domain name is bp3.com, the Kerberos Realm would BP3.COM.

Active Directory/LDAP should be implemented on the Websphere cluster.

This should have been previously completed.  To check:

  1. Login to the WAS console
  2. Expand Security -> Global Security
  3. Click Configure next to the Available realm definitions
  4. This should list the Federated repositories that you have and one of them should be Repository Type LDAP:AD

Move the keytab file to the WebSphere server you will be implementing SSO on.

You can put the file wherever you like, but we recommend putting the file under the BPM installation folder:

  • .../IBM/WebSphere/AppServer/keytab/myfile.keytab

Or in our case:

  • C:\IBM\WebSphere\AppServer\keytab\myfile.keytab

Verify the Service Principal Name (SPN)

Run the following command:

  • setspn -L <USER>

Where the user is the same users as you specified in the ktpass command:

  • setspn -L sa-bpmsso

This should result in showing you the registered SPNs for the user specified and you want to ensure the principal you specified in the ktpass command is listed.  For example:

C:\Users\drosen> setspn -L sa-bpmsso

Registered ServicePrincipalNames for CN=SA-BPMSSO,OU=Automation Accounts,OU=All Corp,DC=BP3,DC=COM:

HTTP/BPMSVR1.bp3.com


Start the Websphere Admin console and create the Kerberos config file

Once you have the keytab file on the WebSphere server, you can generate the Kerberos config file.

  • First, open a command prompt on the Websphere server you are setting SSO up on.
  • Change Directory: cd .../IBM/WebSphere/AppServer/bin
  • Now start the WebSphere Admin console command prompt: wsadmin.bat(.sh)
    • You will be prompted for credentials.  Any user with administrative priviledges on the Websphere server should work.  You should also see:

WASX7209I: Connected to process "dmgr" on node BPMSVR101CellManager01 using SOAP connector; The type of process is: DeploymentManagerWASX7029I: For help, enter: "$Help help"wsadmin>

  • This prompt means you are ready to issue wsadmin commands.
  • Run the command to create the file:
    • NOTES:
      • The DNS entry is the dns name of the target environment.  If the environment is a cluster and the nodes are load balanced, then put in the DNS alias of the load balanced URL
      • The AD Domain controller, in some cases, can be a top level domain alias that is serving to distribute requests to other domain controllers.  This helps when you upgrade, add or retire domain controllers.
    • General form:

$AdminTask createKrbConfigFile

{-krbPath <KERBEROS CONFIG TO CREATE>

-realm <KERBEROS REALM>

-kdcHost <AD DOMAIN CONTROLLER>

-dns <DNS OF TARGET ENV>

-keytabPath <KEYTAB FILE>}

    • Example:

$AdminTask createKrbConfigFile {-krbPath C:\IBM\WebSphere\AppServer\Kerberos\BPMSVR01.config -realm BP3.COM -kdcHost bp3.com -dns BPMSVR1.bp3.com -keytabPath C:\IBM\WebSphere\AppServer\keytab\myfile.keytab}

  • This should put a file in the proper location specified.  In our case, the file is at C:\IBM\WebSphere\AppServer\Kerberos\BPMSVR01.config and the contents should look like this:

[libdefaults]

default_realm = BP3.COM

default_keytab_name = FILE:C:\IBM\WebSphere\AppServer\keytab\myfile.keytab

default_tkt_enctypes = rc4-hmac des-cbc-md5

default_tgs_enctypes = rc4-hmac des-cbc-md5

forwardable = true

renewable = true

noaddress = true

clockskew = 300

[realms]

BP3.COM = {

kdc = bp3.com:88

default_domain = BPMSVR1.bp3.com

}

[domain_realm]

.BPMSVR1.bp3.com = BP3.COM

 

Configure the WAS console to enable SSO

  • Open the WAS admin console: https://BPMSVR01.bp3.com:9043/ibm/console/logon.jsp
  • Enable SSO: navigate to Security -> Global Security -> Web and SIP Security -> Single sign-on (SSO)
    • Check the Enabled box
    • Enter the domain name: bp3.com
    • Click Apply
    • Click Save
  • Create the SPNEGO Filter: navigate to Security -> Global Security -> Web and SIP Security ->SPNEGO Web Authentication
    • Click New in the SPNEGO Filters Table
    • Set FQDN for the Host name: BPMSVR1.bp3.com
    • Set Kerberos realm name: BP3.COM
    • Set Filter criteria: request-url^=portal|ProcessPortal|ProcessCenter|ProcessAdmin|teamworks|rest
    • Check the box for Trim Kerberos realm from principal name
    • Uncheck the box for Enable delegation of Kerberos credentials
    • Click Apply
    • Click Save
  • Enable SPNEGO Web Authentication: navigate to Security -> Global Security -> Web and SIP Security ->SPNEGO Web Authentication
    • Check the box for Use the alias host name for the application server
    • Check the box for Dynamically update SPNEGO
    • Check the box for Enable SPNEGO
    • Check the box for Allow fall back to application authentication mechanism
    • Set the paths for the following:
      • Kerberos configuration file with full path: C:\IBM\WebSphere\AppServer\Kerberos\BPMSVR01.config
      • Kerberos keytab file name with full path: C:\IBM\WebSphere\AppServer\keytab\myfile.keytab
    • Click Apply
    • Click Save


Restart the environment

At this point, you should restart the entire environment.  There are numerous ways to do this, we leave that up to your environment as to which method best suits your needs.

Configuring SSO in Clustered Environments

First, there are several considerations when looking at a clustered environment installation.  In most cases, this will involve a web server or load balancer (or both).  The following article is a more in-depth look at those scenarios:

In addition to the configuration outlined previously, the following steps must be taken to successfully configure SSO in a clustered BPM environment:

  • A separate LDAP account must be created for each node. For a two-node cluster, there should be two user accounts created. For example, sa-bpmsso-n01 and sa-bpmsso-n02.
  • A separate keytab file must be created for each node in the cluster.
  • All keytab files within the node should be merged using the following command:
    (BPM_Installer_Home)/was-iip-jdk/jre/bin/ktab -m <keytab file1> <keytab file2>

This command will merge both keytab files into <keytab file2>

  1. Copy the merged keytab file to the same location on all nodes.
  2. Copy the krb5.ini file to the same location on both all nodes.
  3. From the WebSphere Application Server Administrative console, create a new SPNEGO filter for each additional node.
  4. Save and synchronize the changes manually for all nodes.

Client Side configuration

Microsoft Internet Explorer:

The following steps are required to allow Internet Explorer to log a user in using single sign-on (SSO):

  1. In Internet Explorer, go to Tools->Internet Options->Security->Local intranet->Sites->Advanced option and add the FQDN of the WebSphere Lombardi Edition server.
  2. Go to the Tools->Internet Options->Advanced tab and ensure that the Enable Integrated Windows Authentication option under the Security section is selected.
  3. Close and re-open the browser.
  4. Navigate to the WebSphere Lombardi Edition server and ensure that single sign-on is working.


Mozilla Firefox

The following steps are required to allow Mozilla Firefox to log a user in using single sign-on (SSO):

  1. In Firefox, enter about:config in the browser address field.
  2. Type network.n in the filter field.
  3. Double-click the preference network.negotiate-auth.trusted-uris and add the host names in a comma-delimited string to enable SPNEGO authentication, for example: http://sso-pcs.wlessotest.com,http://sso-ps.wlessotest.com
  4. Click OK.
  5. If the SPNEGO solution uses the advanced Kerberos feature of credential delegation, double-click network.negotiate-auth.delegation-uris to list the sites for which the browser can delegate user authorization to the WebSphere Lombardi Edition server, for example: http://sso-pcs.wlessotest.com,http://sso-ps.wlessotest.com
  6. Click OK.
  7. Click OK and the configuration displays as updated.
  8. Restart the Firefox browser to activate this configuration and ensure that single sign-on is working.

Troubleshooting references:

The following are a few additional articles to help troubleshoot SSO implementation issues:

Have more questions? Submit a request

Comments

Powered by Zendesk