External directory synchronization and authentication using ActiveDirectory plugin

Product:	IMiS/ARChive
Release:	Since 9.7.1610
Date:	06/11/2021

Case:

ActiveDirectory plugin is used for synchronization and authentication using Microsoft Active Directory service. In this article we represent an example how to configure plugin for user/group synchronization and authentication using Microsoft AD.

Description:

IMiS ARChive server can be configured to use Microsoft Active Directory as external service for synchronization users and groups. Synchronized users can also use Microsoft AD for authentication to the IMiS ARChive server using either LDAP or Kerberos authentication methods. ActiveDirectory plugin uses mapping between IMiS ARChive directory and Microsoft AD attributes.

Mappings between IMiS ARChive Server 10.1.2010 fields and Microsoft AD attributes:

"sys:dir:Account" represent user/group account name (single value). Mapped attribute is "sAMAccountName".
"sys:dir:FirstName" represent user/group first name (single value). Mapped attribute for users is "givenName", groups does not have mapping (empty string is returned).
"sys:dir:LastName" represent user/group last name (single value). Mapped attribute for users is "sn" and for groups "name".
"sys:dir:Description" represent user/group description (single value). Mapped attribute for users and groups is "description".
"sys:dir:Email" represent user/group email (single value). Mapped attribute for users and groups is "mail".
"sys:dir:UUID" represent user/group unique identifier for external synchronization service (single value). Mapped attribute for users and groups is "objectGUID".
"sys:dir:Flags:Enabled" represent if user/group is enabled (single value). Mapped attribute for users and groups is "userAccountControl" ("ACCOUNTDISABLE" property flag).
"sys:dir:SecurityClass" represent user/group security class (single value). There is no mapping from Active directory and returned value is always "0".
"sys:dir:Icon" represent user/group icon (single value). Mapped attribute for users and groups is "thumbnailPhoto".
"sys:dir:Aliases" represent user/group aliases (multi value). There is no default mapping for user and groups, mapping must be explicitly done in plugin configuration.
"sys:dir:Flags:Locked" represent if user is locked (single value). Mapped attribute for users is "lockoutTime", groups does not have mappings and return value is always "false".
"sys:dir:Flags:AuthExt" represent if user can be authenticated using external service (single value). There is no mapping for groups, for users, "true" is always returned.
"sys:dir:Flags:AuthHTTP" represent if user can use HTTP authentication (single value). There is no mapping for groups, for users, "false" is always returned.
"sys:dir:Flags:AuthSRP6A" represent if user can use SRP6A authentication (single value). There is no mapping for groups, for users, "false" is always returned.
"sys:dir:Flags:AuthPSK" represent if user can use legacy "pre-shared key" authentication (single value). There is no mapping for groups, for users, "false" is always returned.
"sys:dir:Flags:AuthAdv" represent if user can use legacy advanced authentication (single value). There is no mapping for groups, for users, "false" is always returned.
"sys:dir:Flags:LinkIdentity" represent if user can link internal IMiS ARChive identity with external service provider (single value). There is no mapping for groups, for users, "false" is always returned. Field is available since IMiS ARChive 10.3.2210.
"sys:dir:Delegates" represent user delegates (multi value). There is no mapping for users and groups, empty value is always returned for users.
"sys:dir:GroupMembers" represent group members (multi value). For groups, mapped attribute is "member", for users there is no mapping.

XML is used for plugin configuration. Configuration tags are grouped together by its purpose.

Package configuration:

"<Class>": plugin classpath. For ActiveDirectory plugin, classpath is "com.imis.imisarc.server.aaa.impl.ActiveDirectory".

ActiveDirectory related configuration:

"<AccountAliasList>": list of Microsoft AD attributes (separated with ",") which will override default mappings. First attribute will override "sys:dir:Account" field, rest of attributes will be used to populate "sys:dir:Aliases" field. Optional tag attribute is "scope", which dictates if override is for users, groups or both. Valid values are "user" and "group". If attribute is omitted, override attributes are used for users and groups.

LDAP configuration:

