SAML 2.0 authentication
SAML 2.0 authentication allows single sign-on for users and collaborators by creating or updating their account through an external Identity Provider.
When you use Helix TeamHub with Helix authentication and want users to authenticate via an identity provider (IdP), you must use the Helix Authentication Service (HAS) instead of configuring SAML authentication through TeamHub. See Using the Helix Authentication Service for single sign-on for information.
Accessing repositories over the HTTPS protocol requires setting up a TeamHub password.
With Helix authentication, certain restrictions apply to TeamHub functionality. For details, see Limitations with Helix authentication.
Configure SAML authentication
It is recommended to use SAML over SSL. Configure SSL to your instance first.
Log in to Helix TeamHub Client with a Company Admin account (On-premises users: login to your instance), click the company name on the top navigation and select Overview. Click on Company Settings link on top of the page, select Authentication tab, and enable SAML authentication:
| Name | Description | Required/Optional |
|---|---|---|
IdP SSO URL
|
Authentication endpoint of the Identity Provider. | Required
|
IdP certificate
|
Certificate of the Identity Provider. | Required
|
Signed authentication
|
When enabled, authentication requests are signed with provided private key. | Optional
|
Signed metadata
|
When enabled, metadata is signed with provided private key. | Optional
|
Certificate
|
Certificate of the Service Provider. | Optional
|
Private key
|
Private key of the Service Provider. | Optional
|
Configuring certificate and private key are optional, but required when signing is enabled. Metadata and authentication requests are signed with SHA1 algorithm (http://www.w3.org/2000/09/xmldsig#rsa-sha1) when enabled.
Certificates (X.509) and private key (RSA) must be given in PEM format, with base64 encoded content between header and footer lines. A self-signed certificate and private key can be created with openssl:
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.key
Attributes
Identity Provider is expected to return following attributes in authentication response:
| Name | Description | Required/Optional |
|---|---|---|
email
|
Unique email of the account. | Required
|
short_name
|
Unique username of the account. Generated from email if not provided. | Optional
|
first_name
|
Given name of the account. | Optional
|
last_name
|
Surname of the account. | Optional
|
type
|
Defines type of the account to create. | Optional
|
By default a user account is created on the first log in. If the provided attributes include a type attribute and its value equals the configured collaborator type value, a collaborator account is created instead. Attribute name mapping can be optionally configured in Attribute mapping section.
Metadata
TeamHub supports SAML 2.0 Web Browser SSO Profile with Service Provider initiated HTTP Redirect binding for authentication requests and HTTP POST binding for responses. Service Provider metadata is available in http(s)://[hostname]/account/saml/[company]/metadata after enabling SAML authentication in the company.
- Service Provider Entity ID:
http(s)://[hostname]/account/saml/[company]/metadata - Authentication initialization:
http(s)://[hostname]/account/saml/[company]/init - Assertion Consumer Service:
http(s)://[hostname]/account/saml/[company]/consume - Name ID format:
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
Troubleshooting
- Make sure correct Identity Provider certificate is configured in the settings.
- Update metadata on Identity Provider after changing settings.
- Make sure server time is synced between TeamHub and Identity Provider.
- Inspect Identity Provider and TeamHub logs.
