How to configure Foglight with Windows Single Sign-On (SSO) (4262359)

How to configure Foglight with windows Single Sign-On (SSO)?

Summary of the steps that need to be accomplished

All the following steps needs to be performed having a remote session on Foglight (Foglight the Management Server):

1. Identify the Active Directory "Service Account" to use and add in it's attributes in Active Directory under "servicePrincipalName" the URL of the Foglight Management Server.

   Note: the following is one example:  HTTP/fmshost.example.com.  It should be changed for the actual URL of your Foglight with the Fully Qualified domain name.

   After you checked above configuration, please generate the keytab file.

2. In Foglight, enable Windows SSO by configuring FMS_HOME\config\krb5-auth and FMS_HOME\config\krb5.config according to our guidelines. 
3. Configure the Web Browser to support Windows SSO.

Please check below information on how to complete the configuration.

Details on how to accomplish the configuration

Step 1: Configure Active Directory to support Windows Single Sign-on

Microsoft Active Directory provides a directory service supporting the Lightweight Directory Access Protocol (LDAP), and a Kerberos KDC (key distribution center) to authenticate users. It allows organizations to share and manage information about users and network resources. When properly configured, Active Directory provides an SSO environment that can be integrated with the standard Windows OS desktop login.

When setting up the Kerberos Service Principal Name (SPN), use the following instructions to create mappings between the user account and SPNs, and to create a keytab file to configure in krb5‑auth.config. For example:

ktpass -princ HTTP/fmshost.example.com@EXAMPLE.COM -mapuser [user] -pass [password] -out [keytabFilePath]

Some Kerberos encryption types (E.g. RC4-HMAC) have been disabled by default in Java versions included with newer Foglight releases; the ktpass command can be used with the -crypto parameter to specify the encryption type; for example using AES256-SHA1:

ktpass -princ HTTP/fmshost.example.com@EXAMPLE.COM -mapuser [user] -pass [password] -ptype KRB5_NT_PRINCIPAL -crypto AES256-SHA1 -out [keytabFilePath]

And use setspn to set up the mapping for just the host name. For example:

setspn -A HTTP/fmshost [user] 

NOTES: 

• Duplicate SPNs cause Kerberos authentication to return an NTLM token and fallback to Form authentication. To search for duplicate SPNs use the command setspn -X -F
• Ensure the realm is in uppercase when setting the -princ parameter in the ktpass command as in the examples: HTTP/fmshost.example.com@EXAMPLE.COM
• If you locate duplicate SPNs for "HTTP/fmshost", you can remove them with the command setspn -d HTTP/fmshost.example.com [user]
• To list the SPNs that are registered for a user use setspn -l [user]
• To query SPNs that are registered in one or multiple objects use setspn -Q HTTP/fmshost*
• If the account password changes the keytab file will need to be recreated
• The account option "This account supports Kerberos AES 256 bit encryption" may need to be enabled for the mapped domain account when using AES256-SHA1 as the encryption type

Step 2: Configure Foglight to support Windows Single Sign-On

Foglight provides SSO for the Management Server using Active Directory as its identity store. It includes an enterprise-wide method of identification and authorization that can be administered in a consistent and transparent manner. This method allows users to access only those Management Server components for which they are authorized.

Enabling the Windows SSO feature in Foglight requires the configuration of the following files under [FMS_HOME]/config directory:

• krb5-auth.config
  • Principal: The Active Directory service principal.
  • Keytab: The keytab file of the service principal specified above.
  • Krb5ConfigFilePath: Location of the Kerberos configuration file.

  Example of main parameters in the configuration file:

  Krb5ConfigFilePath = "./config/krb5.config";
  Principal = "HTTP/fmshost.example.com";
  Keytab = "./config/krb5.keytab";
  

  For details on other configuration parameters refer to "Table 1. Properties requiring configuration for SSO in Foglight." in section "Configure Windows Single Sign-on" of the Foglight - Administration and Configuration Guide.

