Close

Set up authentication and sync

Use this information to manage user authentication. Set up if users should be authenticated with the database, LDAP, SSO etc. Set up how user and group information should be synced (imported) with Community Edition. Users and groups can also be managed from the Share Admin Tools, but it’s more common to sync with a Directory Service, which is discussed here.

Authentication subsystems and authentication chains are discussed first as an understanding of those is necessary when configuring authentication and synchronization.

Authentication subsystems

Authentication is one of the categories of the Community Edition subsystem. An authentication subsystem is a coordinated stack of compatible components responsible for providing authentication and identity-related functionality to Community Edition.

Community Edition offers multiple implementations of the authentication subsystem, each engineered to work with one of the different types of back-end authentication server that you have available in your enterprise.

An authentication subsystem provides the following functions:

  • Password-based authentication for web browsing, Microsoft SharePoint protocol, FTP, and WebDAV
  • Web browser, Microsoft SharePoint protocol, and WebDAV Single Sign-On (SSO)
  • User registry export (the automatic population of the user and authority database)

The main benefits of the authentication subsystem are:

  • Subsystems for all supported authentication types are pre-wired and there is no need to edit template configuration.
  • There is no danger of compatibility issues between sub-components, as these have all been pre-selected.
  • Common parameters are shared and specified in a single place. There is no need to specify the same parameters to different components in multiple configuration files.
  • There is no need to edit the web.xml file. The web.xml file uses generic filters that call into the authentication subsystem. The alfresco.war file is a portable unit of deployment.
  • You can swap from one type of authentication to another by activating a different authentication subsystem.
  • Your authentication configuration will remain standard and, therefore, more manageable to support.
  • Authentication subsystems are easily chained

Note: Some authentication functions can only be targeted at a single subsystem instance in the authentication chain. This is a restriction imposed by the authentication protocols themselves. For this reason, Community Edition targets these ‘direct’ authentication functions at the first member of the authentication chain that has them enabled.

Authentication subsystem types

A number of alternative authentication subsystem types exist for the most commonly used authentication protocols. These are each identified by a unique type name.

The following table shows the authentication subsystem types supplied and the optional features they support.

Type Description Single Sign-On (SSO) support User registry entry
alfrescoNtlm Native Community Edition authentication No No
ldap Authentication and user registry export through the LDAP protocol (for example, OpenLDAP) No Yes
ldap-ad Authentication and user registry export from Active Directory through the LDAP protocol No Yes
kerberos Authentication through a Kerberos realm Yes, SPNEGO No
external Authentication using an external SSO mechanism Yes No

Important: Support for Microsoft Office depends on the authentication mechanism provided by the external subsystem. See External authentication and SSO for more information.

Note: If you’re using a proxy (load balancer) with Kerberos authentication, either:

  • Use the external authentication subsystem and set up the proxy to implement kerberos
  • Set up the kerberos authentication subsystem and create the Service Principal Name (SPN) in Active Directory to include the proxy DNS name

Authentication subsystem components

There are a number of main components in an authentication subsystem.

  • authentication component

    Handles the specifics of talking to the back-end authentication system.

  • authentication Data Access Object (DAO)

    Decides what user management functions are allowed, if any. For example, the ability to create a user.

  • authentication service

    Wraps the authentication component and DAO with higher-level functions.

  • user registry export service (optional)

    Allows Community Edition to obtain user attributes, such as email address, organization, and groups automatically.

  • authentication filters

    Provide form or SSO-based login functions for the following:

      * web client
      * WebDAV
      * web scripts
      * SharePoint protocol
    
  • file server authenticators

    Provide authentication functions for the FTP protocol.

Authentication chain

The authentication subsystem types allow you to integrate Community Edition with the authentication servers in your environment. However, if integrating with only one of these systems is not sufficient, you might want to combine multiple authentication protocols against a collection of servers.

Authentication and identity management functionality is provided by a prioritized list, or chain, of configurable subsystems. The built-in authentication chain is a priority-ordered list of authentication subsystem instances. Community Edition composes together the functions of the subsystems in this list into a more powerful conglomerate.

An authentication subsystem provides the following functionality:

  • Password-based authentication for web browsing, SharePoint, FTP, and WebDAV
  • Web browser and SharePoint Single Sign on (SSO)
  • User register export (the automatic population of the user and authority database)

Several alternative authentication subsystems exist for the most commonly used authentication protocols. These subsystems enable you to tie Community Edition to some of the most widely used authentication infrastructures. If you include more than one of these subsystems in the chain, you can create complex authentication scenarios.

Chained functions

Chained functions combine together functions of more than one subsystem.

For example, when a user login, Community Edition tries to match the user’s credentials against each of the subsystems in the chain in order.

  • If a chain member accepts the credentials, the log in succeeds
  • If no chain member accepts, the log in fails

User registry export is also chained. During a synchronize operation, users and groups are exported from each member of the chain supporting user registry export (that is, those of type LDAP) and imported into Community Edition. Ordering in the chain is used to resolve conflicts between users and groups existing in the same directory.

Default authentication chain

The default product configuration has a simple chain with one member. This is an instance of the alfrescoNtlm subsystem type with and ID of alfrescoNtlm1.

This is expressed in the built-in defaults in the repository.properties file as:

```bash
authentication.chain=alfrescoNtlm1:alfrescoNtlm
```

You can configure the properties of alfrescoNtlm1 using the alfresco-global.properties file.

Configure the authentication chain

You can add to or completely replace the default authentication chain.

Chained functions combine authentication subsystems. The chain is controlled by the authentication.chain global property. When a user logs in, Community Edition tries the user’s credentials against each of the subsystems in the order specified in the chain, until the credentials are accepted (the login is successful) or until each subsystem has been tried (and the login fails).

If Kerberos is configured along with basic authentication in a chain, all the calls to the repository will only support Kerberos. The response from the server only contains the WWW-Authenticate: Negotiate header.

To enable the fallback mechanism for basic authentication, do the following:

  • Set the following property (true, by default):

      kerberos.authentication.sso.fallback.enabled=true
    
  • Send a basic authentication header in all the requests.

      Authorization: Basic <encoded_string>
    

    where <encoded_string> is a base64 encoded username and password separated by a single colon (:). For more information, see Basic Authentication Scheme.

  1. Open the alfresco-global.properties file.

  2. Locate, or if it does not already exist, create the authentication.chain global property.

    This is a comma separated list of the form:

     instance_name1:type1,...,instance_namen:typen
    

    for example,

     authentication.chain=alfrescoNtlm1:alfrescoNtlm
    
  3. Set the property to the required values.

    The default authentication chain specifies one instance of the alfrescoNtlm subsystem type with ID alfrescoNtlm1.

    For example, set the property to the following value:

     alfrescoNtlm1:alfrescoNtlm,ldap1:ldap
    

    When you navigate to the Alfresco:Type=Configuration,Category=Authentication,id1=manager MBean in global property overrides, a new authentication subsystem instance called ldap1 is created and added to the end of the authentication chain.

  4. Save the file.

The following examples specify an advanced Active Directory chain, and an advanced LDAP chain.

