2.8. Tuning Directory Services for Authentication

This section describes how to tune directory services configuration and includes the following topics:

2.8.1. Filtering LDAP or Active Directory Logins

You can use login filters to control which users can log in SGD and to specify which attributes are used to identify users. There are two filters, user login filter and group login filter.

You might want to configure a login filter in the following circumstances:

  • Users unable to log in. If your directory uses particular attributes for identifying users, users might not be able to log in to SGD. The solution is to configure the user login filter SGD to search for additional attributes.

  • Slow login times. SGD checks for several attributes when identifying users and this can lead to slow login times if you have a large directory. You can improve login times by changing the user login filter to check for a smaller number of attributes.

  • Restrict user logins. If you want to restrict which users can log in to SGD, configure the group login filter or the user login filter.

See also Section 2.8.2, “Using Directory Search Roots” for an alternative method of improving login times and restricting user logins.

2.8.1.1. User Login Filter

Whenever SGD searches a directory to establish a user's identity, it uses a user login filter to check for attributes on the object in the directory.

For LDAP and third-party authentication, the following login filter is used:

(|(cn=${name})(uid=${name})(mail=${name}))

For Active Directory authentication, the following login filter is used:

(|(cn=${user})(sAMAccountName=${user})(userPrincipalName=${user}@${domain})(userPrincipalName=${name})(mail=${name}))

These login filters contain the following variables:

  • ${name} – The full name typed by the user in the SGD login page

  • ${user} – The part of the user name before the @ symbol

  • ${domain} – The part of the user name after the @ symbol. This can be generated by SGD using the base domain, default domain, or suffix mapping settings for the service object

See Section 2.8.1.3, “How to Configure a User Login Filter” for details of how to change the user login filter.

2.8.1.2. Group Login Filter

The group search filter is used to restrict the LDAP or Active Directory users that can log in to SGD, by testing the user's group membership. If the user is not a member of the group, the user cannot log in to SGD.

See Section 2.8.1.4, “How to Configure the Group Login Filter” for details of how to apply the filter to SGD.

2.8.1.3. How to Configure a User Login Filter

Ensure that no users are logged in to the primary SGD server in the array and that there are no running application sessions, including suspended application sessions.

  1. Log in as superuser (root) on the primary SGD server in the array.

  2. Stop the SGD server.

  3. Configure a user login filter.

    Caution

    Any mistakes in this step can result in users being unable to log in.

    • For LDAP authentication and third-party authentication, use the following command:

      # tarantella config edit \
      --com.sco.tta.server.login.ldap.LdapLoginAuthority.properties-searchFilter filter
      
    • For Active Directory authentication, use the following command:

      # tarantella config edit \
      --com.sco.tta.server.login.ADLoginAuthority.properties-searchFilter filter
      

    For example, to configure a user login filter to search for just the uid and mail attributes, use the following filter:

    "(&(|(uid=\${name})(mail=\${name}))"

    For example, to configure a user login filter to search for just the cn and mail attributes, and to permit logins for only for users that are in the sales department, use the following filter:

    "(&(|(cn=\${name})(mail=\${name}))(department=sales))"

    If you use variables in the filter, you must backslash escape the $ symbol.

  4. Start the SGD server.

2.8.1.4. How to Configure the Group Login Filter

Ensure that no users are logged in to the primary SGD server in the array and that there are no running application sessions, including suspended application sessions.

  1. Log in as superuser (root) on the primary SGD server in the array.

  2. Stop the SGD server.

  3. Configure the group login filter.

    Caution

    Any mistakes in this step can result in users being unable to log in.

    To configure the group login filter, use the following command:

    # tarantella config edit \
    --com.sco.tta.server.login.DSLoginFilter.properties-loginGroups group_dn ...
    

    where group_dn is the DN of one or more LDAP groups.

    For example, to permit logins only from users who are members of either the cn=sgdusers or the cn=sgdadmins group, use the following command:

    # tarantella config edit \
    --com.sco.tta.server.login.DSLoginFilter.properties-loginGroups \
    "cn=sgdusers,cn=groups,dc=example,dc=com" \
    "cn=sgdadmins,cn=groups,dc=example,dc=com"
  4. Start the SGD server.

2.8.2. Using Directory Search Roots

You can use directory search roots to control which users can log in to SGD and to speed up directory searches when using LDAP or Active Directory authentication or when using Directory Services Integration to assign applications.

A directory search root specifies a part of the directory which is used to search for the user identity. To specify a search root, append the search root to the URL for the service object.

For example, to search for users in the Active Directory domain sales.example.com:

ad://example.com/dc=sales,dc=example,dc=com

