---
title: "Auto Provisioning"
description: "Automatically create and manage user accounts from external identity providers"
---

Auto provisioning is a feature that allows you to automatically create and manage user accounts in Pangolin when they log in using an external identity provider rather than pre-provisioning a user with a role. This is useful for organizations that want to streamline the onboarding process for new users and ensure that their user accounts are always up-to-date.

You will be able to programmatically decide the roles and organizations for new users based on the information provided by the identity provider.

## Enable Auto Provision

Toggle the "Auth Provision Users" switch when creating or editing an identity provider.

<Frame>
  <img src="/images/auto-provision.png" />
</Frame>

## What if Auto Provisioning is Disabled?

If auto provision is disabled, organization admins will need to manually create the user accounts and select the role for each user. When creating a user, you can select the identity provider that the user will be associated with. A user will not be able to log in using the identity provider if a user is not pre-provisioned in the system.

<Frame>
  <img src="/images/create-idp-user.png" />
</Frame>

## Configuration Options

## Selecting Roles

You can choose between "Select a Role" and "Expression". Selecting a role will apply that role to all auto provisioned users. The expression will be evaluated against the token response from the IdP on each login (see examples below). You can always manually change the role of the user after they're provisioned.

### Expressions

Use JMESPath to map attributes from the identity provider to roles in Pangolin. See [JMESPath](https://jmespath.org/) for more information on how to use JMESPath.

The expression will be matched against each organization. Meaning:

- The result of the expression must return the exact string of the role name as it is defined in the organization.
- If no matching role is found, the user will not be added to the organization.

### Example: Role Selection 

**Expression:**

<Note>
When entering in a string, JMESPatch requires it be surrounded by `'` (single quotes). See below:
</Note>

```
contains(groups, 'admin') && 'Admin' || 'Member'
```

**Identity Provider Data:**
```json
{
   ...
    "sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
    "aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
    "exp": 1745790819,
    "iat": 1745789019,
    "auth_time": 1745789019,
    "email": "user@example.com",
    "email_verified": true,
    "name": "Example User",
    "groups": [
        "home-lab",
        "admin"
    ]
}
```

This example will return the string "Admin". If the user is not a member of the "admin" group, it will return "Member".

## Global Identity Providers

After you create an IdP, on the edit page, you can manage organization policies via the "Organization Policies" tab. You can set default (fallback) policies, or define them on a per org basis.

### How Organization Policies Are Evaluated

It is helpful to think of the auto provisioning process as follows:

<Steps>
<Step title="User Login">
  User successfully logs in using an identity provider.
</Step>

<Step title="Account Creation">
  Pangolin creates a user account for the user.
</Step>

<Step title="Organization Evaluation">
  Pangolin will loop through each organization and evaluate the JMESPath expression for the organization. If the expression does not return true or the same ID as the current organization, the user will not be added to the organization.
</Step>

<Step title="Role Assignment">
  For each organization, Pangolin will evaluate the JMESPath expression for the role. If no role is found with the exact name in that organization, the user will not be added to the organization.
</Step>
</Steps>

### Selecting Roles

See above examples.
 
### Selecting Organizations

Use JMESPath to map attributes from the identity provider to organizations in Pangolin. See [JMESPath](https://jmespath.org/) for more information on how to use JMESPath.

The expression will be matched against each organization. Meaning:

- The result of the expression must return true or the organization ID as it is defined in the system.
- If no matching organization is found, the user will not be added to the organization.

You can insert the template variable `{{orgId}}` in the expression. This will be replaced with the organization ID when the expression is evaluated.

### Example 1: Group-based Selection

**Expression:**
```
contains(groups, 'home-lab')
```

**Identity Provider Data:**
```json
{
   ...
    "sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
    "aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
    "exp": 1745790819,
    "iat": 1745789019,
    "auth_time": 1745789019,
    "email": "user@example.com",
    "email_verified": true,
    "name": "Example User",
    "groups": [
        "home-lab",
        "admin"
    ]
}
```

This example will return true since the user is a member of the "home-lab" group.

### Example 2: Fixed Organization

<Note>
When entering in a string, JMESPatch requires it be surrounded by `'` (single quotes). See below:
</Note>

**Expression:**
```
'home-lab'
```

**Identity Provider Data:**
```json
{
   ...
    "sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
    "aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
    "exp": 1745790819,
    "iat": 1745789019,
    "auth_time": 1745789019,
    "email": "user@example.com",
    "email_verified": true,
    "name": "Example User",
    "groups": [
        "home-lab",
        "admin"
    ]
}
```

### Default (Fallback) Policy

You can optionally configure a default policy for all organizations. This will be used if the organization does not have its own policy configured.

This example will always return 'home-lab' meaning the user will always be added to the "home-lab" organization.

### Example 1: Dynamic Organization Selection

**Expression:**
```
contains(groups, '{{orgId}}')
```

**Identity Provider Data:**
```json
{
   ...
    "sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
    "aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
    "exp": 1745790819,
    "iat": 1745789019,
    "auth_time": 1745789019,
    "email": "user@example.com",
    "email_verified": true,
    "name": "Example User",
    "groups": [
        "home-lab",
        "admin"
    ]
}
```

When Pangolin evaluates this expression against the "home-lab" organization, it will replace `{{orgId}}` with "home-lab". The result of the expression will return true since the user is a member of the "home-lab" group.
