You are here

Kerberos

The configuration for Kerberos authentication will allow users to access Alfresco products by entering their credentials only once when logging into their Windows environment.

The following diagram illustrates the components and authentication flow for a Kerberos setup:

Kerberos authentication diagram

Prerequisites

The following are the prerequisites needed to configure SSO with Kerberos:

  • The correct product versions of the Alfresco software you are using.
  • A Kerberos Key Distribution Center (KDC).
  • An instance of Active Directory.
  • Administrator access to all systems.

Configuration

There are six steps to configuring SSO using Kerberos with Alfresco products. The following are the host names used as examples throughout the configuration:

  • Alfresco Content Services: repo.example.com
  • Alfresco Share: share.example.com
  • Alfresco Digital Workspace: adw.example.com
  • Alfresco Office Services: repo.example.com/alfresco/aos
  • Alfresco Process Services: aps.example.com
  • Alfresco Process Workspace: apw.example.com
  • Active Directory: ldap.example.com
  • Load Balancer: alfresco.example.com
Important: If using a containerized deployment there are several amendments and additions required for certain steps.

Step 1: Configure Kerberos files

A user account and keytab file is required for Alfresco Content Services (ACS), Alfresco Share and Alfresco Process Services (APS) and a krb5.conf file that details the location of the authentication server needs to be located on each server. The files can be configured against a load balancer.

The following table explains the values used to generate the keytab and krb5.conf files:

Variable Description Example
host A server host or load balancer name without a domain suffix alfresco
domain The Domain Name System (DNS) domain example.com
domainnetbios The Windows domain NetBIOS name example
REALM The DNS domain in uppercase EXAMPLE.COM
  1. Create a user account in Active Directory for the SSO authentication filters:
    • Enter a full name such as HTTP alfresco.
    • Enter a login name such as httpalfresco.
    • Enable the setting Do not require Kerberos pre-authentication.
  2. Use the ktpass command to generate a key table for the user account created in the previous step:

    ktpass -princ HTTP/<host>.<domain>@<REALM> -pass <password> -mapuser 
    <domainnetbios>\http<host> -crypto all -ptype KRB5_NT_PRINCIPAL -out 
    c:\temp\http<host>.keytab -kvno 0
    For example:

    ktpass -princ HTTP/alfresco.example.com@EXAMPLE.COM -pass <password> -mapuser 
    example\httpalfresco -crypto all -ptype KRB5_NT_PRINCIPAL -out 
    c:\temp\httpalfresco.keytab -kvno 0
  3. Use the setspn command to create Service Principal Names (SPN) for the user account created in the first step:

    setspn -a HTTP/<host> http<host>
    setspn -a HTTP/<host>.<domain> http<host>
    For example:

    setspn -a HTTP/alfresco httpalfresco
    setspn -a HTTP/alfresco.example.com httpalfresco
  4. In the Delegation tab of the Properties of the user account created in the first step, tick the Trust this user for delegation to any service (Kerberos only) checkbox.
  5. Copy the key table file created to a protected area on each server such as C:\etc.
    Note: The servers to copy the key table file to are Alfresco Content Services, Alfresco Share and Alfresco Process Services.
  6. Configure a krb5.conf file that contains details of the authentication server:

    [libdefaults]
    default_realm = <REALM>
    default_tkt_enctypes = rc4-hmac
    default_tgs_enctypes = rc4-hmac
              
    [realms]
    <REALM> = {
            kdc = <host>.<domain>
            admin_server = <host>.<domain>
              }
              
    [domain_realm]
    <host>.<domain> = <REALM>
    .<host>.<domain> = <REALM>
    The following is an example krb5.conf file:

    [libdefaults]
    default_realm = EXAMPLE.COM
    default_tkt_enctypes = rc4-hmac
    default_tgs_enctypes = rc4-hmac
              
    [realms]
    EXAMPLE.COM = {
                kdc = ldap.example.com
                admin_server = ldap.example.com
                  }
              
    [domain_realm]
    ldap.example.com = EXAMPLE.COM
    .ldap.example.com = EXAMPLE.COM
  7. Copy the krb5.conf file to the servers running Alfresco Content Services, Alfresco Share and Alfresco Process Services. By default it is located in $WINDIR\krb5.conf where $WINDIR is the location of the Windows directory such as C:\Windows\krb5.conf.

