Active Directory

Kerberos protocol

This SSO solution optionally implements the S4U (services for user) extensions from Microsoft that allow enhanced security and user impersonation.

It supports SPNEGO negotiation mechanism.

Refer to the following documents for more information:

• SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows

• [MS-SFU]: Kerberos Protocol Extensions: Service for User and Constrained Delegation Protocol

DNS Protocol

To use successfully the Kerberos protocol, you must observe some requirements regarding the DNS configuration:

• The server running the SSO agent must have a proper hostname that can be resolved to an IP, using DNS.

• You can also modify your /etc/hosts file

• The IP address of the Kerberos KDC is retrieved via DNS, using "_kerberos" service.

• If you cannot configure your DNS server, you must specify the KDC in /etc/krb5.conf.

• The reverse DNS must also work. If not, you must add /etc/krb.conf to disable the reverse DNS:

  [libdefaults]
  
  rdns = false

HAProxy, SPOE protocol, and SSO agent

The SSO agent uses HAProxy's Stream Processing Offload Engine protocol (SPOA).

It requires HAProxy 1.7r2 or greater or 1.8 or greater. The SSO agent is independent from HAProxy and runs as a separate process.

Each HTTP request and response is passed to the SSO agent which checks if the user is allowed to access the requested resource and determines whether to:

• Allow

• Deny

• Present the authentication form

HAProxy headers

Establish an authentication form

This HTML page must contain an HTML form to allow the user to enter his login and password and to select the domain to log on.

The POST action must be able to post on the same URL.

A minimal form could be the following:

<form method="POST">
  <input name="login" />
  <input name="password" />
  <select name="domain">
    <option value="mydomain.net">My Domain</option>
  </select>
  <!-- optional field. It should contain the value extracted from the
  X-SSO-REDIR_QS header -->
  <input type="hidden" name="posted_redir" values="..." />
</form>

The POST is done on the form backend and handled by HAProxy, which extracts the information and passes it on to the SSO agent.

Add SSO ability to an application

After you set up SSO, use the following procedure to add more applications:

1. Add a new domain:

   • You must add the new domain in a Web form of an HTML page. The user must be able to select it, and you must include its value in the POST.

2. To add an application if you use Kerberos with an Active Directory:

   • Add a new service user associated with the service principal name (SPN) of your application.

   • Create a new Keytab for the new SPN or add it to an existing Keytab.

     On Windows:

     ktpass /out myapp.keytab /mapuser
     <service-user>MYDOMAIN.NET /princ
     HTTP/myapp.mydonain.net@MYDOMAIN.NET /pass <PASSWORD>

3. Update the keytab_file directive, if needed.

4. Add the application to conf/sso.map.

5. In the configuration file so.ini, add the application section and attach it to the correct domain.

6. Add the specified backend to haproxy.cfg.

7. To check if a user is allowed to access an application, you must check that the X-SSO-* headers are as follows:

   • X-SSO-APP: <name of the application>

   • X-SSO-DOMAIN: <name of the domain>

   • X-SSO-ACTION: alw

   • X-SSO-LOGIN: <user login> (SSO >= v1.2 or ALOHA >= 10.5.6)

Configuration directives

LDAP and Kerberos issues

The SSO solution does not require the file /etc/krb5.conf, but you can use it if the file is present in order to override default values or define a specific set of ciphers.

Refer to the MIT Kerberos documentation for more information.

To troubleshoot your environment, you can perform the following tasks:

• Set the environment variable KRB5_TRACE to a log file, or to /dev/stdout to get more verbose Kerberos diagnostics. In addition, you can pass the --debug-krb flag to the SSO daemon.

• Use the provided tool called sso-diag to test parts of the workflows involved when working with Kerberos.

• Test ticket creation in Kerberos using: ./sso-diag -f sso.ini -a MYAPP -d MYDOMAIN -u USER -p PASSWORD krb_ticket

• Check that your access rules or required LDAP groups are set and configured correctly by launching: ./sso-diag -f sso.ini -a MYAPP -d MYDOMAIN -u USER -p PASS auth and replacing MYAPP, MYDOMAIN, USER, and PASS with appropriate values. This directive simulates a user doing a POST on the authentication form with the supplied credentials.

• You can also use ./sso-diag -f sso.ini -a MYAPP -d MYDOMAIN -A MYAPP2 -D MYDOMAIN2 -u USER -p PASS check to simulate a POST with the supplied credentials on MYAPP on MYDOMAIN, and then try to access MYAPP2 on MYDOMAIN2.

• Get the status of the different worker threads running on the SSO agent by sending a SIGUSR1 at any time (when launched with --debug-all).

HAProxy 503 error

• If you get a 503 error (service unavailable) coming from HAProxy, launch the agent with the --debug-spoe-variables option.

• If the SSO application granted access to the URL, check that your backend is correctly configured in haproxy.cfg.

• For example, if you get any of the following messages, check that the POC backend exists in the file haproxy.cfg:

  Encode SPOE set-var str scope=1 sso_app=poc
  Encode SPOE set-var str scope=1 sso_domain=poc
  Encode SPOE set-var str scope=1 action=alw
  Encode SPOE set-var str scope=2 backend=poc

Configuration errors

Message: Invalid domain xxx: 'cannot match config'

• This means that the domain, which was set using sso.map by matching the host header, has no corresponding section in sso.ini.

Message: 'No authentication info found' displays repeatedly while

logging on the form

• If you get this error, check the sso_cookie_domain directive in sso.ini.

• The sso_cookie_domain must match the domain of your applications.

• When logging in with correct credentials, you should see a response header similar to this:

  Set-Cookie: sso-cookie=abc122342; domain=mydomain.net

No server contact error

Message: 'Cannot contact server' or 'error in start_tls()'

• Check that you configured your DNS correctly, and that you can reach the LDAP server on the correct port (standard ports are 636 or 389 depending on the configuration).

Failure to connect with LDAP server

Message: 'TLS or SSL already in effect'

• You cannot use a ldaps:// URL and a ldap_auth_start_tls set to 1 at the same time. They are mutually exclusive.

GnuTLS error

Message: 'GnuTLS: A TLS packet with unexpected length was received'

• You may get this error on servers where an old version of the GnuTLS or OpenSSL library was installed.

• You can change the ciphers used by LDAP libraries with environment variables. For instance:

  export LDAPTLS_CIPHER_SUITE='NORMAL:!VERS-TLS1.2'

SSL certificate error

Message: SSL routines

ssl3_get_server_certificate:certificate verify failed (unable to get local issuer certificate)

• You can bypass the LDAP certificates verification by using the -N flag.

• This sets the environment variable LDAPTLS_REQCERT to never

Host/domain error

Message: gss_acquire_cred_impersonate_name: host/domain

name not found'

• The host name of the server running the SSO agent must resolve to an IP.

• Add it to your DNS server or in your hosts file.

DNS issues

Message: gss_init_sec_context failed,

major_stat=851968, minor_stat=100006

• Reverse DNS must work on the server running the SSO agent.

• You must be able to resolve your server IP to its host name.

• If not, you can add this /etc/krb.conf, to disable the reverse DNS:

  [libdefaults]
  rdns = false