"<LdapURL>": url to the Microsoft AD server. Multiple tags represent fallback servers which will be used on connection failure. Mixing "ldap" and "ldaps" protocols is not supported.
"<LdapUsername>": username for accessing LDAP server.
"<LdapPassword>": password for accessing LDAP server.
"<LdapAuthenticationType>": LDAP authentication type. Supported values: "NONE", "SIMPLE", "DIGEST-MD5", "CRAM-MD5".
"<LdapBaseDN>": LDAP base DN. If tag is omitted, then full user/group DN must be specified in "<LdapUserDN>" and "<LdapGroupDN>" tags.
"<LdapUserDN>": LDAP user DN scope where users will be searched. Multiple tags represent multiple scopes. Number of tags must match number of "<LdapUserObjectFilter>" tags.
"<LdapGroupDN>": LDAP group DN scope where groups will be searched. Multiple tags represent multiple scopes.
"<LdapUserObjectFilter>": LDAP query string for user synchronization. Multiple tags represent multiple user query strings and must match number of "<LdapUserDN>" tags. One tag means that the same query string is used for all user scopes.
"<LdapGroupObjectFilter>": LDAP query string for group synchronization. Multiple tags represent multiple group query strings and must match number of "<LdapGroupDN>" tags. One tag means that the same query string is used for all group scopes.
"<LdapReadTimeout>": LDAP socket read timeout (milliseconds).
"<LdapQueryTimeout>": LDAP query timeout (milliseconds).
"<LdapConnectTimeout>": LDAP connection timeout (milliseconds).
"<LdapPageSize>": how many results will be retrieved in one page from server.
"<LdapRecursiveQueries>": true/false value controls if query is recursive or not (default value is "true").
"<LdapAuthenticationFilter>": LDAP query string for user query operations during authentication. Multiple tags represent multiple user query strings and must match number of "<LdapUserDN>" tags. One tag means that the same query string is used for all user scopes. Query string must contain "%s" formatter, which will be replaced by user values in runtime during authentication process.
"<LinkIdentityFlag>": Overrides default behavior of "sys:dir:Flags:LinkIdentity" field. Configuration expects true or false value.

SSL/TLS configuration:

"<SSLKSType>": SSL keystore type (supports all keystore types from Java).
"<SSLKSFile>": SSL keystore full path.
"<SSLKSPassword>": SSL keystore password.
"<SSLTSType>": SSL truststore type (supports all truststore types from Java). Use "IAKS" type for using internal certificate store from IMiS ARChive Server.
"<SSLTSFile>": SSL truststore full path. If "IAKS" type is used, tag is omitted.
"<SSLTSPassword>": SSL truststore password. If "IAKS" type is used, tag is omitted.
"<SSLProtocols>": supported SSL protocols. Multiple values must be separated with ",". If multiple values are used, they are processed in the same order as they are defined in tag.

Kerberos configuration:

"<KrbServicePrincipal>": represent a unique identity of IMiS ARChive Server in a Kerberos system.
"<KrbKeytabLocation>": keytab file full path.
"<KrbTweakJdkRegression>": "true/false" value for "JDK-8048194" bug workaround in Java 8u40 and 8u45. Default value is "false".
"<KrbDebugMode>": "true/false" value for enabling Kerberos debug mode. When enabled, detailed description of Kerberos verification is dumped in server log. Default value is "false".

Plugin configuration example 1: ActiveDirectory plugin is used for synchronization with one AD server, using DIGEST-MD5 authentication type. User and group synchronization is done from one DN, account and alias override is enabled. "sAMAccountName" attribute is mapped to "sys:dir:Account", "userPrincipalName" and "distinguishedName" attributes are mapped to "sys:dir:Aliases" (this is done for users and groups because "scope" attribute is not present). LDAP query for authentication filter defines, that user can authenticate using email, account name or "distinguishedName" value from aliases. Plugin also uses Kerberos configuration which means that user can authenticate to IMiS ARChive server using Kerberos single sing on.

<Arguments>
<Class>com.imis.imisarc.server.aaa.impl.ActiveDirectory</Class>
<LdapURL>ldap://ad.server.company.com</LdapURL>
<LdapUsername>query-ldap-username</LdapUsername>
<LdapPassword>username-password</LdapPassword>
<LdapAuthenticationType>DIGEST-MD5</LdapAuthenticationType>
<LdapBaseDN>DC=company,DC=com</LdapBaseDN>
<LdapUserDN>OU=Users</LdapUserDN>
<LdapGroupDN>OU=Groups</LdapGroupDN>
<LdapUserObjectFilter>(objectClass=user)</LdapUserObjectFilter>
<LdapGroupObjectFilter>(objectClass=group)</LdapGroupObjectFilter>
<LdapAuthenticationFilter>(&(objectCategory=person)(objectClass=user)(|(userPrincipalName=%s)(mail=%s)(sAMAccountName=%s)))</LdapAuthenticationFilter>
<KrbServicePrincipal>IARC/server-host.company.com@COMPANY.COM</KrbServicePrincipal>
<KrbKeytabLocation>/iarc/work/iarc-server.keytab</KrbKeytabLocation>
<AccountAliasList>sAMAccountName,userPrincipalName,distinguishedName</AccountAliasList>
</<Arguments>

Plugin configuration example 2: ActiveDirectory plugin is used for synchronization with main AD server and fallback server, using DIGEST-MD5 authentication type. User and group synchronization is done from 3 DN scopes, account and alias override is enabled (different configuration for user and groups). All timeouts are set to 60 seconds, LDAP page size is set to 50 hits per page. Plugin uses internal server certificate store for LDAPS connection, secure protocol is limited to TLS. Base DN is omitted, therefore user and group DN contains full DN. The same filter is used for all user and group scopes so only 1 "<LdapUserObjectFilter>" and "<LdapGroupObjectFilter>" is defined.