You can integrate Community Edition with Active Directory so that:

  • Built-in Community Edition users and Windows users can log in, with Community Edition taking precedence
  • LDAP synchronizes user and group details
  1. Configure the following authentication chain:

     alfrescoNtlm1:alfrescoNtlm,ldap1:ldap
    
  2. Activate chained password-based login and target synchronization (but not authentication) at ldap1 by setting the following properties:

    • ldap1

      ldap.authentication.active=false ldap.synchronization.active=true

You can integrate Community Edition with two LDAP directories so that:

  • User passwords are validated directly against the LDAP servers for web, SharePoint and FTP login
  • LDAP is used to synchronize user and group details from both directories
  • Users in the first directory, ldap1, take precedence over those in the second directory, ldap2

Note: If you’re only using a single LDAP provider in your authentication chain, the properties can be included in the alfresco-global.properties file. But if you need to include the configuration for more than one LDAP provider, then you need to separate the properties in distinct subsystem configuration in <configRootShare>/classes/alfresco/subsystems/Authentication/<LDAP Provider Name>/ldap-authentication.properties.

  1. In the alfresco-global.properties, specify this setting:

     authentication.chain=ldap1:ldap,ldap2:ldap
    
  2. Copy ldap-authentication.properties to both the <classpathRoot>/alfresco/extension/subsystems/Authentication/ldap/ldap1/ldap-authentication.properties and <classpathRoot>/alfresco/extension/subsystems/Authentication/ldap/ldap2/ldap-authentication.properties files.
  3. Edit the properties for ldap1 and ldap2 with appropriate settings to complete the configuration. See LDAP configuration properties for information on each of the properties.

Configure authentication subsystems

A number of examples demonstrate how to express various authentication configuration requirements in subsystem instances in the authentication chain. They also explain how the authentication chain integrates the functions of multiple subsystem instances into a more powerful conglomerate, letting you cater for even the most complex authentication scenarios.

These examples demonstrate the flexibility and power of an authentication chain. You can combine the strengths of a variety of different authentication protocols and keep the user database synchronized almost transparently.

The authentication configuration examples adopt the following structured approach:

  1. Decide the authentication chain composition (required subsystem types, instance names, order of precedence) and express this in the alfresco-global.properties file.
  2. For each subsystem instance:
    1. Locate the properties files for its subsystem type. These properties files define the configurable properties for that subsystem type and their default values.
    2. Create a folder named after the subsystem instance under the extension folders.
    3. Copy the properties files into your new folder.
    4. Edit the properties files to record the required configuration of the subsystem instance.

Configure external authentication

Use this information to enable the external authentication subsystem using the alfresco-global.properties file.

Configuring/enabling external authentication subsystem using the alfresco-global.properties file:

  1. Open the alfresco-global.properties file.
  2. Set the following properties to enable external authentication:

     ```bash
     authentication.chain=external1:external
     external.authentication.proxyUserName=
     external.authentication.enabled=true
     external.authentication.defaultAdministratorUserNames=admin
     external.authentication.proxyHeader=X-Alfresco-Remote-User
     ```
    

    Note: The default setting for external.authentication.proxyUserName is alfresco-system. This should only be specified if you’re using SSL. See External authentication and SSO for more information.

  3. Save the alfresco-global.properties file.
  4. Restart the Community Edition server.

For more information on the external authentication properties, see external configuration properties.

External authentication and SSO

Use this information to understand what we mean by External Authentication and how Single Sign-On (SSO) can be used with this authentication type.

What is external authentication?

External authentication uses the Central Authentication Service (CAS), which enables Single Sign-On (SSO), and allows a user to authenticate with a CAS, instead of directly with Community Edition. For example, this might be using the mod_cas Apache module. For more information about mod_cas, see CAS Apache Module.

CAS is usually used with a proxy, for example, the Apache mod_proxy module.

External authentication is set with the authentication.chain parameter in your alfresco-global.properties file to use the external authentication subsystem.

To provide SSO, an external authentication system (or CAS) can be integrated Community Edition. For example, the identity of the logged-in user is extracted by the CAS, passed to Community Edition servlets and extracted using the HttpServletRequest.getRemoteUser() method. As a result, when a user connects to Share they’re shown their user dashboard, but won’t see the Share login page.

The subsystem also allows a proxy user to be configured, so that requests made through this proxy user are made in the name of an alternative user, whose name is carried in a configured HTTP request header. This allows, for example, the Alfresco Share application and other Surf applications to act as a client to an SSO-protected Community Edition application and assert the user name in a secure manner.

A disabled user can still login to Alfresco using external authentication. If the external control synchronization is configured appropriately, a user’s status of disabled can be synchronized via the LDAP directory. In summary, if an administrator wants to prevent a user from authenticating to Alfresco, then the user should be disabled in Alfresco either directly, or in the LDAP directory that is referenced by the ldap.synchronization.userAccountStatusProperty property.

If troubleshooting a user login issue, first check Alfresco to see if the user account is enabled, and then step through the authentication chain to see if the user can successfully authenticate using one of the members of the chain.

For example, if external authentication is the only authentication system in the chain and auto-create missing people is enabled, then the users will be able to authenticate automatically. In other words, users that are not already synchronized to Alfresco will be auto-created and enabled, by default. If the user is subsequently set to disabled (either directly via APIs or via LDAP synchronization), then the user will no longer be able to access Alfresco. The user will also appear as disabled in Share > Admin Tools > Users.

Note: Activating external authentication makes Community Edition accept external authentication tokens. Make sure that no untrusted direct access to Community Edition HTTP or AJP ports is allowed.

Here are two scenarios where external authentication is configured with Community Edition and Share. In both scenarios, an HTTP or HTTPS request is sent to an authentication proxy. If authentication is OK, the proxy passes the request to Share using the AJP protocol.

