Skip to main content

Kerberos Single Sign-On

Kerberos single sign-on allows users to be automatically signed into BlockID applications whenever logged into their Active Directory network. Users wishing to use Kerberos SSO with BlockID on their AdminX portal will require access to their Kerberos Domain Controller with admin privileges to generate a keytab file.

Prerequisites for Kerberos SSO​

Enabling Kerberos SSO in AdminX​

Enabling Kerberos SSO in a New AD Broker User Directory​

To create a new AD Broker user directory with Kerberos enabled, please see AdminX Broker. Kerberos configuration can be enabled during Step 4: Advanced Configuration.

Enabling Kerberos SSO in Existing AD Broker User Directories​

BlockID users with an Active Directory user store connected via the AD Broker can enable Kerberos support in the AdminX portal.

To do so, log in to your AdminX portal as a tenant or community administrator.

From the Dashboard, click Directory Integrations link from the left side menu.

Scroll down to your AD Broker user directory, and click the pencil icon to edit its configuration.

Click the Workstation Login tab to access advanced configuration details.

Scroll down to the Kerberos Single Sign-on section and toggle the switch to enable the Kerberos configuration settings. Under Key Tab file, click Upload and add your Kerberos keytab file.

Click save once the file has been uploaded to complete the Kerberos configuration.

Testing Kerberos SSO Integration​

Once you have enabled Kerberos SSO in AdminX, the final step is to test the integration to ensure the single sign-on functionality is working. To do so, log out of the AdminX panel by clicking your username in the upper-right corner and selecting Logout.

Return to the login page for your AdminX panel. If Kerberos SSO is working, you will automatically be logged in without having to scan your QR code, or entering a username and password.

Steps to be Completed in Active Directory​

tip

Administrator privileges to the Active Directory member server or domain controller are required for the following steps

Before enabling Kerberos SSO in AdminX, users need to generate a keytab file on an Active Directory member server or Domain Controller. Users should also take note of the following:

  • A keytab file should be generated for each tenant
  • The keytab file should be treated the same as a password from a security standpoint
  • The keytab service principal must match tenant to be used (see below)
  • The realm part of the service principal must be upper-case (BLOCKID.1KOSMOS, not blockid.1kosmos)

Users should follow the instructions below to generate a keytab file. Users must upload this keytab file into the configuration settings page for their AD Broker user directory in AdminX.

Create Service Account and Configure SPN​

An Active Directory service account must be created. This action should be completed on either a member server or a domain controller of the Active Directory domain, and administrative access to the controller is required.

Steps​

  1. To open the Active Directory Users and Computers (ADUC) Microsoft Management Console (MMC) console on the Active Directory server, click Start > Run, and enter dsa. msc, and press Enter
  2. Right-click the folder where you want to create the new account and select New > User
  3. Complete the following fields:
    • First name - Enter the user's first name
    • Initial - Optional. Enter an initial for the user's middle name
    • Last Name - Enter the user's last name
    • Full name - Optional. Enter the user's full name
    • User logon name - Enter a username
  4. Click Next
  5. Complete the Password and Confirm Password fields and clear the User must change password at next logon check box
    tip

    We recommend selecting Password never expires to avoid service interruptions. As a security precaution, update the service account password regularly

  6. Click Next and click Finish
  7. Right-click the user created in step 6, select Properties, select the Account tab, and then select the This account supports Kerberos AES 128 bit encryption or This account supports Kerberos AES 256 bit encryption checkboxes in the Account Options area
  8. Click Apply
  9. Create a group policy to enable AES encryption on the AD server. See Windows Configurations for Kerberos Supported Encryption Type
  10. Open a command prompt and run the command to configure an SPN for the service account:
    • Command format: setspn -S HTTP/<BlockID tenant domain>@<REALM> <ServiceAccountName>
    • Example command: setspn -S HTTP/blockid.1kosmos.com@BLOCKID.1KOSMOS spnadmin

Service Principal (SPN) Format​

The format for the service principal (SPN) used in step 10 above is as follows: HTTP/<1kosmos tenant domain>@<REALM>

  • Make sure the setspn command has the correct BlockID tenant domain and REALM
  • If your tenant domain is blockid.1kosmos.net, and your AD REALM is BLOCKID.1KOSMOS, your service principal (SPN) is HTTP/blockid.1kosmos.net@BLOCKID.1KOSMOS
tip

Your REALM is your Active Directory domain in UPPER-CASE, minus the TLD (.com, .net, etc.)

Find your Kerberos REALM​

To obtain the Kerberos Realm and DNS Names in Active Directory, perform the following steps:

  1. Open Programs- > Administrative Tools- > Active Directory Management
  2. Choose Active Directory Domains and Trusts
  3. The Active Directory domain names will be listed

If you need to remove a service principal (SPN), use the following command:

Command format​

setspn -d service/name hostname

Example command​

setspn -d HTTP/blockid.1kosmos.net@BLOCKID.1KOSMOS blockid.1kosmos.net

Generate Keytab File​

After running the setspn command above, the next step is to generate the Kerberos keytab file.

Open a command prompt and run the following command to generate the keytab file:

Command format​

ktpass -out <fn>.keytab -mapuser <ad user from above> +rndPass -mapOp set +DumpSalt -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -princ <service principal name>

Example command​

ktpass -out myfile.keytab -mapuser spnadmin@BLOCKID.1KOSMOS +rndPass -mapOp set +DumpSalt -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -princ HTTP/blockid.1kosmos.net@BLOCKID.1KOSMOS

Explanation of the command options:​

  • -out <filename.keytab>: keytab file name
  • -mapuser <AD user>: AD user created during step 3 above
  • +rndPass: generate a random password
  • -mapOp set: set command
  • +DumpSalt: show the salt algorithm
  • -crypto AES256-SHA1: use AES 256 SHA1
  • -ptype KRB5_NT_PRINCIPAL: kerberos principal type
  • -princ <service principa>: set service principal created during step 10 above

After successfully running the command above, copy the generated keytab file to a secure location. This keytab file will need to be uploaded to the AdminX portal.

Please note:

  • The AD user and -crypto settings must match what was set during Step 7 in the section titled Create Service Account and Configure Service Principal Name
  • Your service principal (SPN) must match your BlockID tenant
  • Your service principal (SPN) must match what was set in the setspn command during Step 10 in the section titled Create Service Account and Configure Service Principal Name