<Arguments>
<Class>com.imis.imisarc.server.aaa.impl.ActiveDirectory</Class>
<LdapURL>ldaps://ad.main.server.company.com</LdapURL>
<LdapURL>ldaps://ad.fallback.server.company.com</LdapURL>
<LdapUsername>query-ldap-username</LdapUsername>
<LdapPassword>ldap-username-password</LdapPassword>
<LdapAuthenticationType>DIGEST-MD5</LdapAuthenticationType>
<LdapUserDN>OU=Users1,DC=company,DC=com</LdapUserDN>
<LdapUserDN>OU=Users2,DC=company,DC=com</LdapUserDN>
<LdapUserDN>OU=Users3,DC=company,DC=com</LdapUserDN>
<LdapGroupDN>OU=Groups1,DC=company,DC=com</LdapGroupDN>
<LdapGroupDN>OU=Groups2,DC=company,DC=com</LdapGroupDN>
<LdapGroupDN>OU=Groups3,DC=company,DC=com</LdapGroupDN>
<LdapUserObjectFilter>(objectClass=user)</LdapUserObjectFilter>
<LdapGroupObjectFilter>(objectClass=group)</LdapGroupObjectFilter>
<LdapAuthenticationFilter>(&(objectCategory=person)(objectClass=user)(|(userPrincipalName=%s)(mail=%s)(sAMAccountName=%s)))</LdapAuthenticationFilter>
<LdapReadTimeout>60000</LdapReadTimeout>
<LdapQueryTimeout>60000</LdapQueryTimeout>
<LdapConnectTimeout>60000</LdapConnectTimeout>
<LdapPageSize>50</LdapPageSize>
<SSLTSType>IAKS</SSLTSType>
<SSLProtocols>TLS</SSLProtocols>
<KrbServicePrincipal>IARC/server-host.company.com@COMPANY.COM</KrbServicePrincipal>
<KrbKeytabLocation>/iarc/work/iarc-server.keytab</KrbKeytabLocation>
<AccountAliasList scope="user">sAMAccountName,userPrincipalName</AccountAliasList>
<AccountAliasList scope="group">sAMAccountName,distinguishedName</AccountAliasList>
</Arguments>

Plugin configuration example 3: This example demonstrates how to configure different query filters for different user and group scopes. Users from scope "OU=Users1,DC=company,DC=com" will be synchronized if its attribute "sAMAccountName" starts with letter 'a' or 'A', synchronized users can authenticate with alias, which is mapped from attribute "userPrincipalName". Users from scope "OU=Users2,DC=company,DC=com" will be synchronized if its attribute "sAMAccountName" starts with letter 'b' or 'B', they can authenticate with its email address. Users from scope "OU=Users3,DC=company,DC=com" will be synchronized if its attribute "sAMAccountName" starts with letter 'c' or 'C', synchronized users can authenticate with its account name. The same behavior is for group synchronization except that used attribute is "cn".

<Arguments>
...
<LdapUserDN>OU=Users1,DC=company,DC=com</LdapUserDN>
<LdapUserDN>OU=Users2,DC=company,DC=com</LdapUserDN>
<LdapUserDN>OU=Users3,DC=company,DC=com</LdapUserDN>
<LdapGroupDN>OU=Groups1,DC=company,DC=com</LdapGroupDN>
<LdapGroupDN>OU=Groups2,DC=company,DC=com</LdapGroupDN>
<LdapGroupDN>OU=Groups3,DC=company,DC=com</LdapGroupDN>
<LdapUserObjectFilter>(&(objectClass=user)(objectCategory=person)(sAMAccountName=a*))</LdapUserObjectFilter>
<LdapUserObjectFilter>(&(objectClass=user)(objectCategory=person)(sAMAccountName=b*))</LdapUserObjectFilter>
<LdapUserObjectFilter>(&(objectClass=user)(objectCategory=person)(sAMAccountName=c*))</LdapUserObjectFilter>
<LdapGroupObjectFilter>(&(objectClass=group)(cn=i*))</LdapGroupObjectFilter>
<LdapGroupObjectFilter>(&(objectClass=group)(cn=j*))</LdapGroupObjectFilter>
<LdapGroupObjectFilter>(&(objectClass=group)(cn=k*))</LdapGroupObjectFilter>
<LdapAuthenticationFilter>(&(objectCategory=person)(objectClass=user)(userPrincipalName=%s))</LdapAuthenticationFilter>
<LdapAuthenticationFilter>(&(objectCategory=person)(objectClass=user)(mail=%s))</LdapAuthenticationFilter>
<LdapAuthenticationFilter>(&(objectCategory=person)(objectClass=user)(sAMAccountName=%s))</LdapAuthenticationFilter>
<AccountAliasList scope="user">sAMAccountName,userPrincipalName</AccountAliasList>
...
</Arguments>