Skip to end of metadata
Go to start of metadata

The Team Server can be configured to use Active Directory as an identity provider. Doing so enables two forms of authentication based on users' Windows domain accounts:

  • LDAP authentication. Enables users to sign in to BiZZdesign applications using their Windows username and password.
  • Integrated Windows Authentication. Enables seamless single sign-on (SSO) for BiZZdesign applications using Kerberos, which lets users sign in without giving the Team Server access to the users' Windows account credentials.

Team Server user accounts must be provisioned from Active Directory using LDAP for these authentication methods to work.

Configuring LDAP user import and single sign-on should only be done by application administrators who are familiar with installing and configuring software and databases.

Synchronizing users can only be done by users who have the System Administrator role.

Configuring LDAP user import and single sign-on is not possible if you are working with a hosted Team Server.


To configure user synchronization and authentication with Active Directory, follow the steps below. If you only want to configure LDAP authentication (so without SSO), skip the steps indicated with "SSO-only".


On this page:


Preparing an Active Directory user account for the Team Server

To enable LDAP user provisioning and authentication, a user or computer account must be prepared in Active Directory to represent the Team Server in the domain. This account must have a Service Principal Name (SPN) associated with it to explicitly associate it with the address of the Team Server, and must be able to query Active Directory for the users you wish to let authenticate with their Windows account. The Active Directory user must have read access to the user accounts that you wish to provision in the Team Server. If you choose to use Integrated Windows Authentication, this Windows user will also be used to associate the Kerberos Service Principal Name (SPN) and its private key with the Team Server.

If you do not have access to Active Directory, please ask your IT department to set up this user for you and provide you with the user's Distinguished Name and password.


  1. In Active Directory, create a new Active Directory user (e.g. a user called "BiZZdesign Team Server"), and set up a strong password for it.

    Ensure that the User must change password at next logon option is cleared, and that Password never expires is selected. The Team Server must be able to use the LDAP Bind operation to authenticate as this user with the Active Directory LDAP server.

  2. The newly created user has a Distinguished Name and password. To find the Distinguished Name in Active Directory Users and Computers, do as follows:

    1. In the menu bar, go to View, and select Advanced features to enable it.

    2. In the list, right-click the newly created user, and select Properties.

  3. On the Attribute Editor tab, under Attributes, look for the distinguishedName attribute.

Preparing the Team Server Active Directory user for Integrated Windows Authentication (SSO-only)

Integrated Windows Authentication uses the Kerberos protocol to enable single sign-on authentication of users, using their logged in Windows account without the Team Server needing to know the user's Windows credentials. When enabled, the Sign in with Windows button appears on the sign-in window.



When the user clicks it, the web browser retrieves a special Kerberos ticket that identifies the user from Active Directory and presents it to the Team Server. Because this ticket is encrypted and signed by Active Directory using a key that has been configured in the Team Server, the Team Server knows to trust the information and is able to authenticate the user. For this authentication scheme to work, you need to prepare the following:

Determining the Service Principal Name

The address of the Team Server (i.e. the URL through which users will reach the Team Server) must be set as a Service Principal Name (SPN) for the Team Server Active Directory user, so that Active Directory knows which key to encrypt the ticket with.

An SPN for the Team Server typically takes the following form:

HTTP/hostname@realm

Hostname is the fully qualified hostname that users use to connect to the Team Server, and realm is the Windows domain name. For example, for a Team Server at http://teamserver.example.com:9000/, the SPN would look like this: HTTP/teamserver.example.com@EXAMPLE.COM

The protocol part of the SPN must be HTTP, even if the Team Server is served over HTTPS.

Setting the Service Principal Name and generating the keytab file

A keytab file must be created for the Team Server Active Directory user. The keytab is a file that contains the private key required by the Team Server to verify the validity of the tickets and decrypt them. Setting the SPN and generating the keytab file can be done at the same time, using the ktpass command in Windows Server.

  1. On the domain controller, open a command prompt or PowerShell as a user that has the privileges required to modify Active Directory users.

  2. Run the following command to set the user's SPN and generate a keytab.

    ktpass /out teamserver.keytab /princ
    HTTP/teamserver.example.com@EXAMPLE.COM /pass
    P@ssw0rd /mapuser teamserver@example.com /ptype
    KRB5_NT_PRINCIPAL /crypto All

    Replace the mapuser and pass arguments with the credentials of the Active Directory user you created for the Team Server, and replace the princ argument with the SPN for your Team Server.

  3. Copy the resulting teamserver.keytab file into the conf folder of your Team Server installation.

