Single Sign-on/Multi-factor authentication

This topic describes how to set up SSO and Multi-factor authentication.

In this topic:

StarTeam Authentication methods

Traditionally, StarTeam servers authenticate its users based on their credentials (username and password). In addition to native password authentication, StarTeam allows using directory services (Microsoft Active Directory/e-Directory or OpenLDAP) to perform password authorization.

Starting 17.1 version, StarTeam server provides support for secure authentication using Single Sign-on (SSO) and Multi-factor authentication (MFA) on Windows.

For SSO, StarTeam server uses NetIQ One SSO Provider service (OSP) which is deployed in the StarTeam web service. OSP handles the authenticating of users on behalf of StarTeam server. The authentication workflow is based on OAuth 2.0 /OpenID Connect, industry-standard protocols for authorization and authentication.

For Multi-Factor authentication, StarTeam server provides integration with Advanced Authentication (AA) server, which provides advanced authentication capabilities (such as SMS/ Email OTP in addition to credentials) and non-password based authentication options such as PKI devices, card readers, and fingerprint readers.

Once SSO/MF authentication is complete, access tokens are sent to the StarTeam server by the clients. The StarTeam server validates the tokens and completes the login process. Note that an email address is a required user property for SSO/MFA, as StarTeam server matches the email address in the access token with the StarTeam user’s email address property. Sometimes users can have multiple aliases in LDAP. The authentication will fail if there are no matching email addresses in StarTeam server. The error message suggests the expected email address for the user.

Back to top

Configuring Single Sign-on Authentication (SSO)

By default, both SSO and MF authentications are disabled on a server configuration.

To enable single sign-on authentication:

1. Open the server admin tool.
2. Navigate to the server configuration Configure Server >Authentication tab.

3. Select the option Enable Single Sign-on authentication.

   Note: Directory services must be enabled and configured prior to enabling single sign-on authentication.

4. Fill in the required information:

   • Oauth2 Issuer URL – This is the base URL for OSP and field is pre-populated to point to OSP service running on StarTeam Web service instance. Edit this if you have configured the StarTeam web service (Tomcat) to handle SSL connections or have changed the port.
   • Session Timeout – The timeout for OSP authenticated sessions on the client browser. Once a user is authenticated successfully using Single sign-on, the browser session remains active using Session cookies for the time specified here or till the StarTeam user logs off. This can be configured as per customer requirement.

5. Configure the LDAP repository which will be used as the source of user data. The LDAP hostname/port is automatically populated based on the Directory services settings.

   • LDAP Admin DN – The DN of a user in the LDAP directory.
   • LDAP Admin password – LDAP admin user’s password.
   • SSL – Currently, SSO authentication only supports ldap on secure port (SSL option). When Directory services has port 389 with TLS checked, then SSO configuration will be automatically set to the default non-secure port 389. Then SSO will work, but using unsecure LDAP connection. When SSL option is enabled, a valid LDAPs certificate needs to be imported into OSP key store to establish a secure connection.
   • Directory Type – The LDAP directory type. Supported directory types for SSO authentication include Active Directory and NetIQ E-Directory.
6. For the Container DN, specify a Base DN of the user container where the directory search will be performed.

Back to top

Configure Key Store

OSP uses public key cryptography for establishing client/server trust for outbound TLS connections, digitally signing messages and tokens and data encryption.

Public/private key pairs (asymmetric keys) may be created using a variety of methods. The method chosen depends primarily on customer requirements for the public key certificate. StarTeam server installs a Java key store with a self-signed certificate. The key store can be found under <StarTeam Server install path>/OSP/keystore/ospkeystore.jks.

Back to top

Self-Signed Public Key Certificates

A self-signed public key certificate is a certificate signed by the private key associated with the public key enclosed by the certificate.

You can create a key pair with a self-signed certificate with tools such as Java's keytool and openssl. When openssl is used, the resulting private key and public key certificate must be installed into an appropriate, Java-supported keystore type.

To create a new keystore using keytool:

1. Run the following command (where validity is the number of days before the certificate will expire):

   keytool -genkey -keyalg RSA -alias starteam -keystore starteamkeystore.jks -storepass password -validity 360 -keysize 2048

2. Fill in your organization information. When asked for your first and last name, enter the domain name of the machine running the StarTeam server that users will be connecting to.

Back to top

Certificate Authority-Signed Public Key Certificates

A Certificate Authority (CA)-signed public key certificate is one which is signed using the private key that belongs to a CA. The CA might belong to the customer, or it might be an external CA from which the customer purchases signed certificates.

Creating a key pair with a CA-signed certificate consists of five steps (steps 1 and 2 are sometimes combined, depending on the tool used):