Step 2: Configure Alfresco Content Services (ACS)

The Java login files need to be updated with details of the Kerberos configuration and the alfresco-global.properties updated to enable SSO using Kerberos.

  1. Configure or create the Java configuration file java.login.config located in /java/conf/security. The following is an example of a java.login.config file. The important properties to set are keyTab and principal.
    • keyTab is the location of the keytab file copied to the ACS server
    • principal is in the format HTTP/<host>.<domain>

    Alfresco {
      com.sun.security.auth.module.Krb5LoginModule sufficient;
    };
              
    AlfrescoHTTP
    {
      com.sun.security.auth.module.Krb5LoginModule required
        storeKey=true
        useKeyTab=true
        doNotPrompt=true
        keyTab="/etc/kerberos.keytab"
        principal="HTTP/alfresco.example.com";
    };
              
      com.sun.net.ssl.client {
        com.sun.security.auth.module.Krb5LoginModule sufficient;
    };
              
    other {
      com.sun.security.auth.module.Krb5LoginModule sufficient;
    };       
  2. Edit the following line in the Java security configuration file java.security by default located in java/conf/security/ to point to the java.login.config file using the full file path:

    login.config.url.1=file:<installLocation>/java/conf/security/java.login.config
  3. Use the following configuration parameters in an alfresco-global.properties file:
    Property Description Example
    authentication.chain The authentication chain needs to be set for Kerberos. kerberos,alfrescoNtlm1:alfrescoNtlm
    kerberos.authentication.realm The Kerberos realm to authenticate against. The realm name is the domain name in uppercase EXAMPLE.COM
    kerberos.authentication.sso.enabled Sets whether authentication using Kerberos is enabled or not true
    kerberos.authentication.sso.fallback.enabled Sets whether a fallback authentication mechanism such as database credentials is used true
    kerberos.authentication.user.configEntryName The name of the entry in the Java Authentication and Authorization Service (JAAS) file used for password-based authentication. The default value of Alfresco is recommended Alfresco
    kerberos.authentication.http.configEntryName The name of the entry in the JAAS file used for web-based authentication. The default value of AlfrescoHTTP is recommended AlfrescoHTTP
    kerberos.authentication.defaultAdministratorUserNames A comma separated list of users that are treated as administrators admin,superuser
    kerberos.authentication.browser.ticketLogons Sets whether ticket parameters in URLs are authenticated with true
    kerberos.authentication.stripUsernameSuffix Sets whether the @domain suffix is stripped from Kerberos authenticated usernames or not false

Step 3: Configure Alfresco Share

The Java login files need to be updated with details of the Kerberos configuration and the share-config-custom.xml file edited to enable SSO using Kerberos.

  1. Configure or create the Java configuration file java.login.config located in /java/conf/security. The following is an example of a java.login.config file. The important properties to set are keyTab and principal.
    • keyTab is the location of the keytab file copied to the ACS server
    • principal is in the format HTTP/<host>.<domain>

    Alfresco {
      com.sun.security.auth.module.Krb5LoginModule sufficient;
    };
              
    ShareHTTP
    {
      com.sun.security.auth.module.Krb5LoginModule required
        storeKey=true
        useKeyTab=true
        doNotPrompt=true
        keyTab="/etc/kerberos.keytab"
        principal="HTTP/alfresco.example.com";
    };
              
      com.sun.net.ssl.client {
        com.sun.security.auth.module.Krb5LoginModule sufficient;
    };
              
    other {
      com.sun.security.auth.module.Krb5LoginModule sufficient;
    };       
    Note: If Alfresco Share is hosted on the same server as Alfresco Content Services then the contents of the java.login.config can be merged into a single file.
  2. Edit the following line in the Java security configuration file java.security by default located in java/conf/security/ to point to the java.login.config file using the full file path:

    login.config.url.1=file:<installLocation>/java/conf/security/java.login.config
  3. Open the share-config-custom.xml file:
    • Update the <realm>property with the realm name, for example <realm>EXAMPLE.COM</realm>.
    • Update the <endpoint-spn> property with the SPN value, for example <endpoint-spn>HTTP/alfresco@EXAMPLE.COM</endpoint-spn>
    • Uncomment the two sections that begin with: <config evaluator="string-compare" condition="Remote">
    • Navigate to the <!--- Kerberos settings ---> section and replace condition="KerberosDisabled" with condition="Kerberos"
    Note: For Kerberos to work with user names that contain non-ASCII characters, add the following option to JAVA_OPTS for the Share JVM:

    -Dsun.security.krb5.msinterop.kstring=true