Using the search root in this example, only users in the sales.example.com domain are able to log in to SGD.

For example, to search for users in the LDAP OU sales:

ldap://ldap.example.com/ou=sales,dc=example,dc=com

Using the search root in this example, only users in the sales OU are able to log in to SGD.

You can use multiple service objects to specify multiple search roots. With the URLs in the following example, only users in the domain sales.example.com and marketing.example.com are able to log in to SGD.

ad://example.com/dc=sales,dc=example,dc=com
ad://example.com/dc=marketing,dc=example,dc=com

2.8.3. LDAP Discovery Timeout

The LDAP discovery timeout controls how long SGD waits for a directory server (LDAP or Active Directory) to respond to the initial contact request. The default is 20 seconds.

SGD makes two attempts to contact a directory server. If there is no response, SGD tries another directory server. If all directory servers time out, SGD might not be able to authenticate users or assign applications to them.

To change the timeout, use the following command:

$ tarantella config edit --tarantella-config-ldap-timeout secs

For Active Directory authentication, the LDAP discovery timeout must be longer than the KDC timeout. See Section 2.2.4.4, “KDC Timeout”. For example, if the KDC timeout is 10 seconds and the KDC retries is 3, make the LDAP discovery timeout 35 seconds (3 x 10 seconds + extra 5 seconds). Keep the KDC timeout and the LDAP discovery timeout in step. If you increase the KDC timeout, increase the LDAP discovery timeout.

2.8.4. Using Service Objects

A service object is a group of directory services configuration settings used for the following SGD authentication mechanisms:

You can enable Active Directory authentication or LDAP authentication. Both cannot be enabled at the same time.

If you enable any of these authentication mechanisms using the Authentication Wizard on the Global Settings → Secure Global Desktop Authentication tab in the SGD Administration Console, SGD automatically creates a service object called generated. If you enable any of these authentication methods on the command line, you must manually create at least one service object.

You can create and manage service objects on the Global Settings → Service Objects tab in the SGD Administration Console. The Service Objects List table shows the available service objects for the SGD array.

On the command line, you use the tarantella service command to create and manage service objects.

Note the following points about service objects:

  • Service objects have a type. This is either an LDAP type or an Active Directory type. The type controls which SGD authentication mechanism can use the object. Active Directory service objects are used only for Active Directory authentication.

  • Service objects can be enabled or disabled. A service object must be enabled before it can be used for authentication. Typically you disable a service object only because you know a directory service is temporarily unavailable, or because you know it will become available in the future.

  • Service objects have a position. SGD uses the enabled service objects in the order specified in the Service Objects List table. If the first enabled service object in the list does not result in a successful authentication or user identity, the next enabled service object in the list is tried.

In the Administration Console, you can configure only the commonly-used settings for service objects, such as the URL of the directory server, or the user name and password. See Section 2.8.4.1, “How to Create an Active Directory Service Object” and Section 2.8.4.2, “How to Create an LDAP Service Object” for more details.

There are also some advanced service object settings that can be configured only from the command line with the tarantella service new or the tarantella service edit commands.

For LDAP service object types, the following are the advanced configuration settings:

For AD service object types, the following are the advanced configuration settings:

2.8.4.1. How to Create an Active Directory Service Object

  1. In the Administration Console, display the Global Settings → Service Objects tab.

  2. In the Service Objects List table, click the New button.

    The Create New Service Object window is displayed.

  3. In the Name field, type the name of the service object.

    Once you have created a service object, you cannot rename it. The name can only contain lowercase characters, digits, or the characters _ and -.

  4. For Type, select the Active Directory option.

    Once you have created a service object, you cannot change the type.

  5. (Optional) Deselect the Enabled check box.

    A service object must be enabled before SGD can use it. Only enable a service object if you are sure that it is ready to be used.

  6. In the URLs field, type the URL of an Active Directory forest.

    For example, ad://example.com.

    The URL must start with ad://. Only type one URL.

    The URL must be unique. Different service objects cannot use the same URL.

    You can specify a DN to use as the search base, for example ad://example.com/dc=sales,dc=example,dc=com. This specifies the part of the directory used to search for the user identity.

    Use the Test button to test the connection to the URL.

  7. Configure secure connections to Active Directory.

    • To use only the Kerberos protocol for secure connections – Select the Kerberos option for Connection Security, and type a user name and password in the User Name and Password fields.

      Note

      The Kerberos option is selected by default.

    • To use Kerberos and SSL for secure connections – Select the SSL option for Connection Security, and type a user name and password in the User Name and Password fields.

    • To use Kerberos, SSL, and client certificates for secure connections – Select the SSL option for Connection Security, and select the Use Certificates check box.

    See Section 2.2.3.5, “SSL Connections to Active Directory” for details of the additional configuration required to use SSL connections.

    If you type a user name, the user name has the form user@example.com. If you omit the domain name from the user name, SGD uses the information in the URL, Base Domain, and Default Domain fields to obtain a domain. The user must have privileges to search Active Directory for user information.

  8. (Optional) In the Active Directory Base Domain field, type a partial domain name.

    The base domain is used when users only supply a partial domain when they log in. For example, if the base domain is set to example.com and a user logs in with the user name rouge@west, SGD tries to authenticate the user as rouge@west.example.com.

  9. (Optional) In the Active Directory Default Domain field, type a domain name.

    The default domain is used when users do not supply a domain when they log in. For example, if the default domain is set to east.example.com and a user logs in with the user name rouge, the SGD tries to authenticate the user as rouge@east.example.com.

  10. Click the Create button.

    The Create New Service Object window is closed and an entry for the service object is added at the bottom of the Service Objects List table in last position on the Service Objects tab.

  11. Use the Move Up and Move Down buttons to change the position of the service object in the table.

    SGD uses the enabled service objects in the order they are shown.