Configuring LDAP user import

  1. In the sidebar menu, click Settings > Authentication.

  2. On the authentication settings page, in Authentication, select identity provider Active Directory.

    Leave HoriZZon URL empty.



  3. Under Directory server, specify the Active Directory server to use and the settings for connecting to this directory server.



    Server URL: The URL used to connect to the LDAP server. Use the prefix ldap://. If you want to connect via a secure SSL connection, use the prefix ldaps://.

    Distinguished name: The Distinguished Name of the Team Server Active Directory user account.

    Password: The password for the Team Server Active Directory account.

    For LDAPS (Secure LDAP) connections, the certificate used by the LDAP server must be trusted by the Java Runtime Environment of the Team Server. Please refer to the manual for your Java Runtime Environment for information about adding certificates to the trusted certificate store.

  4. Under User synchronization, specify the settings for synchronizing users.



    Base DN: The Distinguished Name of the sub-tree that should be queried for users. Users outside this sub-tree will not be imported.

    LDAP query: An LDAP query that should return the users that you want to import. Use the search filter syntax for Active Directory for this. To preview the results of the filter, the Advanced tab of the Custom search functionality of Active Directory can be used.

    Note that license seats may be claimed for any user that matches the query.



    Follow referrals during synchronization: If your user import exceeds the number of users configured on the Active Directory server, activate this option to synchronize more users than the configured limit.

    Follow referrals during sign-in: If referrals are needed to process the sign-in, activate this option. Take note that activating it may result in significant delays.

    Follow referrals connection timeout (ms): The maximum amount of time to attempt following a referral. This setting can be used to limit the amount of time it takes to import users or sign in when Active Directory contains referrals to domain controllers that are not running or not accepting connections. A default Active Directory timeout of 2 minutes is used when dead referrals are encountered. Setting a shorter timeout of 3000 ms is recommended.

  5. If you only configure LDAP authentication, choose one of the following options to continue. At the bottom of the page:

    Click Apply if you only want to save the authentication settings and synchronize users at a later time,
    or
    click Apply and synchronize users if you want to continue to synchronizing users.

    If you also want to use single sign-on, do not click the button, but continue with configuring Integrated Windows Authentication.

Configuring Integrated Windows Authentication (SSO-only)

  1. Under Single sign-on, select Use single sign-on to activate single sign-on, and set the properties that are needed.



    Principal: The Kerberos principal for the Team Server. This typically has the format HTTP/hostname@DOMAIN.

    Realm: The Kerberos realm in which the Team Server resides. This is typically the same as the Windows domain name, and is the part after the @-sign in the Service Principal Name (SPN). For example, if your SPN is HTTP/teamserver.myorg.org@MYORG.ORG, the Kerberos realm will be MYORG.ORG.

  2. Choose one of the following options to continue:

    Click Apply if you only want to save the authentication settings and synchronize users at a later time,
    or
    click Apply and synchronize users if you want to continue to synchronizing users. If the settings have been saved before, click Synchronize users.

Synchronizing users with Active Directory

The number of users that can be synchronized with Active Directory is bound to the number of seats in your Enterprise Studio tool license. During user synchronization, there is no immediate check on the number of users that you are allowed to synchronize. If the number is exceeded, a notification will only appear a short time later. Therefore you should take the allowed number into account before synchronizing. To find out the number of license seats in your tool license, go to Settings > License in the sidebar menu.

The following table shows how Active Directory attributes are mapped to attributes of the Team Server users. Attributes in bold are mandatory and must have been set for all users returned by the LDAP query:


Active Directory

Team Server

sAMAccountName

Username

mail

E-mail address

givenName

First name

sn

Last name

There must always be at least one original Team Server user with the System Administrator role (not imported from LDAP). This user can be used to access the Team Server settings in case there is an issue with the LDAP import and/or sign-in.

Synchronizing users

If you have clicked Apply and synchronize users after configuring the authentication settings, or clicked Synchronize users, the User synchronization page is shown.

If you have only saved the authentication settings before, and now want to synchronize users, open the Authentication settings page, and click Synchronize users. The user synchronization page is shown.