Step 4: Configure Alfresco Digital Workspace

The Alfresco Digital Workspace requires one property added to enable Kerberos SSO. This can be added in the app.config.json, located by default in the /srcdirectory.

The following is the property to add to the app.config.json:

 "auth": {
      "withCredentials": true
}   

Step 5: Configure Alfresco Process Services

The Java login files need to be updated with details of the Kerberos configuration and the activiti-ldap.properties updated to enable SSO using Kerberos.

  1. Configure or create the Java configuration file java.login.config located in /java/conf/security. The following is an example of a java.login.config file. The important properties to set are keyTab and principal.
    • keyTab is the location of the keytab file copied to the ACS server
    • principal is in the format HTTP/<host>.<domain>

    Alfresco {
      com.sun.security.auth.module.Krb5LoginModule sufficient;
    };
                
    AlfrescoHTTP
    {
      com.sun.security.auth.module.Krb5LoginModule required
        storeKey=true
        useKeyTab=true
        doNotPrompt=true
        keyTab="/etc/kerberos.keytab"
        principal="HTTP/alfresco.example.com";
    };
                
      com.sun.net.ssl.client {
        com.sun.security.auth.module.Krb5LoginModule sufficient;
    };
                
    other {
      com.sun.security.auth.module.Krb5LoginModule sufficient;
    };       
  2. Edit the following line in the Java security configuration file java.security by default located in java/conf/security/ to point to the java.login.config file using the full file path:

    login.config.url.1=file:<installLocation>/java/conf/security/java.login.config
  3. Use the following configuration parameters in an activiti-ldap-properties file:
    Property Description Example
    kerberos.authentication.enabled Sets whether authentication via Kerberos is enabled. This needs to be set to true to setup SSO using Kerberos true
    kerberos.authentication.principal The Service Principal Name (SPN) to authenticate against HTTP/alfresco.example.com
    kerberos.authentication.keytab The location of key table file C:/alfresco/alfrescohttp.keytab
    kerberos.authentication.krb5.conf The location of the Kerberos ini file C:/Windows/krb5.ini
    kerberos.allow.ldap.authentication.fallback Sets whether to allow sign in from unsupported browsers using LDAP credentials false
    kerberos.allow.database.authentication.fallback Sets whether to allow sign in from unsupported browsers using database credentials true
    kerberos.allow.samAccountName.authentication Sets whether authentication can use the short form such as username rather than username@domain.com true
    security.authentication.use-externalid A setting that enables authentication through Kerberos true
    ldap.authentication.enabled Sets whether LDAP authentication is enabled. This setting needs to be set to true for SSO to work for Kerberos true

Step 6: Configure Alfresco Process Workspace

The Alfresco Process Workspace requires three properties added to enable Kerberos SSO. These can be added in the app.config.json, located by default in the /srcdirectory.

The following are the properties to add to the app.config.json:

 "auth": {
      "withCredentials": true
}   
"ecmHost": "https://repo.example.com",
"bpmHost": "https://aps.example.com",

(Optional) Containerized deployment

In a containerized deployment it is assumed that a load balancer is used to route traffic to the relevant applications. The Active Directory instance used to authenticate users with in a containerized Kerberos scenario is also more likely to exist outside of the domain of the Alfresco applications.

Kerberos configuration files

