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:
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).
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).
If the authentication is successful, the user is redirected to the Authorization Server’s (IdP) login page, through which the user logs in (C).
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).
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.
Log on to TeamForge as a Site Administrator.
Select My Workspace > Admin.
Select Projects > Identity.
Select the Federation tab.
Select the Use Federated Login check box and select SAML as the IdP from the drop-down list.
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 an 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 X509 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 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 Service Provider. It must be an URI. Assertion Consumer Service URL Defines the URL of the Service Providers 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 “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 “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]
Service Provider X509 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 by 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 "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 "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect” binding only. IDP Certificate Finger Print You can use the fingerprint instead of using the entire X509 certificate. IDP Certificate Finger Print 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 the 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 is 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 need to be encrypted or not. Values are True and False. Sign Metadata This indicates whether the SP Metadata need to be signed or not. Values are True (sign using SP private key) and False (or null to not to 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 signing process. Some of the options:
Reject Unsolicited Response To This indicates where to send the rejected unsolicited response. Compress Request This indicates whether the request need to be compressed or not. Values are True and False. Compress Response This indicates whether the response need to be compressed or not. Values are True and False. Technical Contact Name This indicates the contact name of the Technical person at Service Provider’s end. Technical Contact Email This indicates the email id of the Technical person at Service Provider’s end. Organization Name This indicates the organization name at Service Provider’s end. Organization Display Name This indicates the organization’s display name at Service Provider’s end. Organization URL This indicates the URL of the organization at 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 need to be mapped to user’s email id or not. Values are True and False.
Click Test Connection to verify whether the integration works properly with the IdP configured in this page.
Click Get SP Metadata to obtain the Service Provider’s metadata.
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.
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:
Click Login on your TeamForge site. You are redirected to the login page of third-party IdP.
Enter the SAML (third-party IdP) user credentials.
On successful login, you are redirected to the Create TeamForge Account page.
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.
Enter the values for other required fields.
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:
Click the Forgot Your Password link on the TeamForge Home page. You would receive an email with instructions to reset your password.
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.