Unstract Roles Guide

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

info

Please skip this guide if Enterprise SSO is not required for your Unstract installation.

Prerequisites

Before proceeding, ensure:

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

Supported Unstract Roles

The following roles are available in Unstract:

Unstract Role	Description
unstract_admin	Full administrative access
unstract_user	Standard user access
unstract_supervisor	Supervisory access
unstract_reviewer	Review access
unstract_platform_admin	Platform-level administrative access

1. Steps to be Done by Customer IdP Team

The identity provider (IdP) team is responsible for creating user directory groups and sharing the details with the Ops team.

1. Identify the identity provider — Determine whether your organization uses Microsoft Azure AD or Okta Workforce and follow the corresponding Enterprise SSO guide to configure the IdP integration.

2. Create user directory groups — Create a user directory group in your IdP for each Unstract role in each provisioned environment. For example:

   Unstract Role	Example Group Name
   unstract_admin	unstract_admin_<env>
   unstract_user	unstract_user_<env>
   unstract_supervisor	unstract_supervisor_<env>
   unstract_reviewer	unstract_reviewer_<env>

   note

   The group names above are examples. Use your organization's naming convention.

3. Assign users to groups — Add the appropriate users to each directory group based on their intended Unstract role and environment.

4. Share details with Ops team — Provide the following to the Ops team for role mapping configuration:

   • Identity provider name (one of okta, waad, samlp, oidc, or pingfederate)
   • The list of user directory group names created for each role and environment

2. Steps to be Done by Customer Ops Team

The Ops team maps the IdP groups to Unstract roles using the details received from the IdP team. There are two ways to do this:

• Method A — Automated (recommended): Declare the mappings in your Helm values and let a one-time setup Job apply them on install/upgrade. Available from on-prem release v0.170.0 onward.
• Method B — Manual: Run the init_domain command directly inside the backend pod.

Both methods write the same mappings to the application database — pick one. Method A is preferred because the mappings are declared alongside the rest of your Helm configuration and re-reconciled automatically on every upgrade.

Method A: Automated setup via Helm values

Availability

Available from on-prem release v0.170.0 onward. For earlier releases, use Method B.

Add the enterprise SSO keys to your on-prem values file under backend.configMap:

backend:
  configMap:
    # Enable the one-time enterprise SSO setup Job.
    ENABLE_ENTERPRISE_SSO_SETUP: "True"
    # Org display name — provided by the Unstract team.
    ORG_NAME: "Acme Corporation"
    # IdP group -> Unstract role mapping, as a JSON array string.
    ROLE_MAPPING: '[{"group":"unstract_admin_dev","unstract_role":"unstract_admin","provider":"okta"},{"group":"unstract_user_dev","unstract_role":"unstract_user","provider":"okta"}]'
    # Mappings are enforced at login only when authorization is enabled.
    DISABLE_SSO_IDP_AUTHORIZATION: "False"

The remaining inputs are taken from your existing configuration:

• domain is read from ingress.hostLookup.unstract — ensure it is set.
• client_id is reused from global.sharedConfigs.auth.ZIPSTACK_ID_CLIENT_ID — no separate value needed.

Configuration Reference

Key	Required	Description
ENABLE_ENTERPRISE_SSO_SETUP	Yes	Set to "True" to run the setup Job. Defaults to "False" (feature off).
ORG_NAME	Yes (when enabled)	The organization display name created on the Auth0 side. Contact the Unstract team to get this value.
ROLE_MAPPING	No	The IdP group-to-role mapping as a JSON array string. Defaults to "[]". See Role Mapping Fields for the entry structure.
DISABLE_SSO_IDP_AUTHORIZATION	No	Must be "False" for the mappings to be enforced at login. If "True", IdP group-to-role authorization is skipped and ROLE_MAPPING has no runtime effect. Enable both together.

Valid role and provider values

Each entry's unstract_role must be one of the Supported Unstract Roles. The provider must be one of the supported identity provider types: okta, waad (Azure AD), samlp (SAML), oidc, or pingfederate. Any entry with an unknown role or provider causes the Job to fail without applying changes.

How the Setup Job Works

When ENABLE_ENTERPRISE_SSO_SETUP is "True", a one-time Job runs manage.py init_domain on each Helm install/upgrade to reconcile the mappings:

• Runs on change only — the Job is content-hashed over the SSO config (domain, ORG_NAME, ROLE_MAPPING) and the backend image tag. It re-runs when any of these change; an unchanged re-apply is a no-op.
• Full declarative reconcile — ROLE_MAPPING is the complete desired state. Each run replaces all existing role mappings for the domain. An empty array ("[]") clears all mappings.
• Fails loudly — the entire payload is validated (required fields, JSON shape, and role/provider enums) before any change is applied. If any entry is invalid, the Job fails and no partial changes are saved.

Verify the Configuration

Check the setup Job logs, then confirm the mappings with the list command:

# Find the enterprise SSO setup Job (its name embeds the image tag and a config hash)
kubectl get jobs -n <namespace> -l app.kubernetes.io/component=enterprise-sso-init-domain

# View that Job's logs (use the Job name from the previous command)
kubectl logs -n <namespace> job/<enterprise-sso-init-domain-job-name>

# List configured domains and role mappings
kubectl exec -n <namespace> <backend-pod-name> -- \
    bash -c "source /app/.venv/bin/activate && python manage.py list_domains"

Method B: Manual setup via the init_domain command

Instead of the Helm values above, the Ops team can map the IdP groups to Unstract roles directly in the application database using the details received from the IdP team.

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	The application domain (same as ZIPSTACK_ID_DOMAIN in your Helm secret values)
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 Unstract Roles)
provider	The identity provider type — one of okta, waad (Azure AD), samlp (SAML), oidc, or pingfederate

Example Configuration

{
    "domain": "acme.com",
    "client_id": "xYz789AbCdEf",
    "org_name": "Acme Corporation",
    "role_mapping": [
        {
            "group": "unstract_admin_dev",
            "unstract_role": "unstract_admin",
            "provider": "okta"
        },
        {
            "group": "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": "unstract_admin_dev",
            "unstract_role": "unstract_admin",
            "provider": "okta"
        },
        {
            "group": "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: unstract_admin_dev -> unstract_admin
Created CustomDomainRoles: 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.

3. Steps to be Done by Customer Dev Team

Once the IdP and Ops teams have completed the setup above, users can log in to Unstract with their SSO credentials. Access is governed by the Unstract role mapped to their IdP group.

1. Log in to Unstract — Navigate to the Unstract UI and sign in using your organization's SSO. You will be authenticated through your identity provider and assigned the Unstract role corresponding to your IdP group membership.

2. Verify your role — After logging in, confirm that your access level matches the expected Unstract role assigned by the Ops team.

note

If you are unable to log in or your access level is incorrect, contact your Ops team to verify the role mapping configuration. Users whose IdP group is not mapped to an Unstract role will be forbidden from accessing the application.