Use SAML for TeamForge User Authentication

For more information about SAML, its concepts and components, see https://www.oasis-open.org/.

SAML Terms and Their Purpose

• End User / Browser: The end user is generally a human or a browser (agent) who accesses the Service Provider to get access to a service or a protected resource. The browser carries out all the redirections from the SP to the IdP and vice versa.

• Service Provider (SP): The entity that provides its protected resource when an end user tries to access this resource. To accomplish the SAML based SSO authentication, the Service Provider must have the Identity Provider's metadata.

  note

  It is not necessary that the authentication flow should start from a Service Provider. Even an IdP can initiate the authentication process.

• Identity Provider (IdP): Defines the entity that provides the user identities, including the ability to authenticate a user to get access to a protected resource / application from a Service Provider. To accomplish the SAML based SSO authentication, the IdP must have the Service Provider's metadata.

• SAML Request: This is the authentication request generated by the Service Provider to request an authentication from the Identity Provider for verifying the user's identity.

• SAML Response: The SAML Response contains the acutal assertion of the authenticated user and is generated by the Identity Provider. The SAML Response also consists of additional information such as user profile information, group or role information and so on based on what the Service Provider can support.

• Service Provider-initiated Authentication Flow: This describes the SAML authentication flow initiated by the Service Provider. The authentication process from the SP is triggered when the user tries to access a resouce or log on to the Service Provider application. A typical example is that a browser trying to access a protected resource from the Service Provider.

• Identity Provider-initiated Authentication Flow: This describes the SAML authentication flow initiated by the Identity Provider. Unlike the SP-initiated authentication flow in which the authentication is triggered by a redirection from the Service Provider, here the IdP initiates the SAML Response that is redirected to the SP to assert the user's identity.

How SAML-based SSO Works in TeamForge?

In addition to OAuth 2.0 (with Open ID Connect), TeamForge supports SAML (Security Assertion Markup Language) authentication and authorization protocol.

As in a typical SSO-enabled environment, Single Sign-on in TeamForge works in such a way that the Identity Provider "asserts" the identity of the user and the Service Provider consumes the "assertion" and passes the identity information to the application. This is done by exchanging digitally signed XML documents.

TeamForge, as a SAML compliant Service Provider, can be integrated with any SAML compliant Identity Provider. TeamForge Administrators should make sure that the Identity Provider is SAML 2.0 compliant and must keep the IdP metadata handy before configuring the IdP details in TeamForge.

SAML metadata is an XML file that contains configuration information to be shared between the Service Provider and the Identity Provider.

• The Service Provider metadata XML file contains the SP certificate, the entity ID, ACS parameters and so on. To get the TeamForge (Service Provider) metadata, check at: https://<<hostname>>/oauth/metadata.jsp

• The Identity Provider metadata XML file contains the IdP certificate, the entity ID, redirect URL, logout URL and so on.

TeamForge Administrator must keep the IdP metadata handy before integrating TeamForge with a SAML IdP. The following illustration shows the high-level authentication flow of SAML integration in TeamForge. This is typically a Service Provider-initiated SSO workflow.

Let's see how it works:

1. The end user tries to access a resource URL within the application provided by the Resource Server (Service Provider) via the Client application / Web Browser (A).

2. The Resource Server application generates the authentication request for user and sends it to Authorization Server (Identity Provider). The Service Provider uses the HTTP POST binding component to send the request to the IdP (B).

3. If the authentication is successful, the user is redirected to the Authorization Server's (IdP) login page, through which the user logs in (C).

4. The IdP generates the security token based on SAML assertions for the user and sends the response with the SAML token to the Resource Server application (D).

5. The user now gets a session in the Resource Server and can access the resources in it.

Setting up TeamForge in a SAML-compliant Third-party IdP Environment

For TeamForge to support SAML based SSO from a SAML-compliant third-party IdP, it is required to set up TeamForge in the IdP environment. This means that it is necessary to configure the SAML IdP with the details of TeamForge, who in this case is the SAML Service Provider.

Configuring a SAML IdP is beyond the scope of TeamForge Administrators, as you can use any third-party IdP based on the business requirements.

Once a SAML IdP has been set up, the SAML IdP administrator can set up TeamForge as a Service Provider with the SAML IdP and keep both the IdP and SP metadata handy for creating the TeamForge-SAML IdP integration in TeamForge.

For setting up SAML IdP integration in TeamForge, enable Federated Login in TeamForge.

1. Log on to TeamForge as a Site Administrator.

2. Select My Workspace > Admin.

3. Select Projects > Identity.

4. Select the Federation tab.

