Active Directory setup

 

About Setup

Before you can configure an authentication connector for your Active Directory LDAP server in KeyShield SSO, it is necessary to perform setup on Active Directory Domain Controller. We've provided convenient setup script to help you with this task. kshield_ad_setup.ps1 will:
  • create KeyShield SSO manager user account - used to find users during authentication
  • grant KeyShield SSO manager user account permissions on search base container to find users and read required user attributes
  • create service account (computer) for NTLM authentication - used when Active Directory authentication method and NTLM authentication is enabled in connector configuration
  • extend Active Directory schema for two-factor authentication support - it adds two attributes and one auxiliary class

Before you start

Login to your Domain Controller or Schema Master server and download the script kshield_ad_setup.ps1 to a directory located on the server. Please check health of your Active Directory installation before running the setup script, especially if you are planning to extend Active Directory schema for two-factor authentication.

Running kshield_setup_ad.ps1

To run kshield_setup_ad.ps1, run the following command from PowerShell console on the server: PowerShell.exe -ExecutionPolicy UnRestricted -File kshield_ad_setup.ps1 You will be presented with a setup dialog, where you can review and change setup parameters. After executing the script, configuration values for connector setup will be printed in PowerShell console like this: Now, return to KeyShield SSO web console, go to Configuration -> Authentication Connectors -> click 'add Connector' and enter information printed by the script to configure KeyShield SSO for your AD tree. Note: It is possible to run KeyShield SSO setup script multiple times, password for KeyShield SSO manager user account and NTLM service account are reset each time and must be updated in the corresponding connector configuration after running script.

KeyShield SSO manager/proxy user account

KeyShield SSO uses this user account to authenticate into LDAP server and run queries to find user objects under search base container during authentication. When two-factor authentication is enabled, it is also used to store and read 2FA token id attributes on user objects. Manager account is granted permissions to read general attributes, mail attributes, change password, read and modify objectclass (for auxiliary class extension) and optionally to read/write tdpSSOTokenPerm and tdpSSOTokenTemp attributes added for two-factor authentication if you enable schema extension. If you enable Create/repair KeyShield SSO Manager account option in the setup dialog, KeyShield SSO manager user account is created if it doesn't exist. Then password is reset to random password and permissions to search base container are granted.

NTLM service account

When Active Directory authentication method is enabled, we recommend to use NTLM authentication to authenticate users against your Active Directory server. To do this, KeyShield SSO needs service account in Active Directory. It's basically a computer object with a password. If you enable Create service account for NTLM authentication option in the setup dialog, script creates this account for you and sets a random password. Note: Windows Vista and Windows 7 requires a group policy change to use the NTLMv1 protocol instead of NTLMv2. Other versions of Windows can also have this issue if your organization's security policy does not support NTLMv1. If you do not make this change, it can cause KeyShield client authentication error.   To configure NTLM compatibility for Windows Vista or Windows 7:
  1. Click Start > All Programs > Accessories > Run and type secpol.msc in the Open box, and then click OK.
  2. Click Local Policies > Security Options > Network Security: LAN Manager authentication level.
  3. Click SendLM& NTLM - use NTLMv2 session security if negotiated.
  4. Click Apply.
  You must perform this procedure on every computer that runs has this issue in your network. Alternatively, you can use the Active Directory group policy to make this change for all computers.

Two-factor authentication (2FA)

If you plan to use two-factor authentication such as RFID cards or tokens with KeyShield SSO, you will need to enable Extend Active Directory schema for 2FA option in the setup dialog. This enables installation of two-factor authentication schema extensions into your Active Directory schema. This extends Active Directory schema with attributes necessary for storage of user token ID attributes. Attributes tdpSSOTokenPerm, tdpSSOTokenTemp and dynamic auxiliary class tdpSSOTokenUser will be added to AD schema. No existing user objects will be modified, dynamic auxiliary class will be added only to user objects with token id assigned from KeyShield SSO Token Management console. Before proceeding, make sure the account you're logged in is member of the Domain Admins, Schema Admins or Enterprise Admins security groups. Also, you need to run schema extension on a computer that is in the same Active Directory domain and site as the schema master. We recommend that you first test KeyShield SSO 2FA schema extensions in your Active Directory test environment with same third party extensions as present in your production tree.

Kerberos Authentication Method setup

To enable Kerberos Authentication Method:
  • Log in to the Windows Domain Controller. You must know which server is the domain controller and you must login as user with administrator permissions.
  • Create a new account named e.g ks_kerberos for KeyShield SSO Kerberos service in Active Directory Users and Computers settings.
  • On the Account page, select the User cannot change password and Password never expires check boxes. By preventing the password from expiring, you avoid having to recreate the keytab file when the password is changed. Click OK to save the new user information.
  • It doesn't matter what password you assign to the ks_kerberos user as it will be assigned a new random password by ktpass command later.
  • Map a service principal name (SPN) in the form of <SERVICE>/<host>@<UPPERCASE AD DOMAIN NAME> to the ks_kerberos user using following ktpass command
Note: The host part of service principal name is the host DNS or NETBIOS name of KeyShield SSO server - it's not really used to access the server, it's only used as an unique identifier of the service (for example if you have multiple KeyShield SSO servers) and to find the encryption key in the keytab file. Assuming KeyShield SSO server is running at host server.host.com, you would map SPN to ks_kerberos user account like this:
  • Open a command prompt with administrator permissions.
  • Run ktpass with following parameters (remember to substitute KeyShield SSO server hostname for server.host.com and your AD domain name for YOURADDOMAIN.LOCAL).
ktpass -out ks_kerberos.keytab -princ KS/server.host.com@YOURADDOMAIN.LOCAL -mapUser youraddomain\ks_kerberos -mapOp set +rndPass -ptype KRB5_NT_PRINCIPAL -kvno 0 This will map the SPN KS/server.host.com@YOURADDOMAIN.LOCAL' to user ks_kerberos. The command also saves kerberos keytab file as ks_kerberos.keytab in the current directory (make sure you have write permission to the directory you are running ktpass from). Finally enter the SPN into KeyShield SSO connector configuration (Kerberos Service Principal), upload the generated ks_kerberos.keytab and save and apply the configuration.

Domain Controller

Domain Controller is a server that is responsible for authentication requests within a Windows domain/Active Directory installation. Schema Master is a selected Domain Controller responsible for updating Active Directory Schema. Schema changes are then replicated to other Domain Controllers.

PowerShell

PowerShell is a Microsoft command-line scripting shell used to manage Windows Servers and Desktops. To run PowerShell:
  • On the desktop, press the Windows logo key+R to open the Run dialog box.
  • In the Run dialog box, type powershell, and then press Enter.

Command-Line interface

Command-line interface is a user interface, where the user interacts with a computer by entering text commands in the form of successive lines of text into command window (console). To run command using command-line interface, type the command into console window and press Enter.