In the first scenario, the Share endpoint-url (http://localhost:8080/alfresco/wcs) sends the request directly to Community Edition using HTTP and a User Header. No certificate is used and the external.authentication.proxyUserName is blank:

```bash
external.authentication.proxyUserName=
```

Community Edition trusts the header (defined by external.authentication.proxyHeader) sent by Share. This scenario is typically used if you want to prohibit direct access to Community Edition and enforce using the proxy, for example, by using firewall rules to the proxy.

external-direct

In the second scenario, the Share endpoint-url (http://your.server.com/alfresco/wcs) sends the request back to Apache, using HTTP and a User Header (defined by external.authentication.proxyHeader), and a certificate. external.authentication.proxyUserName is set:

```bash
external.authentication.proxyUserName=alfresco-system
```

Apache uses the certificate to check that the request is coming from Share with the correct user (that is, the value of external.authentication.proxyUserName) and forwards the request to Community Edition. This scenario is typically used to allow direct access to Share, using HTTPS and the originator (the proxy) sends a client certificate when establishing the SSL tunnel.

external-indirect

Default authentication chain and Configuring external authentication provide more information on the parameter and the external authentication subsystem.

Using the external authentication subsystem means that:

  • The complexity of authentication moves to an external software layer (a proxy). Community Edition listens to the authenticated user name that it receives using a custom HTTP header, or it reads the CGI REMOTE_USER variable that can be passed using the AJP protocol.
  • Most of the responsibility for authentication is not controlled by Community Edition, but controlled by the external software layer. Unless there is a problem when the authenticated user name is transmitted, the issue is located in the external software layer. In these cases, work with your proxy vendor or implementer of the authentication proxy to resolve the issue.

SSO is a property of an authentication scheme. You can use more than one method to set up SSO. For example:

  • If you’re using Kerberos, you can use either the kerberos authentication subsystem, or the external authentication subsystem with a proxy that handles Kerberos authentication.
  • If you’re using CAS, you must use the external authentication subsystem with a proxy that handles CAS authentication.

In summary, external authentication and SSO are not interdependent: you can set up external authentication that is not SSO (for example, using an Apache proxy with a mod_auth_basic setting), and you can set up an SSO system that is not using the external authentication subsystem (for example, using the kerberos authentication subsystem).

See Authentication subsystem types for a listing of the authentication subsystems and the features that they support.

There are some limitations when using Microsoft SharePoint support, as provided by Alfresco Office Services, with the Alfresco external authentication subsystem. External authentication can work well when using a web browser client, but not when using the MS Office client. This is because no authentication information is sent with the file URL, and MS Office does not store authentication information, so starts a new authentication process.

An example of this is when using CAS. CAS authenticates using an HTML form and a web browser that follows an HTTP redirect. The web authentication works correctly, but MS Office authentication won’t work because it does not permit completion of the form. This problem is caused by the limited set of authentication protocols that MS Office supports.

MS Office supports the following authentication mechanisms:

  • HTTP Basic
  • HTTP Digest
  • NTLM
  • Kerberos

NTLM and Kerberos can be used in an SSO environment.

For more information about Alfresco Office Services limitations, see Considerations when using Alfresco Office Services.

External configuration properties

The external subsystem supports a number of properties.

Property Description
external.authentication.enabled A Boolean property that when true indicates that this subsystem is active and will trust remote user names asserted to it by the application server.
external.authentication.defaultAdministratorUserNames A comma separated list of user names who should be considered administrators by default.
external.authentication.proxyUserName The name of the remote user that should be considered the proxy user. Requests made by this user will be made under the identity of the user named in the HTTP Header indicated by the external.authentication.proxyHeader property. If not set, then the HTTP Header indicated by the external.authentication.proxyHeader property is always assumed to carry the user name.

Note: The default setting for external.authentication.proxyUserName is alfresco-system, but this should only be specified if you’re using SSL. See External authentication and SSO for more information.
external.authentication.proxyHeader The name of the HTTP header that carries the name of a proxied user. The default is X-Alfresco-Remote-User, as used by Share.
external.authentication.userIdPattern An optional regular expression to be used to extract a user ID from the HTTP header. The portion of the header matched by the first bracketed group in the regular expression will become the user name. If not set (the default), then the entire header contents are assumed to be the proxied user name.

For example, use the following setting:

external.authentication.userIdPattern=^(.+)@.+$

This regular expression will extract everything before the @ sign. For example: john.doe@alfresco.com => john.doe or john@alfresco.com => john.

Configure Alfresco Share to use an external SSO

Alfresco Share can be configured to accept a user name from an HTTP header provided by an external authentication system for Single Sign on (SSO).

This task assumes that you’ve already set up external authentication, as specified in External configuration properties.

  1. Go to the Share <web-extension> directory.

  2. Open the share-config-custom.xml file.

  3. Uncomment the second <config evaluator="string-compare" condition="Remote"> section.

    Note: There are multiple Remote configuration sections in this file. If you have multiple sections in a configuration file, then the last section is used.

    In this uncommented Remote section:

    1. Set the alfrescoHeader connector to use the same value that you defined for your external SSO property in External configuration properties:

      Change the <userHeader> property to the same value as the external.authentication.proxyHeader. This sets the same HTTP header value for both Alfresco Share and the repository.

    2. Set the alfresco endpoint to use the alfrescoHeader connector:

      1. Change the <connector-id> value from alfrescoCookie to alfrescoHeader
      2. Change the <endpoint-url> value to your Alfresco server URL; for example, http://localhost:8080/alfresco/s.

    Note: Below is an example file. Review the entries for userHeader, connector-id and endpoint-url.

     ```xml
       <!--
             Overriding endpoints to reference an Alfresco server with external SSO
             enabled
             NOTE: If utilizing a load balancer between web-tier and repository
             cluster,the "sticky sessions" feature of your load balancer must be used.
    
             NOTE: If alfresco server location is not localhost:8080 then also combine
             changes from the"example port config" section below.
             *Optional* keystore contains SSL client certificate + trusted CAs.
             Used to authenticate share to an external SSO system such as CAS
             Remove the keystore section if not required.
    
             NOTE: For Kerberos SSO rename the "KerberosDisabled" condition above to
             "Kerberos"
    
             NOTE: For external SSO, switch the endpoint connector to "AlfrescoHeader"
                 and set the userHeader to the name of the HTTP header
                 that the external SSO uses to provide the authenticated user name.
     -->
    
     <config evaluator="string-compare" condition="Remote">
         <remote>
    
             <connector>
                 <id>alfrescoHeader</id>
                 <name>Alfresco Connector</name>
                 <description>Connects to an Alfresco instance using header and cookie-based authentication</description>
                 <class>org.alfresco.web.site.servlet.SlingshotAlfrescoConnector</class>
                 <userHeader>X-Alfresco-Remote-User</userHeader>
             </connector>
    
             <endpoint>
                 <id>alfresco</id>
                 <name>Alfresco - user access</name>
                 <description>Access to Alfresco Repository WebScripts that require user authentication</description>
                 <connector-id>alfrescoHeader</connector-id>
                 <endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>
                 <identity>user</identity>
                 <external-auth>true</external-auth>
             </endpoint>
    
             <endpoint>
                 <id>alfresco-feed</id>
                 <parent-id>alfresco</parent-id>
                 <name>Alfresco Feed</name>
                 <description>Alfresco Feed - supports basic HTTP authentication via the EndPointProxyServlet</description>
                 <connector-id>alfrescoHeader</connector-id>
                 <endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>
                 <identity>user</identity>
                 <external-auth>true</external-auth>
             </endpoint>
    
             <endpoint>
                 <id>alfresco-api</id>
                 <parent-id>alfresco</parent-id>
                 <name>Alfresco Public API - user access</name>
                 <description>Access to Alfresco Repository Public API that require user authentication.
                             This makes use of the authentication that is provided by parent 'alfresco' endpoint.</description>
                 <connector-id>alfrescoHeader</connector-id>
                 <endpoint-url>http://localhost:8080/alfresco/api</endpoint-url>
                 <identity>user</identity>
                 <external-auth>true</external-auth>
             </endpoint>
         </remote>
     </config>
     ```
    

    This is another example file, using the cookie session based endpoint.

     ```xml
     <!--
             Overriding endpoints to reference an Alfresco server with external SSO
             enabled
             NOTE: If utilzing a load balancer between web-tier and repository
             cluster,the "sticky sessions" feature of your load balancer must be used.
    
             NOTE: If alfresco server location is not localhost:8080 then also combine
             changes from the"example port config" section below.
             *Optional* keystore contains SSL client certificate + trusted CAs.
             Used to authenticate share to an external SSO system such as CAS
             Remove the keystore section if not required.
    
             NOTE: For Kerberos SSO rename the "KerberosDisabled" condition above to
             "Kerberos"
    
             NOTE: For external SSO, switch the endpoint connector to "AlfrescoHeader"
                 and set the userHeader to the name of the HTTP header
                 that the external SSO uses to provide the authenticated user name.
     -->
    
     <config evaluator="string-compare" condition="Remote">
         <remote>
             <ssl-config>
                 <keystore-path>alfresco/web-extension/alfresco-system.p12</keystore-path>
                 <keystore-type>pkcs12</keystore-type>
                 <keystore-password> alfresco-system</keystore-password>
    
                 <truststore-path> alfresco/web-extension/ssl-truststore</truststore-path>
                 <truststore-type>JCEKS</truststore-type>
                 <truststore-password>password</truststore-password>
    
                 <verify-hostname>true</verify-hostname>
             </ssl-config>
    
             <connector>
                 <id>alfrescoCookie</id>
                 <name>Alfresco Connector</name>
                 <description>Connects to an Alfresco instance using cookie-based
                             authentication
                 </description>
                 <class>org.alfresco.web.site.servlet.SlingshotAlfrescoConnector</class>
             </connector>
    
             <endpoint>
                 <id>alfresco</id>
                 <name>Alfresco - user access</name>
                 <description>Access to Alfresco Repository WebScripts that require user authentication</description>
                 <connector-id>alfrescoCookie</connector-id>
                 <endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>
                 <identity>user</identity>
                 <external-auth>true</external-auth>
             </endpoint>
    
             <endpoint>
                 <id>alfresco-api</id>
                 <parent-id>alfresco</parent-id>
                 <name>Alfresco Public API - user access</name>
                 <description>Access to Alfresco Repository Public API that require user authentication.
                             This makes use of the authentication that is provided by parent 'alfresco' endpoint.</description>
                 <connector-id>alfrescoCookie</connector-id>
                 <endpoint-url>http://localhost:8080/alfresco/api</endpoint-url>
                 <identity>user</identity>
                 <external-auth>true</external-auth>
             </endpoint>
         </remote>
     </config>
     ```
    
  4. Save the file and then restart Share.

    Activating external authentication makes Community Edition accept external authentication tokens, make sure that no untrusted direct access to Alfresco HTTP or AJP ports is allowed.

You have configured Share to use an external SSO.

Set SSO with client certificates

Use this information to set up SSO with client certificates.

  1. Setup Apache as proxy server in front of Community Edition and configure it to use SSL as described in Configuring SSL for a production environment.

  2. Activate external authentication as described in Configuring external authentication.

  3. To extend the SSL configuration in httpd.conf to request client authentication and forward the user name as HTTP header, add this configuration to the <VirtualHost> node:

     ```bash
     SSLVerifyClient         require
     SSLCACertificateFile    /path/to/your/enterprise-CA.pem
     RequestHeader           append  X-Alfresco-Remote-User  "%{SSL_CLIENT_S_DN_Email}e"
     ```
    

    This will accept all client certificates that have been signed by the CA identified by the certificate stored in enterprise-CE.pem. It will use the email address stored in this certificate as the user name.

Configure alfrescoNtlm

alfrescoNtlm is the subsystem configured by default in the Community Edition authentication chain. It performs authentication based on user and password information stored in the repository database.

The alfrescoNtlm subsystem supports the following properties:

Property Description
alfresco.authentication.allowGuestLogin Specifies whether to allow guest access.

Note: If you add extra administrator users in the authority-services-context.xml file and are using alfrescoNtlm, the extra users (other than the admin user) will no longer have administrator rights until you add them to the ALFRESCO_ADMINISTRATORS group.

Configure LDAP

An LDAP subsystem supports two main functions:

  • user authentication - checking a user’s ID and password using an LDAP bind operation
  • user registry export - exposing information about users and groups to the synchronization subsystem

Either of these functions can be used in isolation or in combination. When LDAP authentication is used without user registry export, default Community Edition person objects are created automatically for all those users who successfully login. However, they won’t be populated with attributes without user registry export enabled. LDAP user registry export is most likely to be used without LDAP authentication when chained with other authentication subsystems. For example, Kerberos against Active Directory, and possibly Samba on top of OpenLDAP.

The user registry export function assumes that groups are stored in LDAP as an object that has a repeating attribute, which defines the distinguished names of other groups, or users. This is supported in the standard LDAP schema using the groupOfNames type. See the example LDIF file in OpenLDAP tips.

LDAP configuration properties

Both the ldap and ldap-ad subsystem types support the following configurable properties.

Note: The defaults for ldap are typical for OpenLDAP and Oracle Directory Server, and the defaults for ldap-ad are typical for Active Directory.

LDAP authentication properties

Note: The create.missing.people property in the Alfresco global properties file is set to true by default in Alfresco. This can have the affect of creating users unexpectedly. To avoid this you can override the default setting by changing the property to create.missing.people property=false.

Property Description
ldap.authentication.active This Boolean flag, when true enables use of this LDAP subsystem for authentication. It might be that this subsystem should only be used for user registry export, in which case this flag should be set to false and you would have to chain an additional subsystem such kerberos to provide authentication functions.
ldap.authentication.java.naming.referral This property specifies how the referrals sent by AD in the search results are handled by Alfresco. The recommended values are:

ignore

If ldap.authentication.java.naming.referral=ignore, the following exception will be thrown when a referral is encountered:

javax.naming.PartialResultException: Unprocessed Continuation Reference(s); remaining name 'dc=alfness,dc=com'

follow

If ldap.authentication.java.naming.referral=follow, Alfresco will automatically follow the referral. To be successful, make sure Alfresco can access the referred server. If this property has not been set, then the default is to follow the referrals.

throw

If ldap.authentication.java.naming.referral=throw, the following exception will be thrown:

com.sun.jndi.ldap.LdapReferralException: Continuation Reference; remaining name 'dc=alfness,dc=com'

For more information, see Referrals in the JNDI.
ldap.authentication.java.naming.security.authentication The mechanism to use to authenticate with the LDAP server. This should be set to one of the standard values listed here or one of the values supported by the LDAP provider. Oracle’s LDAP provider supports the following SASL mechanisms. The recommended values are:

simple

The basic LDAP authentication mechanism requiring the user name and password to be passed over the wire unencrypted. You might be able to add SSL for secure access, otherwise this should only be used for testing.

DIGEST-MD5

More secure RFC 2831 Digest Authentication. Note that with Active Directory, this requires your user accounts to be set up with reversible encryption, not the default setting.
ldap.authentication.java.naming.read.timeout Specifies the read timeout in milliseconds for LDAP operations. If Community Edition can’t get a LDAP response within that period, it aborts the read attempt. The integer should be greater than zero. If the integer is less than or equal to zero, no read timeout is specified, which is equivalent to waiting for the response infinitely until it is received.
ldap.authentication.userNameFormat Specifies how to map the user identifier entered by the user to that passed through to LDAP.

If set to an empty string (the default for the ldap subsystem), an LDAP query involving ldap.synchronization.personQuery and ldap.synchronization.userIdAttributeName will be performed to resolve the DN from the user ID dynamically. This allows directories to be structured and does not require the user ID to appear in the DN.

If set to a non-empty value, the substring %s in this value will be replaced with the entered user ID to produce the ID passed to LDAP. This restricts LDAP user names to a fixed format. The recommended format of this value depends on your LDAP server.

Active Directory

There are two alternatives:

User Principal Name (UPN)

These are generally in the format of <sAMAccountName>@<UPN Suffix>. If you’re unsure of the correct suffix to use, use an LDAP browser, such as Softerra, to browse to a user account and find its userPrincipalName attribute. For example:

%s@domain

DN

This requires the user to authenticate with part of their DN, so might require use of their common name (CN) rather than their login ID. It also might not work with structured directory layouts containing multiple organization units (OUs). For example:

cn=%s,ou=xyz,dc=domain

OpenLDAP

The format used depends on the value chosen for ldap.authentication.java.naming.security.authentication.

simple

This must be a DN and would be something like the following:

uid=%s,ou=People,dc=company,dc=com

DIGEST-MD5

Use this value to pass through the entered value as-is:

%s

When authenticating against LDAP, users are not always in the same subtree of LDAP. In this situation, it is necessary to support authentication against multiple branches of LDAP. For example, some users who can authenticate using cn=%s,ou=myCity,ou=myState,o=myCompany but others can authenticate using cn=%s,ou=ANOTHERCity,ou=myState,o=myCompany. Set ldap.authentication.userNameFormat to be empty (the default), and then it’ll derive a query from your personQuery to look up a user by UID. This ensures that you can support users in any branch structure.

ldap.authentication.allowGuestLogin Identifies whether to allow unauthenticated users to log in as the ‘guest’ user.
ldap.authentication.java.naming.factory.initial The LDAP context factory to use. There is no need to change this unless you do not want to use the default Oracle LDAP context factory.
ldap.authentication.java.naming.provider.url The URL to connect to the LDAP server, containing its name and port. The standard ports for LDAP are 389 (and 636 for SSL). For example: ldap://openldap.domain.com:389
ldap.authentication.escapeCommasInBind Escape commas in the entered user ID when authenticating with the LDAP server? Useful when using simple authentication and the CN is part of the DN and contains commas.
ldap.authentication.escapeCommasInUid Escape commas in the entered user ID when deriving an internal user ID. Useful when using simple authentication and the CN is part of the DN and contains commas, and the escaped \, is pulled in as part of a synchronize operation. If this option is set to true it’ll break the default home folder provider as space names can’t contain \ (backslash character).
ldap.authentication.defaultAdministratorUserNames A comma separated list of user names to be considered administrators by default. If you’re using LDAP for all your users, this maps an LDAP user to be an administrator user. This administrator user can then configure the other admin users or groups by add users and/or groups to the ALFRESCO_ADMINISTRATORS group using the Share Admin Tools.

If you already have a group of administrators in LDAP, you can add the required LDAP group(s)to the ALFRESCO_ADMINISTRATORS group. This can be set without a server restart.
ldap.authentication.java.naming.security.protocol This sets the security protocol to use for connecting with the LDAP server. This property has a single value of ssl. Set this property to ssl if the configuration of truststore is required. Leave this property unused if the truststore configuration is not required (the connection is not secured).

Note: In order to enable SSL, import the SSL certificate from the LDAP provider into a Java truststore and the truststore.path, truststore.passphrase, and truststore.typeproperties. To download the certificate, use the following command:

openssl s_client -connect ldap.foxpass.com:636 > my-ldap.crt

To import the certificate into a new keystore, use the following command:

keytool -importcert -alias LDAP.HOST.FQDN -file my-ldap.crt -keystore my-keystore-filename -storepass my-pass -storetype JCEKS
ldap.authentication.truststore.path The path to the truststore file on the file system.
ldap.authentication.truststore.passphrase The password for the truststore.
ldap.authentication.truststore.type The type of the truststore, as specified when generating with keytool or another keystore manager. Must be a standard Java Cryptography Keystore.

LDAP synchronization properties

Property Description
ldap.synchronization.active This flag enables use of the LDAP subsystem for user registry export functions and decides whether the subsystem will contribute data to the synchronization subsystem. It might be that this subsystem should only be used for authentication, in which case this flag should be set to false.
ldap.synchronization.java.naming.security.authentication The authentication mechanism used to connect to the LDAP server when performing user registry exports. In versions earlier than 3.4 versions, this property was the same as ldap.authentication.java.naming.security.authentication. The property should use one of the standard values covered in the Oracle documentation or one of the values supported by the LDAP provider. Oracle’s LDAP provider supports the SASL mechanisms. Recommended values are:

none

Use this option if your LDAP server supports connection without a password. Set to none to allow synchronization by using anonymous bind (note that you’ll not also need to set the following two properties). 

simple

This option is the basic LDAP authentication mechanism requiring the user name and password to be passed over the wire unencrypted. You might be able to add SSL for secure access; otherwise, use this option for testing only.

DIGEST-MD5

This option provides a more secure (RFC 2831) digest authentication. With Active Directory, this requires your user accounts to be set up with reversible encryption, not the default setting.
ldap.synchronization.java.naming.security.principal The LDAP user to connect as for the export operation, if one is required by the ldap.synchronization.java.naming.security.authentication authentication mechanism. This should be in the same format as ldap.authentication.userNameFormat but with a real user ID instead of %s.

This is the default principal to use (only used for LDAP sync when ldap.synchronization.java.naming.security.authentication=simple): ldap.synchronization.java.naming.security.principal=cn\=Manager,dc\=company,dc\=com 
ldap.synchronization.java.naming.security.credentials The password for this user, if required. The password for the default principal (only used for LDAP sync when ldap.synchronization.java.naming.security.authentication=simple)  ldap.synchronization.java.naming.security.credentials=secret 
ldap.synchronization.queryBatchSize If set to a positive integer, this property indicates that RFC 2696 paged results should be used to split query results into batches of the specified size. This overcomes any size limits imposed by the LDAP server. The default value of 1000 matches the default result limitation imposed by Active Directory. If set to zero or less, paged results won’t be used.
ldap.synchronization.groupQuery The query to select all objects that represent the groups to export. This query is used in full synchronization mode, which by default is scheduled every 24 hours.
ldap.synchronization.groupDifferentialQuery The query to select objects that represent the groups to export that have changed since a certain time. Should use the placeholder {0} in place of a timestamp in the format specified by ldap.synchronization.timestampFormat. The timestamp substituted will be the maximum value of the attribute named by ldap.synchronization.modifyTimestampAttributeName the last time groups were queried. This query is used in differential synchronization mode, which by default is triggered whenever a user is successfully authenticated that does not yet exist.
ldap.synchronization.personQuery The query to select all objects that represent the users to export. This query is used in full synchronization mode, which by default is scheduled every 24 hours.
ldap.synchronization.personDifferentialQuery The query to select objects that represent the users to export that have changed since a certain time. Should use the placeholder {0} in place of a timestamp in the format specified by ldap.synchronization.timestampFormat. The timestamp substituted will be the maximum value of the attribute named by ldap.synchronization.modifyTimestampAttributeName the last time users were queried. This query is used in differential synchronization mode, which by default is triggered whenever a user is successfully authenticated that does not yet exist.
ldap.synchronization.groupSearchBase The DN below which to run the group queries.
ldap.synchronization.userSearchBase The DN below which to run the user queries.
ldap.synchronization.modifyTimestampAttributeName The name of the operational attribute recording the last update time for a group or user.
ldap.synchronization.timestampFormat The timestamp format. This varies between directory servers.

Active Directory

yyyyMMddHHmmss'.0Z'

OpenLDAP

yyyyMMddHHmmss'Z'
ldap.synchronization.userIdAttributeName The attribute name on people objects found in LDAP to use as the uid.
ldap.synchronization.userFirstNameAttributeName The attribute on person objects in LDAP to map to the first name property.
ldap.synchronization.userLastNameAttributeName The attribute on person objects in LDAP to map to the last name property.
ldap.synchronization.userEmailAttributeName The attribute on person objects in LDAP to map to the email property.
ldap.synchronization.userOrganizationalIdAttributeName The attribute on person objects in LDAP to map to the organizational ID property.
ldap.synchronization.defaultHomeFolderProvider The default home folder provider to use for people created using LDAP import.
ldap.synchronization.groupIdAttributeName The attribute on LDAP group objects to map to the group name.
ldap.synchronization.groupType The group type in LDAP. The default value is groupOfNames.
ldap.synchronization.personType The person type in LDAP. The default value is inetOrgPerson. This value only need changing if the objectclass for mapping groups and users differs from the default provided by Community Edition. Check the documentation of the LDAP server being accessed.
ldap.synchronization.groupMemberAttributeName The attribute in LDAP on group objects that defines the DN for its members.

LDAP connection pooling configuration properties

Property Description
ldap.synchronization.com.sun.jndi.ldap.connect.pool Use this property to enable or disable connection pooling for synchronization.
ldap.pooling.com.sun.jndi.ldap.connect.pool.authentication A list of space-separated authentication types of connections that may be pooled. Valid types are none, simple, and DIGEST-MD5.
ldap.pooling.com.sun.jndi.ldap.connect.pool.debug A string that indicates the level of debug output to produce. Valid values are fine (trace connection creation and removal) and all (all debugging information).
ldap.pooling.com.sun.jndi.ldap.connect.pool.initsize The string representation of an integer that represents the number of connections per connection identity to create when initially creating a connection for the identity.
ldap.pooling.com.sun.jndi.ldap.connect.pool.maxsize The string representation of an integer that represents the maximum number of connections per connection identity that can be maintained concurrently. An empty value means no maximum size.
ldap.pooling.com.sun.jndi.ldap.connect.pool.prefsize The string representation of an integer that represents the preferred number of connections per connection identity that should be maintained concurrently. An empty value means no preferred size.
ldap.pooling.com.sun.jndi.ldap.connect.pool.protocol A list of space-separated protocol types of connections that may be pooled. Valid types are plain and ssl.
ldap.pooling.com.sun.jndi.ldap.connect.pool.timeout The string representation of an integer that represents the number of milliseconds that an idle connection may remain in the pool without being closed and removed from the pool. # Empty value means no timeout, connection stays in pool forever. Bad connections are automatically detected and removed from the pool by the LDAP provider
ldap.pooling.com.sun.jndi.ldap.connect.timeout The string representation of an integer that represents the number of milliseconds to specify how long to wait for a pooled connection. An empty value means the application will wait indefinitely.

Check supported SASL authentication mechanisms

You can check which Simple Authentication and Security Layer (SASL) authentication mechanisms are supported.

  1. Using an LDAP browser, such as the one from Softerra, check the values of the supportedSASLMechanisms attributes on the root node of your LDAP server.

    Note: The simple authentication method won’t be reported because it’s not a SASL mechanism.

  2. If you use OpenLDAP, you can also query using ldapsearch. For example:

     ```bash
     ldapsearch -h localhost -p 389 -x -b "" -s base -LLL supportedSASLMechanisms
     dn:
     supportedSASLMechanisms: DIGEST-MD5
     supportedSASLMechanisms: NTLM
     supportedSASLMechanisms: CRAM-MD5
     ```
    

Synchronize user account status

Use this information to synchronize the enabled or disabled directory user status after an LDAP sync.

Different LDAP directories store data in different formats. For example, Active Directory has an attribute called userAccountControl where the second bit (0x2) is an ACCOUNTDISABLE flag, Oracle Directory Server has an attribute called pwdAccountLockedTime, and LDAP systems derived from Netscape Directory Server (NDS) have a nsAccountLock attribute.

The values of these attributes need to be mapped onto a boolean property on the cm:person node. To do this, configure the attributes as follows:

  1. Download the default-synchronization.properties file.
  2. Open the <classpathRoot>/alfresco-global.properties file.
  3. Add one of these entries to your configuration, depending on the directory server used. For example:

    • For LDAP-AD, add the following properties to the alfresco-global.properties file:

      synchronization.externalUserControl=true
      synchronization.externalUserControlSubsystemName=ldap1
      
    • For OpenLDAP, add the following properties to the alfresco-global.properties file:

        synchronization.externalUserControl=true
        synchronization.externalUserControlSubsystemName=ldap1
        ldap.synchronization.userAccountStatusProperty=pwdAccountLockedTime
        ldap.synchronization.disabledAccountPropertyValue=000001010000Z
      
    • For Netscape Directory Server systems (Oracle, Red Had, 389 DS), add the following properties to the alfresco-global.properties file:

        synchronization.externalUserControl=true
        synchronization.externalUserControlSubsystemName=ldap1
        ldap.synchronization.userAccountStatusProperty=nsAccountLock
        ldap.synchronization.disabledAccountPropertyValue=true
      
  4. Copy this file into the <extension> directory.
  5. Read the above mentioned property from LDAP and set it in ldap.synchronization.userAccountStatusProperty. For example:

     ldap.synchronization.userAccountStatusProperty=nsAccountLock
    
  6. The next configuration is how to process the value of that property into a boolean true/false value. To do that there is an adapter bean userAccountStatusInterpreter that is plugged into the userRegistry bean via spring.

    This configuration parameter ldap.synchronization.userAccountStatusInterpreter can either be ldapadUserAccountStatusInterpreter or ldapUserAccountStatusInterpreter. This setting instructs the system how to process the value for ldap.synchronization.userAccountStatusProperty.

    • For LDAP-AD:

        ldap.synchronization.userAccountStatusInterpreter=ldapadUserAccountStatusInterpreter
      
    • For non-AD LDAP:

        ldap.synchronization.userAccountStatusInterpreter=ldapUserAccountStatusInterpreter
      

Example: authentication and synchronization with one ldap-ad subsystem

This example addresses the more advanced goal of delegating authentication responsibility to a centralized directory server. Most organizations maintain their user database in a directory server supporting the LDAP protocol, such as Active Directory or OpenLDAP.

When integrated with an LDAP server, Community Edition can delegate both the password checking and account setup to the LDAP server, thus opening up Community Edition to your entire enterprise. This avoids the need for an administrator to manually set up user accounts or to store passwords outside of the directory server.

To integrate with a directory server, you simply need to include an instance of the ldap or ldap-ad subsystem types in the authentication chain. Both subsystem types offer exactly the same capabilities and should work with virtually any directory server supporting the LDAP protocol. Their only differences are the default values configured for their attributes. The ldap type is pre-configured with defaults appropriate for OpenLDAP, whereas ldap-ad is pre-configured with defaults appropriate for Active Directory.

There are two choices in this scenario: replace or add to the authentication chain.

  • Replace the authentication chain

    You could remove alfinst from the previous example and instead add an instance of ldap-ad. This would hand over all authentication responsibility to Active Directory and would mean that the built-in accounts, such as admin and guest, could not be used.

    In this scenario, it would be important to configure at least one user who exists in Active Directory as an administrator and enable the guest account in Active Directory, if guest access were required.

  • Add to the authentication chain

    You could instead supplement the existing capabilities of alfinst by inserting an ldap-ad instance before or after alfinst in the chain. This means that you could use the built-in accounts alongside those accounts in the directory server.

    In this scenario, where you chose to position your ldap-ad instance in the chain determines how overlaps or collisions between user accounts are resolved. If an admin account existed in both Community Edition and Active Directory, then admin would be Community Edition if alfinst came first, or Active Directory if the ldap-ad instance came first.

This example uses an Active Directory server and configures an instance of the ldap-ad subsystem.

  1. This example uses the second option to append an instance of ldap-ad to the authentication chain. This instance name is ldap1 and is declared by changing the authentication.chain property in the alfresco-global.properties file.

  2. Undo any previous modifications to alfinst.

  3. Add the following properties to alfresco-global.properties to configure the ldap-ad authentication subsystem:

     authentication.chain=alfinst:alfrescoNtlm,ldap1:ldap-ad
    
     ldap.authentication.allowGuestLogin=false
     ldap.authentication.userNameFormat=%s@domain.com
     ldap.authentication.java.naming.provider.url=ldap://domaincontroller.domain.com:389
     ldap.authentication.defaultAdministratorUserNames=Administrator,alfresco
     ldap.synchronization.java.naming.security.principal=alfresco@domain.com
     ldap.synchronization.java.naming.security.credentials=secret
     ldap.synchronization.groupSearchBase=ou=Security Groups,ou=Alfresco\,dc=domain,dc=com
     ldap.synchronization.userSearchBase=ou=User Accounts,ou=Alfresco,dc=domain,dc=com
    

    There are a large number of configurable properties for ldap-ad, which demonstrates the flexibility of Alfresco’s LDAP infrastructure. Luckily, because ldap-ad already has sensible defaults configured for a typical Active Directory set up, there are only a few edits you must make to tailor the subsystem instance to your needs.

    The following table is a summary of the settings that have been changed:

    Property Description
    ldap.authentication.allowGuestLogin Enables / disables unauthenticated access.
    ldap.authentication.userNameFormat A template that defines how user IDs are expanded into Active Directory User Principal Names (UPNs) containing a placeholder %s, which stands for the unexpanded user ID. A UPN generally consists of the user’s account ID followed by an @ sign and then the domain’s UPN suffix. You can check the appropriate UPN suffix for your domain by connecting to the directory with an LDAP browser, browsing to a user account, and looking at the value of the userPrincipalName attribute.
    ldap.authentication.java.naming.provider.url An LDAP URL containing the host name and LDAP port number (usually 389) of your Active Directory server
    ldap.authentication.defaultAdministratorUserNames A list of user IDs who should be given administrator privileges by default. Another administrator can include more users as administrators by adding those users to the ALFRESCO_ADMINISTRATORS group.
    ldap.synchronization.java.naming.security.principal The UPN for an account with privileges to see all users and groups. This account is used to retrieve the details of all users and groups in the directory so that it can synchronize its internal user and authority database. Passwords are never compromised and remain in the directory server.
    ldap.synchronization.java.naming.security.credentials The password for the previous account
    ldap.synchronization.groupSearchBase The Distinguished Name (DN) of the Organizational Unit (OU) below which security groups can be found. You can determine the appropriate DN by browsing to security groups in an LDAP browser.
    ldap.synchronization.userSearchBase The distinguished name (DN) of the Organizational Unit (OU) below which user accounts can be found. You can determine the appropriate DN by browsing to user accounts in an LDAP browser.
Apply ldap-ad example

This example demonstrates how you can further delegate authentication responsibility to Active Directory, without the automatic sign-on capabilities that are available to internal users.

  1. Restart the server.

    If you watch the output from Tomcat in the alfresco.log in the installation directory, you’ll eventually see lines similar to the following:

     13:01:31,225 INFO
     [org.alfresco.repo.management.subsystems.ChildApplicationContextFactory]
     Starting 'Synchronization' subsystem, ID: [Synchronization, default]
    
     ...
    
     13:01:49,084 INFO
     [org.alfresco.repo.security.sync.ChainingUserRegistrySynchronizer]
     Finished synchronizing users and groups with user registry 'ldap1'
    
     13:01:49,084 INFO
     [org.alfresco.repo.security.sync.ChainingUserRegistrySynchronizer]
     177 user(s) and 19 group(s) processed
    
     13:01:49,131 INFO
     [org.alfresco.repo.management.subsystems.ChildApplicationContextFactory]
     Startup of 'Synchronization' subsystem, ID: [Synchronization, default] complete
    

    This is output is from the Synchronization subsystem, the subsystem responsible for synchronizing the internal user and authority database with all user registries in the authentication chain. Since the authentication chain now provides a user registry, the Synchronization subsystem has some work to do when Community Edition starts up.

  2. From the example logs, notice that the Synchronization subsystem automatically created 177 users and 19 groups using attributes, such as email address and group memberships, retrieved from Active Directory through an LDAP query. This reduces the workload of the administrator user.

    Note: The Synchronization subsystem uses an incremental timestamp-based synchronization strategy, meaning that it only queries for changes since the last synchronization run. So after the first start up, further synchronization runs can be almost instantaneous. Because synchronization runs are also triggered by a scheduled nightly job and whenever an unknown user successfully authenticates, you should find that Community Edition always stays synchronized with hardly any effort.

    Now, if you enter the URL: http://localhost:8080/share into your browser, you can log in using the ID and password of any of the Active Directory users.

    Important: Passwords are validated through an LDAP bind operation on Active Directory in real time. Passwords for Active Directory users are not stored locally.

  3. Navigate to a user profile.

    Notice that attributes such as email address were populated automatically from Active Directory.

Example: authentication and synchronization with two ldap-ad subsystems

This example uses one Active Directory server and shows authentication as well as user registry export (synchronization) from two ldap-ad subsystems.

The two ldap-ad subsystems used are ad1 and ad2. Both these subsystems use the same Active Directory server but different locations within it (search bases).

  1. Add the following properties to the alfresco-global.properties file.

     authentication.chain=alfinst:alfrescoNtlm,ad1:ldap-ad,ad2:ldap-ad
    
  2. Create the properties files to configure ad1:

     mkdir <installLocation>\tomcat\shared\classes\alfresco\extension\subsystems\
     Authentication\ldap-ad\ad1
    
     cd /d <installLocation>\tomcat\shared\classes\alfresco\extension\subsystems\
     Authentication\ldap-ad\ad1
    
     copy <InstallLocation>\tomcat\webapps\alfresco\WEB-INF\lib*.properties
    

    A single file called ldap-ad-authentication.properties now appears in the ad1 directory. You can edit this file to define your LDAP set up.

    The following lines show the set of properties you’ll typically need to edit and how you might set them for a domain controller for a fictitious domain called domain.com for ldap-ad subsystem ad1.

     ldap.authentication.allowGuestLogin=false
     ldap.authentication.userNameFormat=%s@domain.com
     ldap.authentication.java.naming.provider.url=ldap://domaincontroller.domain.com:389
     ldap.authentication.defaultAdministratorUserNames=Administrator,alfresco
     ldap.synchronization.java.naming.security.principal=alfresco@domain.com
     ldap.synchronization.java.naming.security.credentials=secret
     ldap.synchronization.groupSearchBase=ou=ad1,ou=Alfresco\
     ,dc=domain,dc=com
     ldap.synchronization.userSearchBase=ou=ad1,ou=Alfresco,dc=domain,dc=com
    
  3. Create the properties files to configure ad2:

     mkdir <installLocation>\tomcat\shared\classes\alfresco\extension\subsystems\
     Authentication\ldap-ad\ad2
    
     cd /d <installLocation>\tomcat\shared\classes\alfresco\extension\subsystems\
     Authentication\ldap-ad\ad2
    
     copy <InstallLocation>\tomcat\webapps\alfresco\WEB-INF\lib*.properties
    

    A single file called ldap-ad-authentication.properties now appears in your ad2 directory. You can edit this file to define your LDAP set up.

    The following lines show the set of properties you’ll typically need to edit and how you might set them for a domain controller for a fictitious domain called domain.com for ldap-ad subsystem ad2.

     ldap.authentication.allowGuestLogin=false
     ldap.authentication.userNameFormat=%s@domain.com
     ldap.authentication.java.naming.provider.url=ldap://domaincontroller.domain.com:389
     ldap.authentication.defaultAdministratorUserNames=Administrator,alfresco
     ldap.synchronization.java.naming.security.principal=alfresco@domain.com
     ldap.synchronization.java.naming.security.credentials=secret
     ldap.synchronization.groupSearchBase=ou=ad2,ou=Alfresco\
     ,dc=domain,dc=com
     ldap.synchronization.userSearchBase=ou=ad2,ou=Alfresco,dc=domain,dc=com
    

Configure synchronization

The synchronization subsystem manages the synchronization of Community Edition with all the user registries (LDAP servers) in the authentication chain.

The synchronization subsystem supports three modes of synchronization:

Synchronization mode Description
Full All users and groups are queried, regardless of when they were last modified. All local copies of these users and groups already existing are then updated and new copies are made of new users and groups. Since processing all users and groups in this manner can be fairly time consuming, this mode of synchronization is usually only triggered on the very first sync when the subsystem first starts up. However, synchronization can also be triggered in this mode by the scheduled synchronization job, if synchronization.synchronizeChangesOnly is set to false.
Differential Only those users and groups changed since the last query are queried and created/updated locally. This differential mode is much faster than full synchronization. By default, it is triggered when the subsystem starts up after the first time and also when a user is successfully authenticated who does not yet have a local person object in Community Edition. This means that new users, and their group information, are pulled over from LDAP servers as and when required with minimal overhead.
Differential With Removals All users and groups are queried to determine which ones no longer exist and can be disabled or deleted locally. In order to synchronize the attributes of the remaining users and groups, a differential sync is performed so only those users and groups that have changed since the last sync are updated or added locally.

Synchronization triggers

Synchronization can be triggered by each of the following events:

Synchronization trigger Description
Startup On system startup or restart of the Synchronization subsystem, a differential sync is triggered (unless disabled with configuration).
Authentication On successful authentication of a user who does not yet exist locally, a differential sync is triggered (unless disabled with configuration).
Schedule A scheduled job triggers synchronization in differential with removals mode every 24 hours. This can instead by scheduled in full mode if you set the synchronization.synchronizeChangesOnly property to false. The scheduling of this job can also be altered.

Synchronization deletion

Users and groups removed from the LDAP directory or query are only identified when synchronization is triggered by the schedule job in either full mode or differential with removals mode.

Users and groups created as a result of a synchronization operation are tagged with an originating zone ID. This records the ID of the authentication subsystem instance that the user or group was queried from. On synchronization with a zone, only those users and groups tagged with that zone are candidates for deletion. This avoids accidental deletion of built-in groups, such as ALFRESCO_ADMINISTRATORS.

When a removed user or group is detected, Community Edition will behave in one of two ways, depending on the value of the synchronization.allowDeletions property. When true (the default value), Community Edition simply deletes the user or group from the local repository. When false, the user or group is simply untagged from its zone, thus converting it to a local user or group. A removed user also loses its memberships from any of the LDAP groups they were in, whereas, a removed group is cleared of all their members. As the user or group is retained in the repository, this setting has the advantage that the site memberships for that user or group are remembered, should they later be reactivated.

Collision resolution

If there are overlaps between the contents of two user registries in the authentication chain (for example, where two user registries both contain a user with the same user name), then the registry that occurs earlier in the authentication chain will be given precedence. This means that exactly the same order of precedence used during authentication will be used during synchronization.

For example, if user A is queried from zone Z1 but already exists in zone Z2:

  • A is ignored if Z1 is later in the authentication chain than Z2
  • A is moved to Z1 if Z2 does not exist in the authentication chain or Z1 is earlier in the authentication chain and the synchronization.allowDeletions property is false.
  • A is deleted from Z2 and recreated in Z1if Z1 is earlier in the authentication chain and the synchronization.allowDeletions property is true.

Synchronization configuration properties

The synchronization subsystem manages synchronization by configuring the subsystem’s properties.

The following properties can be configured for the synchronization subsystem.

Property Description
synchronization.synchronizeChangesOnly Specifies whether the scheduled synchronization job is run in differential mode. The default is true, which means that the scheduled sync job is run in differential mode (rather than full mode). Regardless of this setting a differential sync can still be triggered when a user who does not yet exist is successfully authenticated.
synchronization.allowDeletions Specifies if deletion of local users and groups is allowed. See the information about Synchronization deletion and Collision resolution for the circumstances under which this can happen. The default is true. If false, then no sync job will be allowed to delete users or groups during the handling of removals or collision resolution.
synchronization.import.cron Specifies a cron expression defining when the scheduled synchronization job should run, by default at midnight every day.

For more information about the cron expression, see the CronTrigger tutorial.
synchronization.syncOnStartup Specifies whether to trigger a differential sync when the subsystem starts up. The default is true. This ensures that when user registries are first configured, the bulk of the synchronization work is done on server startup, rather than on the first login.
synchronization.syncWhenMissingPeopleLogIn Specifies whether to trigger a differential sync when a user, who does not yet exist, is successfully authenticated. The default is true. If there are users created in the LDAP server that do not already exist, when you start Community Edition, a differential synchronization is triggered.
synchronization.autoCreatePeopleOnLogin Specifies whether to create a user with default properties when a user is successfully authenticated, who does not yet exist, and was not returned by a differential sync (if enabled with the specified property). The default is true. Setting this to false allows you to restrict Community Edition to a subset of those users who could be authenticated by LDAP; only those created by synchronization are allowed to log in. You can control the set of users in this more restricted set by overriding the user query properties of the LDAP authentication subsystem.

Edit this page

Suggest an edit on GitHub
This website uses cookies in order to offer you the most relevant information. Please accept cookies for optimal performance. This documentation is subject to the Documentation Notice.