5. Select the Use Federated Login check box and select SAML as the IdP from the drop-down list.

6. Click Save.

   

7. Select the SAML tab. This page is used to capture the security configurations of TeamForge and the SAML IdP. The IdP details that you provide in this page is obtained from the metadata XML of the third-party IdP.

   important

   The Service Provider ACS (Assertion Consumer Service) Logout related properties are generated by the system, hence they should not be changed unless required.

   

   This table provides the parameters and their description used in the SAML configuration page.

   important

   Configuration details are mandatory for fields 1 through 8 for a basic SAML integration.

Parameter Name	Description
IDP Entity ID	Defines the unique identifier of the Identity Provider. It must be a URI.
IDP Single Sign-On URL	Defines the URL that defines the SSO endpoint of the IdP. It is the target URL of the IdP where the SP sends its authentication request message.
IDP X.509 Certificate	Defines the digital certificate that verifies the public key of the IdP.
IDP Single Sign-On Logout URL	Identity Provider’s Single Sign-On Logout URL. If the IdP does not support logout, leave this blank.
IDP Single Sign-On Logout Response URL	Defines the Single Sign-On Logout (SLO) endpoint of the IdP that specifies the URL location of the IdP where the SP will send the SLO response. If this is left blank, the same URL as the logout service URL will be used. This property can be used if the IdP uses a separate URL for sending a logout request and response.
Service Provider Entity ID	Defines the unique identifier of the Service Provider. It must be a URI.
Assertion Consumer Service URL	Defines the URL of the Service Provider's Assertion Consumer Service, where the assertion from the IdP will be sent.
Service Provider Logout URL	Defines the URL of the Service Provider where the Logout Response message will be returned.
Assertion Consumer Service Binding	Defines which SAML protocol binding to be used when returning the Response message. TeamForge supports the "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" binding only.
Service Provider Logout Binding	Defines which SAML protocol binding to be used when returning the logout response or sending the logout request message. TeamForge supports the "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" binding only.
Name ID Format	Defines the constraints on the name identifier to be used to represent the requested subject. It is a mandatory attribute sent by the IdP in its SAML response to make the federation. TeamForge supports the following three Name ID formats: - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified [default], - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
Service Provider X.509 Certificate	Defines the digital certificate that verifies the public key of the SP.
Service Provider Private Key	Defines the private key of the Service Provider. Required Format: PKCS#8 BEGIN PRIVATE KEY. If you have PKCS#1 BEGIN RSA PRIVATE KEY, convert it using “openssl pkcs8 -topk8 -inform pem -nocrypt -in sp.rsa_key -outform pem -out sp.pem”.
IDP Single Sign-On Service Binding	Defines the SAML protocol binding to be used when returning the response message. TeamForge supports the "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" binding only.
IDP Single Sign-On Logout Service Binding	Defines the SAML protocol binding to be used when returning the response message. TeamForge supports the "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" binding only.
IDP Certificate Fingerprint	You can use the fingerprint instead of using the entire X.509 certificate.
IDP Certificate Fingerprint Algorithm	If an IdP fingerprint is provided, then the fingerprint algorithm is required to let the toolkit know which algorithm is used. Possible values: sha1 (default value), sha256, sha384.
Use Strict Mode	Values are True and False. TeamForge rejects unsigned or unencrypted messages if the strict mode is set to True.
Debug	This is used to set the log level to debug. Values are True and False.
Logout Name ID Encrypted	This indicates that the Name ID of the logout response sent by the Service Provider will be encrypted. Values are True and False.
Sign Authentication Request	This indicates whether the AuthnRequest message sent by the Service Provider is signed. The Metadata of the SP provides this information. Values are True and False.
Sign Logout Request	This indicates whether the logout request messages sent by the Service Provider are signed. Values are True and False.
Sign Logout Response	This indicates whether the logout response sent by this Service Provider is signed. Values are True and False.
Sign Messages	This indicates whether the messages are to be signed or not. Values are True and False.
Sign Assertions	This indicates whether the response, logout request, and logout response elements received by the SP need to be signed or not. Values are True and False.
Encrypt Assertions	This indicates whether the assertions received by the Service Provider need to be encrypted or not. Values are True and False.
Need Name ID	This indicates whether the Name ID is required or not in the SAML response. Values are True and False.
Name ID Encrypted	This indicates whether the Name ID received by the Service Provider needs to be encrypted or not. Values are True and False.
Sign Metadata	This indicates whether the SP Metadata needs to be signed or not. Values are True (sign using SP private key) and False (or null to not sign).
Authentication Context	Defines the authentication context of the Service Provider. If no value is provided, then no authentication context will be sent in the AuthnRequest. Set the value as “urn:oasis:names:tc:SAML:2.0:ac:classes: urn:oasis: names:tc:SAML:2.0:ac:classes:Password”
Authentication Context Comparison	This allows the authentication context comparison parameter to be set. Default value is exact.
Validate XML	This indicates whether the Service Provider will validate all received XMLs. Note: To validate the XML, the Use Strict Mode to set to ‘strict’ and wantXMLValidation to be set to True.
Signature Algorithm	This indicates the algorithm that the toolkit will use during the signing process. Some of the options: - http://www.w3.org/2000/09/xmldsig#dsa-sha1 - http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 - http://www.w3.org/2001/04/xmldsig-more#rsa-sha384 - http://www.w3.org/2001/04/xmldsig-more#rsa-sha512
Reject Unsolicited Response To	This indicates where to send the rejected unsolicited response.
Compress Request	This indicates whether the request needs to be compressed or not. Values are True and False.
Compress Response	This indicates whether the response needs to be compressed or not. Values are True and False.
Technical Contact Name	This indicates the contact name of the Technical person at the Service Provider’s end.
Technical Contact Email	This indicates the email id of the Technical person at the Service Provider’s end.
Organization Name	This indicates the organization name at the Service Provider’s end.
Organization Display Name	This indicates the organization’s display name at the Service Provider’s end.
Organization URL	This indicates the URL of the organization at the Service Provider’s end.
Username Attribute	This indicates the username attribute of the IdP.
Email Attribute	This indicates the email attribute of the IdP.
User Display Name Attribute	This indicates the display name attribute of the user.
Map Email to Username	This indicates whether the username needs to be mapped to the user’s email id or not. Values are True and False.

