SSO Group-to-Role Mapping Guide

This guide explains how to map your identity provider's groups to Unstract roles, enabling role-based access control through Enterprise SSO.

info

This step is only required if you have configured Enterprise SSO for your Unstract deployment. If you are not using Enterprise SSO, you can skip this guide.

Prerequisites

Before proceeding, ensure:

• Unstract is deployed and running per the On-Prem Deployment Guide.
• Your identity provider (IdP) is configured per the Azure AD or Okta Enterprise SSO guide.

Step 1: Prepare the Configuration File

Create a JSON configuration file (e.g., domain-config.json) with the following structure:

{
    "domain": "<your-domain>",
    "client_id": "<your-sso-client-id>",
    "org_name": "<your-organization-name>",
    "role_mapping": [
        {
            "group": "<idp-group-name>",
            "unstract_role": "<unstract-role>",
            "provider": "<identity-provider>"
        }
    ]
}

Field Reference

Field	Required	Description
domain	Yes	Your organization's domain (e.g., yourcompany.com)
client_id	Yes	The Auth0 client ID (same as ZIPSTACK_ID_CLIENT_ID in your Helm secret values)
org_name	No	The organization name created on the Auth0 side. Contact the Unstract team to get this value.
role_mapping	No	Array of group-to-role mappings (see below). Technically optional, but must be provided to enable group-to-role assignment.

Role Mapping Fields

Each entry in role_mapping requires all three fields:

Field	Description
group	The group name as configured in your identity provider
unstract_role	The Unstract role to assign (see supported roles table below)
provider	The identity provider type (e.g., okta, azure_ad, okta_saml)

Supported Unstract Roles

Each Unstract role must be mapped to a corresponding group in your identity provider's directory.

Unstract Role	Customer Directory Group (example)
unstract_user	customer_unstract_user_dev
unstract_admin	customer_unstract_admin_dev
unstract_supervisor	customer_unstract_supervisor_dev
unstract_reviewer	customer_unstract_reviewer_dev

note

The customer directory group names above are examples. Replace them with the actual group names configured in your identity provider.

Example Configuration

{
    "domain": "acme.com",
    "client_id": "xYz789AbCdEf",
    "org_name": "Acme Corporation",
    "role_mapping": [
        {
            "group": "customer_unstract_admin_dev",
            "unstract_role": "unstract_admin",
            "provider": "okta"
        },
        {
            "group": "customer_unstract_user_dev",
            "unstract_role": "unstract_user",
            "provider": "okta"
        }
    ]
}

Step 2: Identify the Backend Pod

kubectl get pods -n <namespace> | grep backend

Step 3: Run the Init Domain Command

Run the following command to write the configuration and initialize the domain:

kubectl exec -n <namespace> <backend-pod-name> -- \
    bash -c 'source /app/.venv/bin/activate && cat > /tmp/domain-config.json << '\''EOF'\''
{
    "domain": "acme.com",
    "client_id": "xYz789AbCdEf",
    "org_name": "Acme Corporation",
    "role_mapping": [
        {
            "group": "customer_unstract_admin_dev",
            "unstract_role": "unstract_admin",
            "provider": "okta"
        },
        {
            "group": "customer_unstract_user_dev",
            "unstract_role": "unstract_user",
            "provider": "okta"
        }
    ]
}
EOF
python manage.py init_domain /tmp/domain-config.json && rm /tmp/domain-config.json'

note

Replace the JSON values above with your actual domain, client ID, organization name, and role mappings.

On success, you should see output similar to:

Created CustomDomains: acme.com
Created CustomDomainOrg: acme.com -> Acme Corporation
Created CustomDomainRoles: customer_unstract_admin_dev -> unstract_admin
Created CustomDomainRoles: customer_unstract_user_dev -> unstract_user
Domain initialization complete.

Step 4: Verify the Configuration

Run the list command to confirm everything was set up correctly:

kubectl exec -n <namespace> <backend-pod-name> -- \
    bash -c "source /app/.venv/bin/activate && python manage.py list_domains"

Important Notes

• Idempotent: The command is safe to re-run. If the domain already exists, it will update the existing configuration.
• Role mappings are replaced: Each time you run the command, all existing role mappings for that domain are deleted and recreated from the JSON file. Ensure your configuration file contains the complete set of role mappings.
• Atomic operation: All changes are applied together. If any step fails, none of the changes are saved.
• Invalid role entries are skipped: If a role mapping is missing any required field (group, unstract_role, or provider), that entry is skipped with a warning. Other valid entries are still processed.