• krb5.config

  The krb5.config file contains standard Kerberos configuration information. See the following URL for detailed information about the settings:

  http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html

  Here are a simple krb5.config (Windows domain is EXAMPLE.COM and domain controller is host1.example.com)

  [libdefaults]
          default_realm = EXAMPLE.COM
   
  # The Management Server will use the first kdc in the realm as an LDAP server 
  # to retrieve user group information. Use the "LDAPURLOverrides" element in 
  # krb5-auth.config to override this behaviour.
  [realms]
          EXAMPLE.COM = {
                  kdc = host1.example.com
          }
   
  [domain_realm]
          .example.com = EXAMPLE.COM

Step 3: Configure your web browser to support Windows Single Sign-on

Most web browsers include extensions that allow Foglight users to participate in a Kerberos-based single sign-on (SSO) environment. This environment relies on the SPNEGO (Simple and Protected GSS-API Negotiation Mechanism) authentication mechanism. To enable this feature, configure your web browser to support SPNEGO authentication.

Only Microsoft Internet Explorer, Google Chrome™, and Mozilla Firefox browsers can be configured to support SPNEGO authentication currently.

To configure Internet Explorer to enable SPNEGO authentication:

1. Log in to your Windows Active Directory domain.
2. Start Internet Explorer.
3. From the Tools menu, navigate to Internet Options > Advanced > Security.
4. Scroll down to the Security section. Select the option: Enable Integrated Windows Authentication (requires restart).
5. From the Tools menu, select Internet Options > Security > Local Intranet > Sites > Advanced.
6. Add one of the following:
   • An entry for the application server.
   • A list entry that globally includes the domain of the application server. For example: http://*.example.com
7. Select Local Intranet > Custom Level.
8. Select the Security Settings > User Authentication option for Automatic logon only in Internet Zone option.
9. Restart Internet Explorer.

To configure Chrome to enable SPNEGO authentication on a machine running a Windows OS:

For complete details, see the Chrome documentation at: http://www.chromium.org/developers/design-documents/http-authentication.

1. From the Start menu, open the Control Panel.
2. Select Internet Options.
3. Select the Security tab.
4. Click Local Intranet > Sites > Advanced.
5. Type the domain of the application server in the box (for example: "*.example.com"), and click Add.
6. Click OK to close all the dialog boxes.

To configure Chrome to enable SPNEGO authentication on a machine running Linux or Chromium:

For complete details, see the Chrome documentation at: http://www.chromium.org/developers/design-documents/http-authentication.

Customize the launcher for your desktop.

Add the following parameter to the command-line:

--auth-server-whitelist=".example.com"

Where .example.com is the domain of the application server.

To configure Firefox to enable SPNEGO authentication:

For complete details, see the Firefox documentation at https://developer.mozilla.org/en-US/docs/Integrated_Authentication.

1. Log in to your Windows Active Directory domain.
2. Start Firefox.
3. In the address bar of a blank tab, type about:config.
4. If prompted, click "I'll be careful, I promise!".

   A list of entries appears in the Firefox window.

5. In the Filter field, type: negotiate. Locate the entry network.negotiate‑auth.trusted‑uris. This entry is used to configure the sites that are permitted to engage in SPNEGO authentication with Firefox.
6. Double click network.negotiate‑auth.trusted‑uris.
7. In the dialog box that opens, type the URL that you use to access the Foglight browser interface (for example: "yourdomain.com").
8. Click OK to close the dialog box, and restart Firefox to enable the new configuration.

Step 4: Connect to Foglight

Once everything is configured, connect with one user to Foglight. The user will be imported from the AD, but the connection will be rejected. Connect to Foglight with an administration user and open the "User Management" dashboard. On the "Groups" make sure the AD groups are imported with the distinguish name (group@domain). Assign the group to the first user and let the user connect to the Foglight now.

After the first authentication via AD has been done the AD groups are fully initialized and further users will be able to connect using SSO.

If you do not have access to Active Directory, you can check the "Service Account" settings using Microsoft third party tool "AD Explorer":

1. Once you open ADExplorer, you will see "Connect to Active Directory" window, please leave in blank and click "OK"
2. On the upper menu and click on Search │ Search Container
   
   Set the following options: 
   
   Class: -- Common classes --
   Attibute: sAMAccountName
   Relation: is
   Value: username
   
   

   Note: "username" is the service account username you are using for this configuration within Foglight.

3. Click "Add" and then "Search", at bottom of that window you can double click on the search result.
4. Do a search for "servicePrincipalName", open it up and see if the Foglight URL is entered.

Download AD Explorer