# How to Import Users & Groups (LDAP, SAML, TFS)

Teamscale comes with a built-in user management system. In many scenarios, however, it makes more sense to connect to an existing user management system like LDAP instead.

# Importing Users & Groups from LDAP Server

Teamscale provides LDAP integration to synchronize your LDAP users and groups with the teamscale server. Teamscale can import groups or individual users from a configured LDAP server.

To configure LDAP

  • Go to the Admin perspective.
  • Navigate to Settings > Authentication.
  • Press Add under the LDAP Server section.
  • Enter a name for the server.

The options are:

# LDAP Server Options

OptionDescription
HostnameThe server’s hostname (URL).
PortThe server’s port.
SSLSelect this checkbox if the server is using SSL for connections.
Base DN for usersThe DN under which the users are stored on the LDAP tree. For example: ou=users,dc=example,dc=com.
Base DN for groupsThe DN under which the groups are stored on the LDAP tree. For example: ou=groups,dc=example,dc=com.
Group attributeThe attribute groups are saved with. For example: cn, if the group DN looks like: cn=GROUPNAME,ou=groups,dc= example,dc=com.
DN for the initial bindFull DN of the user used for the connection. This user should have read access to all users and groups. For example: uid=readadmin,ou=users, dc=example,dc=com.
Password for initial bindThe password used by the bind user.
Login attributeThe attribute users are saved with. For example: uid, if the user DN looks like: uid= USERNAME,ou=users,dc=example,dc=com.
Group member attributeThe attribute under which each group stores its members.
First name attributeThe attribute used to store the first name of users.
Last name attributeThe attribute used to store the last name of users.
Email attributeThe attribute used to store the user’s email address

Add the server by pressing the Add button. You can now import entire groups of users using the Import button in the Groups view.

If you wish to import single users, use the Import button in Admin > Users.

If you want to import or update multiple users or group information, use the synchronize buttons found in both views.

# Typical Settings for Active Directory

When configuring an Active Directory server, typically, the following values can be used for the general settings:

OptionDescription
Group attributecn
Login attributesAMAccountName
Group member attributemember (in some cases memberOf)
First name attributegivenName
Last name attributesn
Email attributemail

# Typical Settings for Open LDAP

The following table typical settings for configuring an Open LDAP server:

OptionDescription
Group attributecn
Login attributeuid
Group member attributememberUid
First name attributegivenName
Last name attributesn
Email attributemail

# Global LDAP Catalog

If users are stored in different domains and are thus not available from a single LDAP server it is recommended to query the global catalog of one of the directory servers using port 3268 (or 3269 with SSL). The global catalog offers read-only access to most data of the whole domain tree and thus reduces the overhead to follow LDAP redirects to other servers. Not using the global catalog and following referrals will create a new connection for each LDAP request which may lead to refused connection errors.

# Fallback LDAP Servers

If the LDAP server has fallback servers which are listed in the DNS record, it is recommended to configure the server host using the domain name instead of a single IP address. Teamscale will then use the fallback servers if the primary server is not available.

# Using Azure DevOps Authorization (formerly: TFS Authorization Server)

Teamscale can import groups from teams or groups of an on-premise TFS or Azure DevOps server. This will only synchronize group membership information (authorization); actual authentication and user import has to be delegated to another provider, e.g., LDAP.

Before starting configuration, ensure you have added external credentials for your TFS/Azure DevOps server. This is usually the case if you already configured code analysis for a project on that server.

To configure Azure DevOps Authorization, go to the Admin perspective and open Authentication in the Settings page. Press Add under the TFS Authorization Server section and enter a name for the server.

Azure DevOps Authorization Server Settings

The image shows the configuration options for Azure DevOps Authorization. The different options are:

# TFS Authorization Server Options

OptionDescription
The Azure Dev Ops Server accountThe external credential identifier of the Azure DevOps server. This must be configured first in External Credentials.
The property for the user loginThe name of the user property that the delegated authenticator is queried for when importing users. This can be left empty in most cases. This means that for users in Azure DevOps Server who login with Windows credentials, the DN (distinguished name) is used, and for all other users the E-Mail is used. If a value is specified, that specific property of the user in Azure DevOps Server will be extracted and used for further queries. Users that do not have that property specified or have an empty property will be ignored.
Retrieve users from the following serversMandatory for this connector. The identifier of the authentication provider that should be queried for users. Should be specified in the form of <type>:<name>, e.g., ldap:local-ad.

# Single Sign-On using SAML 2.0

This option can be used, if you already have a SAML 2.0 compatible Identity Provider. Note that SAML can only be used for authentication, which means that your users need to be known to Teamscale beforehand. This is typically achieved by connecting Teamscale to your LDAP server and importing corresponding users and groups.

# First: Setup Identity Provider (outside Teamscale)

As first step, you must configure your identity provider to allow requests from Teamscale. For this, you need to configure at least the entity id of the Teamscale service provider, which you can choose freely, and the assertion consumer URL. The later is the service authsaml, so if your Teamscale server is configured to serve https://ts.company.com/, then the assertion consumer URL would be https://ts.company.com/auth-saml. The configuration details of your identity provider depend on the product used and are beyond the scope of this guide. As a result you should obtain a metadata XML description of the identity provider as SAML 2.0 entity description.

# Second: Setup SAML Provider in Teamscale

  1. In Teamscale, in the Admin perspective navigate to Settings.
  2. Ensure that your Teamscale instance base URL is set correctly.
  3. Create a new SAML 2.0 Identity Provider with a meaningful name and fill the fields:
OptionDescription
Display nameAn arbitrary string that is displayed on the button on the login screen. Example: Corporate Login
Service Provider IDId of the service provider, i.e. the Teamscale instance. This must match what you configured in your identity provider for Teamscale.
Metadata XMLThe entity descriptor metadata XML. This should also contain the identity provider’s public key as X.509 certificate.

Most of the required information is parsed from the metadata you provide there. For testing, you should log out. On the login screen you should see a button that allows you to sign in using the configured identity provider.