8. Click Test Connection to verify whether the integration works properly with the IdP configured in this page.

9. Click Get SP Metadata to obtain the Service Provider's metadata.

10. Click Save to save the configuration.

Intermediate Login Page for Multiple User Accounts

In a SAML enabled and SAML+LDAP enabled environment, if you have multiple user accounts for the same email address, you will be redirected to an intermediate login page before the third party IdP for authentication. In this intermediate login page, you can see the list of accounts associated with your email address. Select one from this list and set it as default account so that you would log on with this account every time you are authenticated via the third party IdP. After you have set a default account, you would not see the intermediate login page the next time you are authenticated via SAML.

If you want to change or reset the default user account at any point in time, you can do so from the My Settings > Edit User Information page.

Direct Login to TeamForge

In a SAML-enabled TeamForge environment, TeamForge administrators are provided with a direct login URL which can be used to log on to TeamForge without any intermediaries such as an IdP whenever things go wrong (due to some changes in SAML IdP endpoints) and if TeamForge is not accessible.

You can also use this direct login to fix any issues with SAML configuration. The direct login URL for local TeamForge administrators can be found in the TeamForge SAML configuration UI. TeamForge Administrators are advised to bookmark or keep this URL handy.

note

Other users can use the ‘Forgot Password’ link at the login page to set the local TeamForge password that should authenticate them to carry out any other user activities based on their RBAC permissions.

Authenticate SAML Users to Access Non-web Applications

Earlier, users authenticated via SAML were able to access only the TeamForge web applications. From TeamForge 18.3, users in a SAML-enabled environment can access the non-web applications such as Git, SVN, and other CLI applications using their TeamForge credentials.

SAML users must have a TeamForge account to access the non-web applications.

• To create a new TeamForge account in a SAML-enabled environment:

  1. Click Login on your TeamForge site. You are redirected to the login page of third-party IdP.

  2. Enter the SAML (third-party IdP) user credentials.

     On successful login, you are redirected to the Create TeamForge Account page.

     

  3. Enter the password in the Password and Confirm Password fields.

     note

     The User Name and Email Address fields are read-only fields. All email communications to SAML users are sent via the email id provided in the Email Address field.

  4. Enter the values for other required fields.

  5. Click Create. Now you can use this password to log on to non-web applications.

     note

     If you have created the account without providing the password on the Create TeamForge Account page, you would receive an email with instructions to set the password.

• To enable the existing TeamForge users to reset their password in a SAML-enabled environment:

  1. Click the Forgot Your Password link on the TeamForge Home page. You would receive an email with instructions to reset your password.

  2. Reset the password based on the instructions in your reset password email.

     After resetting your TeamForge password, you can access the non-web applications using this password.

note

To enforce password security policy, site administrators can set the site-options.conf token REQUIRED_PASSWORD_SECURITY to true.