2.8.4.2. How to Create an LDAP Service Object

  1. In the Administration Console, display the Global Settings → Service Objects tab.

  2. In the Service Objects List table, click the New button.

    The Create New Service Object window is displayed.

  3. In the name field, type the name of the service object.

    Once you have created a service object, you cannot rename it. The name can only contain lowercase characters, digits, or the characters _ and -.

  4. For Type, select the LDAP option.

    Select this option even if you are using a Microsoft Active Directory server for LDAP authentication.

    Once you have created a service object, you cannot change the type.

  5. (Optional) Deselect the Enabled check box.

    A service object must be enabled before SGD uses it. Only enable a service object if you are sure that it is ready to be used.

  6. In the URLs field, type the URL of one or more LDAP directory servers.

    For example, ldap://melbourne.example.com.

    If you type more than one URL, separate each URL with a semicolon (;).

    SGD uses the URLs in the order they are listed. If the first LDAP directory server in the list is unavailable, the next one is tried.

    To use secure connections to LDAP directory servers, use an ldaps:// URL.

    The URLS configured for an LDAP service object must all be of the same type, either ldap:// or ldaps://. You cannot use a mixture of ldap:// and ldaps:// URLs.

    If the LDAP directory uses a non-standard port, specify the port number as part of the URL, for example ldap://melbourne.example.com:5678. Otherwise the port number can be omitted.

    You can specify a DN to use as the search base, for example ldap://melbourne.example.com/dc=example,dc=com. This specifies the part of the LDAP directory used to search for the user identity.

    The URL(s) must be unique. Different service objects cannot use the same URL(s).

    Use the Test button to test the connection to the URL(s).

  7. Type the details of an LDAP user in the User Name and Password fields.

    The user name must be the DN of the user, for example cn=sgd-user,cn=Users,dc=example,dc=com. This is the administrator bind DN, see Section 2.4.3.3, “LDAP Bind DN and Password Change” for more details.

    As you can only enter one user name and password, this user must be able to search all LDAP directory servers listed in the URL field.

    If the directory server supports anonymous binds, you can omit the user name and password. You must be able to perform LDAP queries for user data to use anonymous binds.

  8. Click the Create button.

    The Create New Service Object window is closed and an entry for the service object is added at the bottom of the Service Objects List table in last position on the Service Objects tab.

  9. Use the Move Up and Move Down buttons to change the position of the service object in the table.

    SGD uses the enabled service objects in the order they are shown.

2.8.5. Password Expiry

The following information applies to LDAP and Active Directory service object types. See Section 2.8.4, “Using Service Objects”.

SGD can handle the expiry of a user's password in the following ways:

  • Display a warning message on the webtop, telling the user that their password is about to expire

  • Deny authentication and force the user to reset their password at the next log in

The password expiry features are disabled by default.

For important information about authentication and password expiry, see Section 2.2.4.2, “Active Directory Password Expiry” and Section 2.4.3.3, “LDAP Bind DN and Password Change”.

Password expiry features are configured separately for each for service object. For example, to enable LDAP password expiry features for the mainldap service object, use the following command:

$ tarantella service edit --name mainldap --check-pwd-policy 1

With this configuration, users see a warning message on their webtop seven days before their password is due to expire. One day before their password is due to expire, SGD forces them to change their password. These are the defaults.

