Skip to main content

Settings for SSO

Windows Server Settings​

User authentication takes place using the Kerberos protocol (SPNEGO/GSSAPI, see RFC 4559). Before setting up, it is necessary to select a domain name (FQDN) under which the web will be available services on the UCS server and the service user name of the user that will be established in MS AD. Attention, when changing the domain name, it is necessary to repeat the generation process keytab file.

  1. Create a service user account in Active Directory to which the keytab will be bound, with which UCS will verify Kerberos tickets of users accessing web sites services on the UCS server.

    account creation - names create account - password

    Username, first name and last name can be anything you want. Login username must be without spaces.

    A user must be established in OU Users in order to create a file keytab. Once created, the user account can be transferred to another OU.

    Remember the password, it will be necessary to enter it in the next step, when creating the keytab file. Set the parameters so that a password change is not required after the first login and then the parameter that the password is still valid. Whether the user cannot change the password is optional.

  2. On a domain controller or station with an installed RSAT open a command prompt and type the following command:

ktpass
  -out ucs.keytab
  -princ HTTP/ucs.firma.cz@FIRMA.CZ
  -mapUser firma\ucs
  -mapOp set
  -pass heslo
  -ptype KRB5_NT_PRINCIPAL
  -crypto All

The values you need to enter according to your organization's AD settings are for -princ, -mapUser and -pass arguments.

The command is entered on one line, the parameters are listed in this document on multiple lines for clarity.

The name of the keytab file can be arbitrary. After passing to the UCS server, it should file to be deleted from the domain controller.

It is absolutely necessary to respect the case in the princ parameter! HTTP in uppercase, domain in lowercase, realm behind the culprit in uppercase.

Although the server is accessed via the https protocol, the service name in the princ must be HTTP, not HTTPS! There is only one slash after HTTP, it is not a URL.

Replace the value ucs.firma.cz with the address under which users will access web browser to the UCS server. If you are running UCS in HA mode and the name server is ucs1.firma.cz, or ucs2.firma.cz, but users access the address https://ucs.frima.cz/, use ucs.firma.cz.

Attention, if you add the -setUpn parameter, the userPrincipalName a will not change it will not be possible to use access to user data and group membership (GSSAPI authenticated access to AD using LDAP). This is not a parameter, but by an attribute that would have to be specified as +setUpn.

In the pass parameter, enter the password you set for the service user account.

  1. Upload the generated ucs.keytab file to the UCS server.

    Attention, do not send the file by e-mail or any other insecure way. Contains private login key on the basis of which it is possible to log in to AD s by the permission of the service user account!

Firewall Settings​

  • For authentication of user Kerberos tickets, transmitted through browsers it is necessary to enable communication initiated by the UCS server towards AD on TCP port 88.

  • If accounts from AD are to be synchronized (initiated by the user's first login) or verifying the user's membership in a group, it is also necessary to allow access to the service LDAP to AD. Communication is initiated from the UCS server towards AD on TCP port 636, respectively 389, depending on whether the LDAPS or LDAP protocol is used.

  • If you are not using a stateful firewall, then you need to implement the rules of the rules for responses from MS AD (mirrored IP and ports).

| Service | Source IP | Source Port | Destination IP | Destination Port | |:---------|:-----------:|--------------:|:------- --:|------------:| | Kerberos | UCS | 1024-65535 | MS AD | 88 | | LDAP | UCS | 1024-65535 | MS AD | 389 | | LDAPS | UCS | 1024-65535 | MS AD | 636 |

Workstation settings​

In order for login to work without entering a password, the workstation must also be up-to-date user logged into the Windows domain. Subsequently, it is necessary to enable SSO for domains name ucs.firma.cz (all browsers use this setting):

  1. Internet options
  2. tab Security
  3. Icon Local Intranet
  4. the Websites button will open another dialog
  5. The address is added in the format: http://ucs.firma.cz and https://ucs.firma.cz, Alternatively, you can use http://*.firma.cz and https://*.firma.cz, if used more web services for SSO. Don't forget to click the Add button to added the address to the allowed websites.

local intranet

UCS settings​

Single sign-on is set up in the UCS v System → SSO providers. Below is an example of a setting that corresponds ktpass example in this document.

MSAD SSO setup in UCS

  • The Realm value is entered in capital letters. Realm must be specified, not truncated Windows domain name.
  • Users are authenticated in AD in the order in which the controller hostnames are entered. It is possible to achieve polling, for example, of a less busy DC. If the first DC is unavailable, then continue to the second, etc.
  • Base DN is used in LDAP filters when verifying user membership in groups and in case AD is used as IDP (automatic creation of users in UCS at their first login).
  • The Username lookup setting specifies whether the user should be searched for in AD using his login name (Username - e.g. “pepa”) or according to his Kerber principal (Principal - e.g. “pepa@FIRMA.CZ”).
  • The setting Usernames format indicates in which format the users are based in UCS and performs the necessary mapping. A value of Username means that users are in UCS established under usernames - e.g. "pepa", the value Domain means, that users are established in UCS incl. domains - e.g. "FIRMA\pepa" and the value Principal means that users in UCS are established under their Kerberos principals - e.g. "pepa@FIRMA.CZ".
  • If the Require group to login option is checked, then UCS will verify before login, that the user is a member of at least one of the groups listed below. In this case, that if the user has a valid Kerberos ticket, but is not a member of any of the listed groups, then UCS will reject its registration.
  • Mapping Group DN to Template user serves to automatically create a user at his first login. If the user is a member of the given group, then he is established according to the given user template. Attention, if the user's group changes, UCS will not execute automatic change of settings according to the new user template.
  • Mapping Windows domain to Kerberos realm serves to translate the domain Windows names to the Kerberos realm and is only used if a login fails using a Kerberos ticket, the user logs in using the form (name and password) and enter your name in the format “FIRMA\pepa”.

Troubleshooting​

Validation of keytab file​

For form logins, it must be possible to obtain a TGT based on saved accesses in the ktpass file. Obtaining a kerberos ticket is done on the command line as follows (The UCS SSO interface renews the expired ticket automatically).

kinit -k HTTP/ucs.firma.cz

klist
Valid starting       Expires              Service principal
10/13/2021 13:26:02  10/13/2021 21:26:02  krbtgt/FIRMA.CZ@FIRMA.CZ

Errors that are not errors​

Some error messages may look like errors, but that's all they really are entering a wrong password or a non-existent username. It is the following return codes from MSAD:

Major: 458752 No credentials were supplied, or the credentials were unavailable or inaccessible Major: 851968 Unspecified GSS failure

According to the minor number of the error, it is then possible to recognize:

  • Wrong password - Minor: 2529638936 Preauthentication failed
  • Password not entered - Minor: 22 Invalid argument
  • Non-existent account - Minor: 2529638918 Client 'username@realm' not found in Kerberos database