SAML SSO Configuration Guide🔗

This guide walks you through configuring SAML-based Single Sign-On (SSO) for the Apheris Governance Portal.

Once configured, users in your organization will be able to log in to the Apheris Governance Portal using their company email address and your organization's identity provider.

Prerequisites🔗

Access to your organization's Identity Provider (IdP) with permissions to create/configure SAML applications
Ability to create and manage security groups in your IdP
Administrative access to assign users to those groups

Setup Process🔗

Metadata Exchange - Exchange SAML metadata between your IdP and Apheris
Attribute Mapping Configuration - Configure user attribute claims
Group Claims Configuration - Configure group claims for role-based access control
Testing - Validate the integration

1. Metadata Exchange🔗

Provide Your Metadata to Apheris🔗

Share your IdP's metadata XML file or URL with your Apheris contact. This file contains the SSO Login URL and X.509 Certificate required for the SAML connection.

Receive Apheris Metadata🔗

After receiving your metadata, Apheris will create the SAML connection and provide you with a metadata XML file containing the required configuration values. You'll use this file to complete your IdP configuration.

2. Attribute Mapping Configuration🔗

Your IdP must send the following user attributes in the SAML assertion. Configure your IdP's SAML attribute statements or claims to match these exact claim names, mapping each to the appropriate user attribute from your directory:

Attribute	Claim Name (URI)	Source
User ID	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier`	User principal name or unique identifier
Email	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`	User email address
Name	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`	User display name
Given Name	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`	User first name
Family Name	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`	User last name
Groups	`http://schemas.xmlsoap.org/claims/Group`	User group memberships (see 3. Group Claims Configuration)

3. Group Claims Configuration🔗

Apheris uses role-based access control (RBAC). Users must be assigned to specific groups in your IdP, and these groups must be sent in the SAML assertion.

Create Security Groups🔗

Create four security groups in your IdP with names following this pattern:

<YOUR_PREFIX>_data-scientist
<YOUR_PREFIX>_data-steward
<YOUR_PREFIX>_model-manager
<YOUR_PREFIX>_owner

For detailed role descriptions and permissions, see Managing users and permissions.

Assign Users to Groups🔗

Assign your users to the appropriate groups based on their required access level.

Configure Group Claims🔗

Critical Configuration

This is the most common source of SSO integration issues. Please follow these instructions carefully.

Configure your IdP to send a group claim that meets the following requirements:

The claim must be multi-valued (array of groups)
The claim must contain group names (not IDs or GUIDs)
Configure the source attribute to send group names (e.g., sAMAccountName for on-prem AD, group display name for cloud-only groups)
Do not send Group IDs/GUIDs - these will not match the configured group mapping

Important

The claim name must match exactly: http://schemas.xmlsoap.org/claims/Group

Provide Group Names to Apheris🔗

Send your Apheris contact the exact names of the four groups you created:

<YOUR_PREFIX>_data-scientist
<YOUR_PREFIX>_data-steward
<YOUR_PREFIX>_model-manager
<YOUR_PREFIX>_owner

Apheris will configure the mapping from your group names to Apheris roles.

4. Testing🔗

Navigate to https://web.<network>.apheris.net where <network> is your network identifier (e.g., aisb or admet)
Enter your organization name (this will be provided by Apheris)
You should be redirected to your IdP's login page
Log in with a test user who is assigned to at least one of the four groups
After successful authentication, you should be redirected back to the Apheris Governance Portal
Verify that the user can access the Apheris Governance Portal
Check that the user has the correct roles assigned by clicking on their name in the bottom left navigation pane to view their profile

Troubleshooting🔗

Issue: User can log in but has no roles assigned🔗

Possible Causes:

Groups are not being sent in the SAML assertion
Groups are in the wrong format

Solution:

Verify groups claim is configured in your IdP
Check that the claim name is exactly http://schemas.xmlsoap.org/claims/Group
Confirm groups are being sent as names, not GUIDs
Verify the user is actually a member of one of the groups that were set up in Create Security Groups