You can control when the password expiry features become active. In the following example, the password expiry features are enabled for the mainldap service object. SGD is configured to display a warning message 14 days (1209600 seconds) before password expiry, and users are forced to change their passwords 3 days (259200 seconds) before they expire:

$ tarantella service edit --name mainldap --check-pwd-policy 1 \
--pwd-expiry-warn-threshold 1209600 \
--pwd-expiry-fail-threshold 259200

2.8.6. LDAP Password Update Mode

The following information applies only to LDAP service object types. See Section 2.8.4, “Using Service Objects”.

By default, SGD performs password changes by performing a bind as the LDAP user. See Section 2.4.3.3, “LDAP Bind DN and Password Change” for more details.

The password update mode can be configured separately for each LDAP service object. For example, to use the administrator bind for the mainldap service object, use the following command:

$ tarantella service edit --name mainldap
--password-update-mode ldapadmin

2.8.7. Sites

The following information applies only to Active Directory service object types. See Section 2.8.4, “Using Service Objects”.

A site object in Active Directory is an object that contains subnets.

If site awareness is enabled for a service object, SGD automatically attempts to discover site information by contacting the global catalog. Alternatively, you can configure your own site name for the service object.

If SGD has site information, it queries only the Active Directory servers appropriate for the site.

Caution

If you configure a whitelist, the site configuration for the service object is ignored, see Section 2.8.8, “Whitelists” for more details.

See Section 2.8.15, “Active Directory Authentication and LDAP Discovery” for more details about how sites are used.

Sites can be configured separately for each service object. For example, to enable site awareness for the east service object, use the following command:

$ tarantella service edit --name east --site-aware 1
 

For example, to configure a site name of boston for the east service object, use the following command:

$ tarantella service edit --name east --site-aware 1 --site-name boston

2.8.8. Whitelists

The following information applies only to Active Directory service object types. See Section 2.8.4, “Using Service Objects”.

A whitelist is a list of global catalog servers that are always used for LDAP queries. Only those servers that are included in the whitelist can used for LDAP queries.

Caution

If you configure a whitelist, the site configuration for the service object is ignored, see Section 2.8.7, “Sites” for more details.

The order of the servers in the whitelist is important. If SGD cannot contact the first server in the list, it tries the next one.

See Section 2.8.15, “Active Directory Authentication and LDAP Discovery” for more details about how whitelists are used.

Whitelists can be configured separately for each service object. For example, to configure a whitelist for the east service object, use the following command:

$ tarantella service edit --name east --white-list \
"good1.east.example.com" "good2.east.example.com"

2.8.9. Blacklists

The following information applies only to Active Directory service object types. See Section 2.8.4, “Using Service Objects”.

A blacklist is a list of Active Directory servers that are never used for LDAP queries, for example because a server is temporarily unavailable. Blacklists override any other configuration such as sites or whitelists.

Blacklists can be configured separately for each service object. For example, to configure a blacklist for the east service object, use the following command:

$ tarantella service edit --name east --black-list \
"bad1.east.example.com" "bad2.east.example.com"

2.8.10. Search Only the Global Catalog

The following information applies only to Active Directory service object types. See Section 2.8.4, “Using Service Objects”.

When searching for user information from Active Directory, SGD uses the domain controller for the user's domain by default.

While the domain controller contains the most complete and reliable source for user information, it can result in longer timeouts and delays because SGD has to manage connections to both the domain controller and the global catalog. Instead SGD can be configured to search for user information only from the global catalog.

Caution

If you enable this option, you cannot use the service object password expiry options because SGD cannot access the user's Password Last Set attribute. See Section 2.8.5, “Password Expiry” for more details. Also access to group information is reduced because SGD cannot access domain local security group information.

See Section 2.8.15, “Active Directory Authentication and LDAP Discovery” for more details about how this option is used.

Whether to search only the global catalog can be configured separately for each for service object. For example, to enable searching only the global catalog for the east service object, use the following command:

$ tarantella service edit --name east --ad-alwaysusegc 1

After running this command, you must flush the cache of LDAP data. Run the following command as superuser (root) on every SGD server in the array:

# tarantella cache --flush all

2.8.11. Suffix Mappings

The following information applies to Active Directory service objects and LDAP service objects that connect to Active Directory. See Section 2.8.4, “Using Service Objects”.

Suffix mappings enable you to remap the domain typed by a user to an authentication domain.

Suffix mappings can be configured separately for each service object. For example, to configure a suffix mapping for the east service object, use the following command:

$ tarantella service edit --name east --suffix-mappings \
"test.east.example.com=east.example.com"

Each suffix mapping has the format suffix=domain. If there is more than one mapping, separate each mapping with a space.

2.8.12. Domain Lists

