Configuring SSO
The single sign-on (SSO) function requires several configuration files.
Configure SSO
The file haproxy-sso.cfg
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:-
If you use your own external Web server to host the SSO portal, use:
backend sso_portal # this is the webserver used to diplay the SSO login form mode http server sso_portal-1 my_web_server:80
-
If you want to use the built-in LUA Web server, use:
global lua-load
sso_portal.lua# ... backend sso_portal mode http http-request use-service lua.sso_portal
-
Configure SSO SPOE
The haproxy-sso-spoe.cfg
file contains information regarding which messages to exchange between the SSO SPOE daemon and HAProxy.
We recommend that you do not modify it and keep it as provided.
Specify SSO mappings
The file sso.map
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
Configure the SSO daemon
The sso.ini
file 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 get replaced with appropriate values at run time. For example, if you prefer that all your backends start withbk_
, you can use:
backend = bk_<APP_NAME>
Configuration directives
Directive | Description |
---|---|
| 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 |
| The internal host name of your application. It must match the domain part of the Kerberos SPN (ie HTTP/mydomain.int) |
| The external FQDN of your application. |
| When setting this field to |
| Allows you to choose the location of the Kerberos tickets cache:
|
| Defines the domain attribute that the SSO agent must use when setting its cookie. You must match the longest common part of your external host name.
|
| Defines the lifetime of the SSO cookie (in seconds). Past this time, the user must reauthenticate. Default: |
| For each domain, you must define additional LDAP and Kerberos parameters as follows:
|
| Controls whether to use TLS when connecting to the LDAP server: |
| Must be defined for each application. |
| Indicates the URLs to reach the login. When users must enter their credentials, HAProxy Enterprise redirects them here.
|
| An authenticated user who reaches this URL gets logged out. |
| After a successful authentication, a message displays with a link to access the application.
|
| Secret used to encode the current user URL, and to redirect the user after a successful authentication.
|
| Use this directive to restrict access to a particular application to a specified group of users.
|
| By default, all applications require the user to log into the corresponding domain and a valid cookie to grant access.
|
| If set to |
| LDAP member to search for when computing LDAP groups membership (default: |
| LDAP filter to apply when computing LDAP groups membership (default: |
Diagnostics and troubleshooting
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 replacingMYAPP
,MYDOMAIN
,USER
, andPASS
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 onMYAPP
onMYDOMAIN
, and then try to accessMYAPP2
onMYDOMAIN2
.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 Enterprise 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 insso.ini
.
Message: 'No authentication info found' displays repeatedly while logging on the form
If you get this error, check the
sso_cookie_domain
directive insso.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 aldap_auth_start_tls
set to1
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
tonever
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
Next up
SAML