Authentication

Humanitec supports 3 Authentication mechanisms:

• Google
• GitHub
• Single Sign On via SAML

Users can sign up directly using Google or GitHub without any other configuration. For users to use Single Sign On (SSO) with SAML, further configuration is necessary.

Configuring SAML (Security Assertion Markup Language) #

To connect your SAML Identity Provider (IdP) with Humanitec, reach out to Humanitec support. This guide provides an overview of the SAML integration process and the steps required to configure the IdP.

Overview #

The integration between Humanitec and your SAML IdP enables users to authenticate using SAML-based Single Sign-On (SSO), like Okta. By following the instructions below, you can configure the SAML settings on both ends to establish a secure and seamless authentication flow.

The steps are as follows:

1. Required information #

Before you contact Humanitec, you must:

• have already created a Humanitec Organization and know its ID,

• choose an existing user who has the Administrator role in the Organization to act as the authorization mechanism for new SAML users (*),

• decide what role you want users accessing via SAML to have by default. It must be one of Member, Manager or Administrator. See RBAC for more information.

• have the following Identity Provider SAML Metadata available:

  • An SSO URL - The URL to redirect to perform the Identity retrieval
  • An Entity ID - This is a unique ID representing the App.
  • A Certificate - This is used to verify the assertions.

  This information is normally available bundled together as an IDPSSODescriptor or SAML Metadata file.

  • In Microsoft Entra: On the Set up single sign-on with SAML page, in the SAML Signing Certificate section, find Federation Metadata XML and select Download.
  • In Google Workspace: Under Web and Mobile apps, in the Humanitec app, select Download Metadata.

• The domain that your SAML users have email addresses under. For example, everything after the @ in the email address. This is used to restrict the users that can sign in via SAML to those with email addresses under this domain.

• Optionally, provide the mapping between the user groups and the Humanitec Organization Roles that will be applied when users sign on for the first time.

(*) The administrative user will not have to approve each new user. It is used internally to technically add new users to the Organization.

Since this user is not authenticated via SAML, it is also a breakglass account if the SAML authentication should fail, e.g. due to expired certificates.

2. Contact Humanitec support #

Contact Humanitec support and provide the previously listed information. You will receive a response with the following information:

• An ACS URL: The Assertion Consumer Service (ACS) URL provided by Humanitec, in the following format: https://api.humanitec.io/auth/saml/{SAML_ID}/acs.
• Entity ID: The Entity ID for Humanitec’s SAML integration, in the following format: https://api.humanitec.io/auth/saml/{SAML_ID}/metadata.

3. Configure your SAML Service Provider (SP) #

• Enter the An ACS URL and Entity ID

• Set the Name ID Format to EMAIL

• Define claims that Humanitec can read properties from. Humanitec understands the following claims:

  • email
  • firstName
  • lastName
  • displayName
  • groups - This attribute should contain the groups that the user belongs to. It can be reduced but must include all groups provided in the mapping in step 1.

  If displayName is provided, firstName and lastName will be ignored if present. If email is not provided, it will default to the Named ID.

These mappings are case sensitive and should not be prefixed with any schema namespace uri.

User data collected from claims is only updated the first time the user logs in.

• Test the sign-in process by visiting: https://app.humanitec.io/auth/login and selecting on the Single Sign-on (SSO) button.