1. Create the public/private key pair.
2. Create a Certificate Signing Request (CSR) for the public key.
3. Submit the CSR to the CA.
4. Receive the signed, public key certificate from the CA.
5. Install the public key certificate into a Java keystore file. The private key may also need to be installed into the keystore at the same time depending on the method used to create the key pair. The bundled self-signed certificate is good for testing and to get started but it is recommended that customers use CA-signed certificates for production use.
6. Configure the key store in StarTeam server admin tool:

Next, you configure the key store in StarTeam server admin tool. Provide the following information:

• Key Alias: All key store entries (key and trusted certificate entries) are accessed via unique aliases. Aliases are case-insensitive. An alias is specified when you add an entity to the key store using the -genkey command to generate a key pair (public and private key) or the -import command to add a certificate or certificate chain to the list of trusted certificates. The default key alias installed with the server is “osp”.
• Key password: Key store entry’s password. When configuring for the first time, customers are required to change the default password of the self-signed certificate. Default key password is Micr0Focu5.
• Keystore File location: Location of the key store. Default location is <Server install path>/OSP/keystore/ospkeystore.jks
• Keystore password: Password for accessing the Key store. Default key store password is Micr0Focu5.
• Keystore Type: Supported types of keystore are JKS/Pkcs12. Installed keystore’s type is pkcs12.

Once configured, both the StarTeam server and Web service must be restarted to allow the Single Sign-on authentication setting to take effect.

Back to top

Configure Multi-Factor authentication (MFA)

Multi-factor authentication allows StarTeam users to have a second factor authentication such as Email, a one-time password (OTP), SMS OTP etc. in addition to their LDAP credentials. MFA also allows using advanced authentication techniques such as PKI devices, card readers, and fingerprint readers, as the primary authentication. NetIQ Advanced Authorization (AA) Server (version 6.2 or later) must be installed first. For details on how to download and setup the AA server, see the Net IQ documentation.

The following list briefly describes the configuration for the AA server:

1. Repository - A repository is a central location where the user’s data is stored. This must point to LDAP directory. Advanced Authentication uses the repository only to retrieve the user information and configurations in Advanced Authentication do not affect the repository.
2. Methods – A method is a way of authenticating the identity of an individual who attempts to access an endpoint. Based on what is chosen for second factor, methods can be configured. For example, Email OTP can be configured to change the format of OTP code, body of the email and validity period.
3. Chains - A chain is a combination of authentication methods. A user must pass all methods in the chain to be successfully authenticated. For example, if you create a chain with LDAP Password and Email OTP, a user must first specify the LDAP Password. If the LDAP password is correct, the system sends an email with a One-Time-Password (OTP) to the user’s email address. The user must then enter the correct OTP to be authenticated.
4. Events – Advanced Authentication provides authentication events that can be used to integrate with StarTeam. Events are useful when using non-password based authentication as the first factor. Each event can be configure to use specific authentication chains.
5. Endpoints - Endpoints are devices where AA server authenticates. Users should manually create a new endpoint AA server endpoint id. Once a new endpoint is created, take down the values specified in Endpoint ID and Endpoint Secret and place them in a secure place in your application. NOTE: You will not be able to get the Endpoint ID and Endpoint Secret later on the appliance.
6. Enable SSL - Advanced Authentication server uses the HTTPS protocol. You must create a certificate file that is in the .pem or .crt, or .pfx format. You must upload the existing SSL certificate on the AA server. Note that AA server’s SSL/TLS certificate needs to be imported into the key store used by OSP.

Once, the AA server is installed and configured, enable Multi-factor authentication in StarTeam server by selecting Enable Multi-Factor authentication.

Provide the following information:

• AA server base URL: The URL should be of the format https://<AA server address>/api/v1. Replace AA server address to point to the IP address of the AA server host machine.
• AA Admin name: Enter the user that has administrator privileges on AA server.
• AA Admin password: Enter the AA user’s password that has administrative privileges.
• Endpoint ID: Enter the ID of the newly created endpoint in AA server.
• Endpoint Secret: Enter the secret of the newly created endpoint in AA server.
• Repository Name: Configure repository in AA server to point to your LDAP repository. AA server will use this repository for authenticating the users. Enter the name of the repository that was added in AA server in the text field.

 

Once, the above details are configured, you must restart StarTeam server and the Web service in order to allow the configuration to take effect.

Advanced Authentication server supports a number of options that can be used for second factor authentication. Administrators can enable/disable Methods, set priorities by editing the file authcfg.xml in the <StarTeam server install path>\OSP\WEB-INF\conf\current\starteam\services folder.

The NaafFactor element in the authcfg.xml file contains the AA methods to be enabled for 2nd factor. Email OTP and SMS OTP are enabled by default in the installed configuration file, with SMS OTP having higher priority. Note that SMS and Email Sender should be configured in AA server.