The following information applies only to Active Directory service object types. See Section 2.8.4, “Using Service Objects”.

When SGD starts, it connects to the configured Active Directory forests and then only connects to individual domains as they are needed. In some situations, there can be delays for users when they log in while SGD establishes a connection to the domain. Performance can be improved by providing SGD with a list of domains to connect to when SGD starts.

Domain lists can be configured separately for each for service object. For example, to configure a domain list for the east service object, use the following command:

$ tarantella service edit --name east --domain-list \
"boston.east.example.com" "cambridge.east.example.com"

If there is more than one domain, separate each domain name with a space.

Domain lists do not restrict the Active Directory domains used for authentication.

2.8.13. Lookup Cache Timeout

The following information applies to LDAP and Active Directory service object types. See Section 2.8.4, “Using Service Objects”.

The lookup cache timeout controls for how long SGD keeps LDAP user data after a user logs in. The default is 1200 seconds (20 minutes).

You might want to increase this timeout if the LDAP data does not change very often.

The lookup cache timeout can be configured separately for each for service object. For example, to configure the lookup cache timeout for the east service object, use the following command:

$ tarantella service edit --name east --lookupcache-timeout secs

2.8.14. LDAP Operation Timeout

The following information applies to LDAP and Active Directory service object types. See Section 2.8.4, “Using Service Objects”.

You can configure an LDAP timeout in the event that the LDAP searches of an LDAP directory or Active Directory server takes too long. The LDAP timeout controls how long SGD waits for the directory server to respond to LDAP operations, such as requests for data. The default is 20 seconds.

SGD makes two attempts to contact the directory server. If there is no response, SGD tries another directory server in the list. For Active Directory service objects, see Section 2.8.15, “Active Directory Authentication and LDAP Discovery” for details of the servers SGD contacts. For LDAP service objects, the list of LDAP servers comes from the URLs configured for the service object.

If all directory servers time out, SGD might not be able to authenticate users, or assign applications using LDAP.

The LDAP operation timeout can be configured separately for each for service object. For example, to configure the timeout for the east service object, use the following command:

$ tarantella service edit --name east --operation-timeout secs

2.8.15. Active Directory Authentication and LDAP Discovery

With Active Directory authentication, once a user has been authenticated using Kerberos, SGD performs an LDAP search of Active Directory to establish the user identity and other user information. By default, SGD performs the following steps to discover the LDAP information:

  1. DNS lookup for global catalogs. SGD performs a DNS lookup using the URL configured for the service object to obtain a list of global catalog servers for the forest.

  2. LDAP query on a global catalog. SGD performs an LDAP query on a global catalog to establish the user identity.

    SGD queries the global catalog servers in the order they are returned from the DNS lookup. If SGD cannot contact the first global catalog, it tries the next one in the list.

  3. DNS lookup for domain controllers. SGD performs a DNS lookup for the domain controllers for the user's domain.

    The domain used for this lookup is either the domain typed by the user when they log in, or constructed using the default domain and base domain configured for the service object.

  4. LDAP query on a domain controller. SGD performs an LDAP query on a domain controller to establish a complete set of attributes for the user, such as group membership.

    SGD queries the domain controllers in the order they are returned from the DNS lookup. If SGD cannot contact the first domain controller, it tries the next one in the list.

The configuration of the service object can have a significant effect on the discovery of LDAP information, see Section 2.8.4, “Using Service Objects” for more details. The following table summarizes the effect of service objects on the steps performed by SGD.

Service Object Configuration Options

Steps Performed

Notes

Whitelist

2, 3, 4

The LDAP query is only on the global catalogs in the whitelist.

Search global catalog

1, 2

The DNS lookup and LDAP query are only on the global catalogs.

No operations performed on the domain controllers.

Whitelist

Search global catalog

2

The LDAP query is only on the global catalogs in the whitelist.

No operations performed on the domain controllers.

Site aware

Site name

1, 2, 3, 4

The DNS lookups are only on the global catalogs and domain controllers for the configured site.

Site aware

Site name

Search global catalog

1, 2

The DNS lookup is only on the global catalogs for the configured site.

No operations performed on the domain controllers.

Site aware

1, 2, 3, 4

SGD performs an additional DNS lookup to obtain a list of global catalogs, and then performs an LDAP ping to a global catalog to discover the site name.

The DNS lookups are only for the global catalogs and domain controllers for the discovered site.

Site aware

Search global catalog

1, 2

SGD performs an additional DNS lookup to obtain a list of global catalogs, and then performs an LDAP ping to a global catalog to discover the site name.

The DNS lookup is only for the global catalogs for the discovered site.

No operations performed on the domain controllers.