When the page is opened, the Team Server shows a preview of the users that are about to be imported. If you run an import again later, the Team Server synchronizes its user database with Active Directory, updating existing users (for example if their last name has changed), adding new users, and deleting users that are no longer returned by the LDAP query.

The preview is the result of the LDAP query. The total number of users that is shown includes users from Active Directory and original Team Server users.

If the data look OK, click Synchronize users, if not click Cancel.

If the LDAP query returns users with an e-mail address that matches that of an existing Team Server user, the Team Server will update the existing user rather than provisioning a new one.

After synchronization: authentication

After users have been imported, they can sign in to the Team Server using their Windows username and password (LDAP authentication). Note that the Team Server does not import the user's Windows credentials. During LDAP authentication, the Team Server will validate the user's credentials by performing an LDAP Bind operation with them. If the Team Server can authenticate with the LDAP server using the credentials provided by the user, and if the user was provisioned in the Team Server, the user is granted access.

After synchronization: user rights

Users that have been added during synchronization do not have administrator rights nor have the rights to create model packages. Their permissions need to be set afterward by an administrator user.

Also, the users do not receive an e-mail notification (like manually added users do), and do not need to register in the Team Server. Their user accounts are immediately ready for signing in and can be used directly for invitations to model packages and projects.

Adding the Team Server to the web browser's trusted zone (SSO-only)

As a security measure, web browsers do not perform Kerberos authentication with websites unless the site has been explicitly listed as a trusted location. To enable Kerberos authentication for single sign-on, the Team Server needs to be added to the web browser's trusted zone differ per browser. Follow the procedure(s) that applies to your situation.

Perform the procedure for Internet Explorer, as the Activity Console automatically uses this web browser. If the Team Server will be used in Internet Explorer, Edge or Chrome, then you are done. If you use the Team Server in Firefox, then also perform the procedure for that web browser.

Internet Explorer

It is possible to add the Team Server to the trusted zone through a Windows Group Policy as well as locally on a single machine. If you do not wish to use a group policy to add the Team Server to the trusted zone, you may also add the site to the zone on the local machine directly. (The procedure only needs to be performed for Internet Explorer, but also applies to Edge and Chrome.)

Adding the site to the trusted zone for the entire domain using a Group Policy

Perform the following steps as a domain administrator on the domain controller.

  1. Using the Group Policy Management Snap-in, create a new domain policy, or edit an existing one.

  2. Navigate to Computer Configuration > Policies > Administrative Templates > Windows Components > Internet Explorer > Internet Control Panel > Security Page.



  3. In Security Page, double-click the policy setting Site to Zone Assignment List.

  4. Make sure the setting is enabled, and click Show.



  5. In the Show contents window, under Value name and Value, add the address of the Team Server and the value "1" to add the site to the Intranet Zone, and click OK. You do not need to specify the port number.



  6. In the Site to Zone Assignment List window, click OK.

  7. In the group policy editor, navigate into the Intranet Zone folder, and double-click the Logon options policy setting.

  8. Ensure that the setting is enabled, that under Logon options the option Automatic logon with current username and password is selected, and click OK to close the window.


For additional information, see also:
https://blogs.msdn.microsoft.com/askie/2012/06/05/how-to-configure-internet-explorer-security-zone-sites-using-group-polices/

Adding the site to the trusted zone for a local machine

  1. Run inetcpl.cpl, using the Run dialog box (Windows Key+R), or by typing it into the Start Menu. Alternatively, you can start Internet Explorer, click in the upper right corner of the browser, and select Internet options.

  2. On the Security tab, select the Local intranet zone, and click Sites.

  3. In the Local intranet window, click Advanced.

  4. In Add this website to the zone, enter the Team Server's URL, and click Add.



  5. Click Close, and then click OK twice to close the Local intranet and Internet Options windows.

Firefox

Firefox has its own settings for trusted URIs.

  1. Start Firefox and type about:config in the address bar, and press Enter.

  2. If you receive a warning, read the message, and accept the risk.

  3. In the settings list, search for the network.negotiate-auth.trusted.uris setting, right-click it, and click Modify.

  4. Enter the URI for the Team Server, and click OK to save it. The setting can be a list of URI's; if it already has one or more URI's, then add the new one preceded by a comma.