The SSO solution requires several configuration files.

haproxy-sso.cfg

This file defines the main HTTP frontend that HTTP clients require in order to use SSO.

It also defines the HTTP rules, ACLs, and checks involved between the SPOE agent and HAProxy.

You may have to modify parts of this file depending on your Active Directory setup and your network configuration.

  • The bind directive of the frontend: bind *:80

  • The sso_portal backend:

backend sso_portal
   # this is the webserver used to diplay the SSO login form
   mode http
   server sso_portal-1 my_web_server:80

haproxy-sso-spoe.cfg

This file contains information regarding which messages will be exchanged between the SSO SPOE daemon and HAProxy.

We recommend that you do not modify it and keep it as provided.

sso.map

This file must contain the mappings between your different applications and the Host header.

# Host header                      <domain>/<app>
sp2010.mydomain.net                2010.mydomain.net/sharepoint2010
sp2013.mydomain.net                2013.mydomain.net/sharepoint2013
exchange2013.mydomain.net          2013.mydomain.net/exchange2013
stats.mydomain.net                 stats/stats

sso.ini

This is the main configuration file of the SSO daemon. It must contain information about each application that you want to manage.

It uses a similar syntax to any typical Windows .ini file.

  • Lines starting with ; or # are comments.

  • Comments can appear at the end of any line when preceded by a space.

  • There are several sections in sso.ini:

    • The default section ([defaults]) contains default values. These values are inherited by each domain.

    • Domain sections ([domain:mydomain]) define properties valid for the scope of the entire domain.

    • Other sections are applications sections.

  • At least one domain section is required, and each application must be attached to exactly one domain. Applications inherit the properties of their domain, and can also override them.

  • Some properties can include keywords within brackets such as <KRB_REALM> that will be replaced with appropriate values at run time. For example, if you prefer that all you backend start with bk_, you can use:

backend = bk_<APP_NAME>

Configuration directives

Directive

Description

[application_name]

Each application must have a unique name. To name applications, you may use alphanumeric characters or underscores. This name must match a name in the sso.map file.

internal_domain

The internal host name of your application. It must match the domain part of the Kerberos SPN (ie HTTP/mydomain.int)

external_domain

The external FQDN of your application.

krb_auth_method

When setting this field to 1, the user will be authenticated using the information provided in the login form. This is the recommended method, in addition to krb_s4u = 1 that uses Kerberos constrained delegation.

krb_cache_name

Allows you to choose the location of the Kerberos tickets cache:

  • on disk: /tmp/kr5cc_<USER>

  • in memory: MEMORY:kr5cc_<USER>

sso_cookie_domain

Defines the domain attribute that the SSO agent will use when setting its cookie. You must match the longest common part of your external host name.

  • sso_cookie_lifetime: Defines the lifetime of the SSO cookie (in seconds)

  • Past this time, the user is required to reauthenticate.

    Default: 36000s.

sso_cookie_lifetime

Defines the lifetime of the SSO cookie (in seconds). Past this time, the user is required to reauthenticate.

Default: 36000s.

ldap_uri

For each domain, you must define additional LDAP and Kerberos parameters as follows: ldap://ad.mydomain.net.

The LDAP server validates the credentials from the user, and refreshes all groups to which the user belongs.

A group membership will be refreshed every ldap_groups_refresh_interval seconds, and it can use a different user/password specified in ldap_groups_refresh_user and ldap_groups_refresh_password.

  • ldap_base, such as dc=mydomain,dc=net

  • krb_realm contains your Kereros realm (usually in upper case)

  • krb_keytab_file defines the keytab file that will contain Kerberos services you want to use

ldap_auth_start_tls

Controls whether to use TLS when connecting to the LDAP server: 0:disabled, 1:enabled (by default)

internal_domain, external_domain

Define for each application

auth_url

Indicates the URLs to reach the login. When the users need to enter their credentials, the get redirected here.

After a successful authentication, a message displays with a link to access the application. You can use title_page to define the target of the link.

Example: the URL for a standard Sharepoint2013 installation can be: https://<EXTERNAL_DOMAIN>/SitePages/Home.aspx

title_page

After a successful authentication, a message displays with a link to access the application.

You can use title_page to define the target of the link.

Example: the URL for a standard Sharepoint2013 installation can be: https://<EXTERNAL_DOMAIN>/SitePages/Home.aspx.

You must use an absolute URL with the scheme (HTTP or HTTPS).

ldap_required_group

Use this directive to restrict access to a particular application to a specified group of users.

The group must have the following form: CN=Builtin,DC=2013,DC=mydomain,DC=net. The matching is done using the memberOf attribute which is case insensitive.

allow_unauthenticated_users = 1

By default, all applications require the user to log into the corresponding domain and a valid cookie to grant access.

This directive allows access to certain applications without any access check.

Kerberos customization, diagnostics, and troubleshooting

Troubleshoot Kerberos

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

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, an then try to access MYAPP2 on MYDOMAIN2.

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

Troubleshoot an 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

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.

'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)

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

'No authentication info found' displayed 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

'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 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

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

'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