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

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 (e.g., okta, azure_ad, okta_saml)
   • 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 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 (e.g., okta, azure_ad, okta_saml)

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.