SMS OTP would not work if a user does not have their mobile number property set in their LDAP directory and the user would get an Email OTP instead. Users with valid mobile number will get a SMS OTP. The methods can be configured as desired. For example, the SMS OTP method can disabled as shown below.

To use a non-password authentication like Public Key Infrastructure (PKI) as the first factor instead of LDAP credentials, select the Delegate authentication to AA server option and enter the event name that was configured in Advanced Authentication server. Authentication will now be completely delegated to Advanced Authentication server and methods are executed in the order defined in the chain used in the event.

Back to top

Using PKI devices for authentication

A PKI device is a hardware device such as a contact card and USB token that contains the digital certificate. The PKI reader validates the digital certificate and the identity of users. When you try to authenticate on any device, the certificate in the device is compared with the actual certificate. If the certificates are identical, you are authenticated successfully.

Advanced Authentication Device Service is required for enrolling the PKI method using PKI device. AA device service is installed along with 17.1 version or later of StarTeam server and StarTeam clients and which support Multi-factor authentication.

Each user must enroll their PKI device with the AA server. Go to https://<AA server address>/account/authenticators.

To enroll the PKI Authenticator using the PKI Device#:

1. Click the PKI icon in Add Authenticator.
2. (Optional) Specify a comment in the Comment.
3. (Optional) Select the preferred category from Category. A message waiting for the card is displayed.
4. Click Save.
5. Insert the card into the reader or connect the token to the machine.
6. A message Use an existing certificate or generate a key pair is displayed.
7. Select a key from Key. If you have connected the token or card reader, the certificate type and expiry date of certificate is automatically populated in Key.
8. Specify the PIN code of the device.
9. Click Save. A message Authenticator "PKI" has been added is displayed.

For more information on enrolling and troubleshooting PKI devices for authentication, refer to the NetIQ documentation.

Back to top

Enforcement of Single Sign-on/Multi-factor authentication

By default, SSO and MF authentication are not enforced on users even when they are enabled on the StarTeam server. Users can continue to login using an older version (less than 17.1) of StarTeam client or by disabling SSO authentication in 17.1 + clients. However, StarTeam server administrators can enforce SSO/MFA authentication on selected users.

To enforce SSO and MF authentication:

1. Select Tools->Accounts->User Manager.
2. Right click on selected or all users and select Enforce Single Sign-On/ Multi-Factor Authentication.

Alternatively, go to the User properties for a specific user, navigate to the Logon tab and select Enable Single Sign-on/Multi-Factor authentication.

Once enforced, users are required to use SSO/ MF authentication to login to StarTeam server. Any attempts to login using an older client (less than 17.1 version) or using the native StarTeam login dialog will be blocked.

To skip SSO/MFA enforcement for a specific application, edit the app-control.xml file located in the AppControl folder under the repository folder. A new attribute named AllowPassword was introduced for this purpose.

To allow Pulse App to login with password, even when "enforce SSO/MFA" is checked, add this entry to app-control.xml:

To allow Atlas and Rhythm applications to login with password, even when "enforce SSO/MFA" is checked, add this entry to app-control.xml:

To allow StarTeam Connector application to login with password, even when "enforce SSO/MFA" is checked, add this entry to app-control.xml:

Back to top

Enabling SSL connections on Tomcat Web Server

By default, Single sign-on authentication does not use secure connection. To enable SSL connection on Tomcat web server, check the Tomcat documentation (SSL/TLS configuration How-to section):

For implementing SSL, tomcat web server must have an associated certificate. Certificates must be issued by Certificate Authority (CA) for production use. Self-signed certificates can be used for testing purpose.

Once certificates are obtained, they need to be imported into a key store. Tomcat currently operates only on JSK, PKCS11 or PKCS12 format key stores.

Once the certificates are imported into a supported keystore, configure the Connector in the <Server install>/WebServer/conf/server.xml file. A sample <Connector> element for an SSL connector is included in the default server.xml file installed with Tomcat. To configure an SSL connector that uses JSSE, you will need to remove the comments and edit it so it looks something like this:

Comment out the default connector on port 9090.

Next, change the Oauth2 issuer URL in Authentication tab in Server administration tool to https:// and modify the http port to the newly configured secure port. Also set the RESTServicePort option in starteam-server-config.xml to the secure port. This is required to ensure that Search and Pulse services work correctly with SSL connection.

Upon restarting the StarTeam web service and StarTeam server, SSL is enabled and all SSO/MF authentication requests will be encrypted.

Back to top

Server administration login using SSO/MFA

On a server configuration which has SSO/MFA enabled, there are two ways for an administrator to login. By default, all logins use the native StarTeam login dialog (password based authentication).

If an administrator needs to use SSO/MF authentication, they would need to select Actions-> Logon using the Single Sign-on authentication menu. The user is redirected to the system browser to complete the required authentication steps as configured.

Back to top