Authentication

The Humanitec Platform Orchestrator supports three 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.
    • In Okta: Under SAML Signing Certificates in the Humanitec app, find Actions and select View IDP Metadata. Save the page as XML.

  • 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.

2. Contact Humanitec support

Contact Humanitec support and provide a SAML Metadata file as well as the previously listed information. You will receive a response with the following information:

  • The SAML ID: The identifier of your SAML IdP as it is registered in Humanitec.
  • 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.

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

Groups

Once your SAML Identity Provider is connected to the Humanitec Platform Orchestrator, you can leverage the Groups feature to make it easier to:

  • Reflect IdP groups membership into the Humanitec roles and permissions System
  • Handle team changes with minimum manual effort

Assigning roles to users via groups is complementary to assigning roles to Organization members directly. Roles obtained from both sources will be added up.

How do groups work?

A Group in the Platform Orchestrator RBAC system has the following properties:

  • It works like a User in the Platform Orchestrator RBAC.
    Organization, Application, and Environment Type Roles can be assigned, updated, and removed from a Group exactly as it works with users.
  • It is a collection of users. Members of a Group inherit permissions from the Group roles.
    If the user Jane holds the role member in her Organization and belongs to a group with administrator Organization role, she is still an Organization member but she can act as an administrator in the Organization due to the permissions inherited from the Group she belongs to.
  • User groups are synchronized between IdP and Orchestrator when a user logs in via the IdP SSO: the Orchestrator leverages the content of the groups attribute in the claims received by the IdP to make the user member of the groups listed in the attribute and previously registered under the Orchestrator.

Create a group

All the IdP groups that you want to use in the Orchestrator to define RBAC must be created under your Humanitec Organization with the desired Organization Role, the IdP ID, and the same group name the IdP will send in the groups attribute configured in step 3. Use the create group endpoint  to create the group:

humctl api post /orgs/$HUMANITEC_ORG/groups \
-d '{
"group_id": "group_id_in_idp",
"idp_id": "saml_id",
"role": "member"
}'

The received response will be similar to:

{
  "created_at": "2025-03-03T16:21:10.12728Z",
  "group_id": "group_id_in_idp",
  "id": "g-52e048fb-dfc5-5984-a399-1eb16c67a7be",
  "idp_id": "saml_id",
  "role": "member"
}

The id received in the response must be used to handle any role you want to assign to the newly created group using the Platform Orchestrator API  or the Humanitec Terraform Provider , as specified in the RBAC documentation section.

Change the Organization level role of a group

To change the Organization level role of a group, use the same command as for a regular user using the group ID:

humctl api patch /orgs/$HUMANITEC_ORG/users/g-52e048fb-dfc5-5984-a399-1eb16c67a7b \
-d '{
"role": "manager"
}'

Assign an Application level role to a group

For example, if you want that all the members of the DevX IdP group can update the Application sample-app in the Platform Orchestrator, once the group has been created as shown above, you can assign the developer role for the desired Application to it. Use this command:

humctl api post /orgs/$HUMANITEC_ORG/apps/sample-app/users \
-d '{
"id": "g-52e048fb-dfc5-5984-a399-1eb16c67a7b"
"role": "developer"
}'

Change the Application level role of a group

To change the Application level role for a group, use the same command as for a regular user using the group ID:

humctl api patch /orgs/$HUMANITEC_ORG/apps/sample-app/users/g-52e048fb-dfc5-5984-a399-1eb16c67a7b \
-d '{
"role": "viewer"
}'

Delete a Group from an Organization

A group can be removed from an Organization in the same way a user is removed from it:

humctl api delete /orgs/$HUMANITEC_ORG/users/g-52e048fb-dfc5-5984-a399-1eb16c67a7be

Overview

Organization Members
OSZAR »