In Step 1 the keytab and krb5.conf files need to be edited if the Active Directory instance is in a separate domain.

  1. The keytab file can be configured to refer to an Active Directory instance in a separate domain if necessary.

    For example:

    ktpass -princ HTTP/alfresco.example.com@AD-SSO.EXAMPLE.COM -pass PASSWORD -mapuser 
    ad-sso\httpsalfresco -crypto all -ptype KRB5_NT_PRINCIPAL -out 
    c:\temp\httpalfresco.keytab -kvno 0
    Where alfresco.example.com is the load balancer address, AD-SSO.EXAMPLE.COM is the domain of the Active Directory instance and ad-sso is the domainnetbios of the Active Directory instance.
  2. The krb5.conf uses the internal IP address of the Active Directory container.

    For example:

    [libdefaults]
    default_realm = AD-SSO.EXAMPLE.COM
    default_tkt_enctypes = rc4-hmac
    default_tgs_enctypes = rc4-hmac
              
    [realms]
    AD-SSO.EXAMPLE.COM = {
              kdc = ec2amaz-5gk9lmd.ad-sso.example.com
              }
              
    [domain_realm]
    ec2amaz-5gk9lmd.ad-sso.example.com = AD-SSO.EXAMPLE.COM
    .ec2amaz-5gk9lmd.ad-sso.example.com = AD-SSO.EXAMPLE.COM

Share configuration file

The same edits need to be carried out on the share-config-custom.xml however the <realm> will be the Active Directory domain name and the <endpoint-spn> will use the load balancer address and Active Directory domain.

For example:

<realm>AD-SSO.EXAMPLE.COM</realm>
<endpoint-spn>HTTP/alfresco.example.com@AD-SSO.EXAMPLE.COM</endpoint-spn>

Dockerfiles

In a containerized deployment, the updated files will need to be copied to the relevant application containers to overwrite the existing files with the correct configuration. This can be achieved by using the Dockerfile to update each container.

The following files need to be overwritten:

Application File
Alfresco Content Services krb5.conf
  kerberos.keytab
  java.login.config
  java.security
  alfresco-globabl.properties
   
Alfresco Share krb5.conf
  kerberos.keytab
  java.login.config
  java.security
  share-config-custom.xml
   
Alfresco Digital Workspace app.config.json
   
Alfresco Process Services krb5.conf
  kerberos.keytab
  java.login.config
  java.security
  activiti-ldap.properties
   
Alfresco Process Workspace app.config.json

The following is an example Dockerfile used to overwrite the files in the Alfresco Process Services container assuming the new files are in a directory called /config/:

FROM alfresco/process-services:1.10.0
          
COPY config/krb5.conf /etc/krb5.conf
COPY config/kerberos.keytab /etc/kerberos.keytab
COPY config/java.login.config /usr/java/default/conf/security/java.login.config
COPY config/java-aps.security /usr/java/default/conf/security/java.security
COPY config/activiti-ldap.properties /usr/local/tomcat/lib/activiti-ldap.properties

Clustered deployments

If using a clustered deployment on Kubernetes set sessionAffinity: ClientIP on the Alfresco Content Services service so that client requests are passed to the same pod. The Kubernetes documentation provides further information on this setting.

Verify the configuration

To verify that SSO is working correctly after configuring Kerberos, the following are required:

  • A Windows client machine that is part of the domain and has a browser installed that is configured to use Kerberos authentication.

The following is an example sequence to follow to verify that SSO works correctly:

  1. Sign in to the Windows client machine as the user configured in Step 1.
  2. Open a new browser session and navigate to the Alfresco Digital Workspace at the URL http://adw.example.com/workspace and there should be no additional sign in step required.
  3. Create a new tab in the same browser session and navigate to Alfresco Share at the URL http://share.example.com/share and there should be no additional sign in step required.
  4. Create a new tab in the same browser session and navigate to Alfresco Process Services at the URL http://aps.example.com/activiti-app and there should be no additional sign in step required.
  5. Create a new tab in the same browser session and navigate to Alfresco Process Workspace at the URL http://apw.example.com/process-workspace and there should be no additional sign in step required.

Sending feedback to the Alfresco documentation team

You don't appear to have JavaScript enabled in your browser. With JavaScript enabled, you can provide feedback to us using our simple form. Here are some instructions on how to enable JavaScript in your web browser.