> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-jit-with-cisco-account.md).

# Configuring JIT Provisioning with Cisco Account

Just-in-time (JIT) provisioning creates or updates a ThousandEyes user when the user signs in through Cisco account. It uses identity, profile, and role or group information from your identity provider (IdP).

JIT provisioning runs when a user signs in. It is not a continuous provisioning or deprovisioning service. When JIT processes a login, ThousandEyes determines the user’s roles and account-group access from the configured role mappings.

Cisco account supports JIT provisioning with Security Assertion Markup Language (SAML) and OpenID Connect (OIDC). Both protocols use the same JIT role mappings in ThousandEyes. The protocol-specific difference is how Cisco Identity receives the identity, profile, and role or group values.

{% hint style="info" %}
JIT provisioning with Cisco account supports service provider (SP)-initiated login only. Start from the ThousandEyes login screen or an SP-initiated link. IdP-initiated launches, including launches from an IdP application catalog, are not supported for this workflow.
{% endhint %}

## How JIT Role Mappings Work

The role-mapping flow is the same for SAML and OIDC:

1. IdP role or group value.
2. SAML assertion attribute or OIDC ID-token claim.
3. Cisco Identity custom claim.
4. ThousandEyes JIT role attribute.
5. ThousandEyes role and account-group mapping.

The claim name must match the configured ThousandEyes JIT role attribute. Each incoming role or group value must exactly match the name of a ThousandEyes role in the mapping, including capitalization, spacing, and special characters. If a matching role does not exist, create a custom role with the same name as the incoming value.

For example, an OIDC ID token might contain:

```json
{"groups":["TE-JIT-Users"],"name":"Jane Doe"}
```

Configure the example as follows:

* **ThousandEyes JIT role attribute:** `groups`
* **ThousandEyes role:** Create or use a custom role named `TE-JIT-Users`.
* **ThousandEyes JIT role mapping:** Select the `TE-JIT-Users` role and the account groups it can access.

For group-based mappings, send group values as an array when supported by your IdP. Create or use a ThousandEyes role with the same name as each group value that should provide access, then create one mapping for each value.

{% hint style="warning" %}
Maintain at least one mapping for the built-in **Organization Admin** role. This role provides the permissions required to manage users and JIT settings and controls access to the Cisco Identity tenant admin portal under **Manage > Account Settings > Organization Settings** and **Single Sign-On (SSO) > Go to admin portal**.

Assign this role to administrators who need tenant admin portal access. If an administrator does not receive a mapped **Organization Admin** role, the administrator can lose access to the tenant admin portal after the next login.
{% endhint %}

## Comparing SAML and OIDC JIT Provisioning

| Area                         | SAML                                                                        | OIDC                                                                                                       |
| ---------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| User identity                | SAML mapping attribute, such as `uid`                                       | OIDC identity claim, such as `email` or `mail`                                                             |
| Role or group values         | Attribute or custom claim in the SAML assertion                             | Custom claim in the OIDC ID token, commonly an array such as `groups`                                      |
| Cisco Identity configuration | SAML mapping attribute, custom claims, JIT settings, and profile attributes | OIDC metadata, scopes, discovery or endpoint settings, custom claims, JIT settings, and profile attributes |
| ThousandEyes role mappings   | Same JIT role-mapping settings                                              | Same JIT role-mapping settings                                                                             |

## Prerequisites

Before configuring JIT provisioning, make sure that you have:

* A Cisco account configuration with SSO enabled. For more information, see [Configure SSO with Cisco Account](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account).
* An account with your chosen IdP.
* An IdP configuration that sends a stable, unique, and verified identifier for each user.
* An IdP configuration that sends role or group values for users who need access to ThousandEyes.
* A test user assigned to a dedicated application group or role. Avoid relying only on broad default groups such as `Everyone`.
* A break-glass routing rule that allows at least one administrator to sign in with local Cisco account credentials if SSO configuration fails. For more information, see [Configure Routing Rules](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules).
* A ThousandEyes account assigned a role with the following permissions:

  * *Edit security & authentication settings*
  * *Edit users in all account groups*
  * *View security & authentication settings*
  * *View all account groups settings* or *View agents in account group* or *View all users*
  * *View roles* or *View all users*

  For more information about permissions, see [Role-Based Access, Explained](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/role-based-access-control-explained).

### Additional OIDC prerequisites

If you use OIDC, make sure that you have:

* An OIDC application registered with your IdP.
* The client ID, client secret, and redirect URI required by your IdP.
* An OIDC discovery URL or the required endpoint information.
* A role or group claim configured in the ID token.
* The required scopes, including `openid` and `email`.
* Claims configured on the same authorization server that Cisco account uses for login.

{% hint style="warning" %}
Do not use JIT provisioning and SCIM provisioning together. JIT provisioning can replace user profile and role information when the user signs in.

Keep SSO enabled while JIT provisioning is in use.
{% endhint %}

## Configure JIT Provisioning

Use this procedure to configure JIT provisioning with either SAML or OIDC. Protocol-specific steps are labeled where they apply.

Configure the IdP, Cisco Identity, and ThousandEyes settings in the following order.

### 1. Open the Cisco Identity Portal

1. In ThousandEyes, go to **Manage > Account Settings > Organization Settings**.
2. In the **Single Sign-On (SSO)** section, click **Go to admin portal**.
3. In the Cisco Identity portal, go to **Settings > Manage IdPs**.

### 2. Add or Edit the Identity Provider

1. To add a provider, click **+ Add an IDP**, select **SAML** or **OpenID Connect**, and click **Next**.
2. To edit a provider, click **...** next to the provider and select **Edit IdP**.

### 3. Configure the Protocol-Specific Settings

1. **(SAML only)** Configure the SAML metadata and the required **SAML mapping attribute**.

   Use the SAML attribute that identifies the user in your IdP. For example, map `uid` to the user’s email address, user principal name (UPN), or `eduPersonPrincipalName`. For more information, see [Configure SAML](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account#configure-saml).
2. **(OIDC only)** Configure the OIDC metadata, scopes, and discovery URL or endpoint information.

   Register the Cisco Identity redirect URI in your IdP application. For more information, see [Configure OpenID Connect](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account#configure-openid-connect).
3. **(OIDC only)** If your IdP supports more than one authorization server, verify which authorization server Cisco account uses for login.

   Configure the claims, scopes, and access policies on the authorization server identified by the discovery document’s `issuer` value.
4. **(OIDC only)** If you use a custom authorization server, define and allow the `groups` scope in its access policies.

{% hint style="info" %}
Claims configured on one authorization server do not automatically apply to another. For example, an Okta claim configured on `/oauth2/default` might not appear if Cisco account uses the Okta organization authorization server.
{% endhint %}

### 4. Open the JIT and Custom-Claims Settings

1. **(SAML only)** Expand **Configure custom claims, JIT settings, and linking attributes (optional)**.
2. **(OIDC only)** Expand **Configure Just-In-Time (JIT) settings and Custom Claims (optional)**.

### 5. Configure Custom Claims

1. **(SAML only)** Under **Custom claims**, add the role or group attribute from the SAML assertion.

   The claim name must match the ThousandEyes **SAML Role Name Attribute** setting.
2. **(OIDC only)** Under **Custom claims**, add the role or group claim from the OIDC ID token.

   Configure the claim in the IdP so it is included in the ID token. For group-based mappings, send the group values as an array.
3. Use the same claim name in the IdP, Cisco Identity, and ThousandEyes.

   For example, configure `groups` consistently in all three locations.
4. Configure profile claims such as `name`, `displayName`, or `mail` if you want Cisco Identity to forward them to ThousandEyes.

Cisco Identity supports a maximum of 25 custom claims. Claim names are case-sensitive. For example, `groups` and `Groups` are different claim names.

### 6. Configure JIT Settings

1. Select **Create or activate users**. This setting is required. It creates a user when no active user is found or activates an existing inactive user.
2. **(SAML only)** Select **Update user with SAML attributes** if you want to update existing users with attributes from the SAML assertion.
3. **(OIDC only)** Select **Update user with OIDC claims** if you want to update existing users with claims from the OIDC ID token.

### 7. Configure Linking, Profile, and Group Attributes

The source attribute and claim names below are examples. Replace them with the names sent by your IdP.

#### Linking Attribute

The linking attribute uniquely identifies a user so Cisco Identity can update the user’s profile, including the email address.

Map an immutable IdP attribute or OIDC claim to `externalId` when the user’s email address is not a permanent identifier.

| Protocol | Source attribute or claim example                            | Cisco Identity attribute | Description                                                                                             |
| -------- | ------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| SAML     | `user.objectid`                                              | `externalId`             | A unique attribute for identifying a user and updating the user’s profile, including the email address. |
| OIDC     | An immutable claim, such as `sub` or an IdP-specific user ID | `externalId`             | A stable identifier that remains consistent if the user’s email address changes.                        |

#### Profile Attributes

Configure only the profile attributes that your IdP sends and that you want Cisco Identity to maintain.

| Attribute type     | SAML attribute name      | SAML Cisco Identity attribute name | OIDC claim name     | OIDC Cisco Identity attribute name    | Description                                                                                                               |
| ------------------ | ------------------------ | ---------------------------------- | ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Primary identifier | `uid`                    | `Username/Primary email address`   | `mail` or `email`   | `uid`                                 | The user’s email address, UPN, or other supported primary identifier.                                                     |
| Profile            | `user.preferredlanguage` | `preferredLanguage`                | `preferredLanguage` | `preferredLanguage`                   | The user’s preferred language.                                                                                            |
| Profile            | `user.locale`            | `locale`                           | `locale`            | `locale`                              | The user’s locale.                                                                                                        |
| Profile            | `user.timezone`          | `timezone`                         | `timezone`          | `timezone`                            | The user’s primary time zone.                                                                                             |
| Profile            | `user.displayname`       | `displayName`                      | `displayName`       | `displayName`                         | The user’s display name.                                                                                                  |
| Profile            | `user.givenname`         | `name.givenName`                   | `given_name`        | `name.givenName`                      | The user’s first name.                                                                                                    |
| Profile            | `user.surname`           | `name.familyName`                  | `family_name`       | `name.familyName`                     | The user’s last name.                                                                                                     |
| Profile            | `user.streetaddress`     | `addresses.streetAddress`          | `street_address`    | `addresses.streetAddress;work`        | The street address of the user’s primary work location.                                                                   |
| Profile            | `user.locality`          | `addresses.locality`               | `locality`          | `addresses.locality;work`             | The city or locality of the user’s primary work location.                                                                 |
| Profile            | `user.region`            | `addresses.region`                 | `region`            | `addresses.region;work`               | The state or region of the user’s primary work location.                                                                  |
| Profile            | `user.country`           | `addresses.country`                | `country`           | `addresses.country;work`              | The country of the user’s primary work location.                                                                          |
| Profile            | `user.postalcode`        | `addresses.postalCode`             | `postal_code`       | `addresses.postalCode;work`           | The postal code of the user’s primary work location.                                                                      |
| Profile            | `work phonenumber`       | `phoneNumbers.work`                | `phone_number`      | `phoneNumbers;work;primary`           | The user’s work phone number. Use international E.164 format only, with a maximum of 15 digits.                           |
| Profile            | `mobile phonenumber`     | `phoneNumbers.mobile`              | `mobile_phone`      | `phoneNumbers;mobile;primary`         | The user’s mobile phone number. Use international E.164 format only, with a maximum of 15 digits.                         |
| Profile            | `extension phonenumber`  | `phoneNumbers.extension`           | `phone_extension`   | `phoneNumbers;work_extension;primary` | The work extension of the user’s primary work location. Use international E.164 format only, with a maximum of 15 digits. |
| Profile            | `user.jobtitle`          | `title`                            | `title`             | `title`                               | The user’s job title.                                                                                                     |
| Profile            | `user.department`        | `department`                       | `department`        | `department`                          | The user’s department or team.                                                                                            |
| Profile            | `work emails`            | `emails.work`                      | `email`             | `emails;work`                         | The user’s work email address.                                                                                            |
| Profile            | `user.organization`      | `organization`                     | `organization`      | `organization`                        | The user’s organization ID.                                                                                               |

If `displayName` is provided, ThousandEyes uses it. Otherwise, ThousandEyes combines `firstName` and `lastName`. If neither is available, it assigns **JIT Created User**.

#### Group Attributes

Group attributes are optional. Configure them only when you need to map IdP groups to Cisco Identity groups for licensing or service settings.

These attributes are different from the role or group claim used for ThousandEyes JIT role mappings.

| Protocol | Source attribute or claim example | Cisco Identity attribute | Description                                                                   |
| -------- | --------------------------------- | ------------------------ | ----------------------------------------------------------------------------- |
| SAML     | `user.groupid`                    | `groupId`                | Maps an IdP group identifier to a Cisco Identity group ID.                    |
| SAML     | `user.groupexternalid`            | `groupExternalId`        | Maps an IdP external group identifier to a Cisco Identity external group ID.  |
| OIDC     | `groupId`                         | `groupId`                | Maps an OIDC group identifier to a Cisco Identity group ID.                   |
| OIDC     | `group_external_id`               | `groupExternalId`        | Maps an OIDC external group identifier to a Cisco Identity external group ID. |

### 8. Save the Identity Provider

1. For a new provider, click **Add IdP**.
2. For an existing provider, click **Save**.

### 9. Configure JIT Role Mappings in ThousandEyes

{% hint style="info" %}
ThousandEyes uses the screen labeled **SAML Just-In-Time Settings** for both SAML and OIDC. There is no separate OIDC role-mapping screen.
{% endhint %}

1. Go to **Manage > Account Settings > Organization Settings > Security and Authentication**.
2. Scroll to **User Provisioning > SAML Just-In-Time Settings**.
3. Switch the **Enable** toggle on.
4. Select the **SAML Role Name Attribute** that contains the role or group values.

   For OIDC, select the custom claim name that Cisco Identity sends to ThousandEyes. If the claim name is not listed, select **Custom…** and enter it manually.
5. In the **Role** dropdown, select a ThousandEyes role whose name exactly matches the incoming role or group value. If a matching role does not exist, create a custom role with that name under **Manage > Account Settings > Users and Roles > Roles** before continuing.
6. In the **Account Groups** dropdown, select the account groups that the role can access.
7. Click **+ Add mapping** to add mappings or click the minus icon to remove them.
8. Include a mapping for the built-in **Organization Admin** role if administrators need access to the Cisco Identity tenant admin portal.
9. Click **Save**.

### 10. Test and Activate the Identity Provider

If you added a new IdP or changed the SSO configuration:

1. In Cisco Identity, go to **Settings > Manage IdPs**.
2. Open the actions menu for the IdP and select **Test SSO Setup**.
3. Complete the test login.
4. If the test succeeds, select **Successful test**.
5. Click **Activate SSO and IdP**.
6. Click **Save**.

For more information, see [Test Your SSO Setup](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/test-your-sso-setup).

### 11. Test JIT Provisioning

Test with a user assigned to the dedicated IdP group or role.

1. Open the following SP-initiated link in your browser:

   `https://app.thousandeyes.com/v2/login?fwd=/account/switch/<AID>`

   Replace `<AID>` with the account group ID.
2. If possible, use a private browser window to avoid cached authentication information.
3. Log in to your IdP when prompted.
4. Confirm that ThousandEyes creates or activates the user.
5. Confirm that the user receives the expected ThousandEyes roles and account-group access.
6. If profile updates are enabled, confirm that the expected profile attributes are updated.
7. If testing an administrator, confirm that the user can access the Cisco Identity tenant admin portal.

You can also enter your email address on the ThousandEyes login screen. If you are not already logged in to your IdP, ThousandEyes redirects you to the IdP and then returns you to ThousandEyes to complete provisioning and login.

## Editing or Disabling JIT Settings

### Edit JIT Settings

1. Go to **Manage > Account Settings > Organization Settings > Security and Authentication > User Provisioning > SAML Just-In-Time Settings**.
2. To change the role attribute, select or enter the new claim or attribute name.
3. If you change the claim name, update the custom claim name in Cisco Identity and the claim name configured in your IdP.
4. To change a role mapping, select a different role from the **Role** dropdown.

   Create the role under **Manage > Account Settings > Users and Roles > Roles** before it appears in the dropdown.
5. To change account-group access, select or clear account groups in the **Account Groups** dropdown.
6. Click **Save**.
7. Test the change with an SP-initiated login.

### Edit the Identity Provider Configuration

1. In Cisco Identity, go to **Settings > Manage IdPs**.
2. Click **...** next to the IdP.
3. Select **Edit IdP**.
4. Update the protocol settings, custom claims, JIT settings, linking attributes, or profile attributes.
5. Click **Save**.
6. Test the change with an SP-initiated login.

### Disable JIT

To stop using JIT provisioning, switch the **Enable** toggle off.

Your JIT settings remain saved but inactive. Disabling JIT does not delete existing users or role mappings. Review existing users separately if you want to remove access.

## Troubleshooting JIT Provisioning

| Protocol     | Symptom                                                                | Likely cause                                                                           | What to do                                                                                                                                                                                            |
| ------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SAML or OIDC | JIT is not active                                                      | SSO or JIT is disabled                                                                 | Confirm that SSO is enabled and that **User Provisioning > SAML Just-In-Time Settings > Enable** is on.                                                                                               |
| SAML or OIDC | An IdP application-catalog launch fails                                | IdP-initiated login is not supported for this workflow                                 | Start from the ThousandEyes login screen or an SP-initiated link.                                                                                                                                     |
| SAML or OIDC | The user is created without the expected access                        | No matching role mapping or the mapped role does not allow login                       | Map the exact role or group value to a ThousandEyes role with login access and the required account groups.                                                                                           |
| SAML         | No roles are found                                                     | The IdP did not send the configured SAML attribute or custom claim                     | Confirm that the SAML assertion contains the configured role attribute and that the attribute name and values match exactly.                                                                          |
| OIDC         | Custom claims contain `name` but not the group claim                   | The group claim is access-token-only or configured on a different authorization server | Configure the group claim in the ID token and configure it on the authorization server identified by the discovery document’s `issuer` value.                                                         |
| OIDC         | The token preview contains claims, but live login does not             | The preview uses a different authorization server from the one Cisco account uses      | Compare the live token’s `iss` value with the discovery document’s `issuer` value. Configure claims, scopes, and policies on that same server.                                                        |
| OIDC         | A custom authorization server fails when requesting the `groups` scope | The scope is not defined or is not allowed by the access policy                        | Add the `groups` scope to the authorization server and allow it in the access policy.                                                                                                                 |
| SAML or OIDC | The logs show group values, but no role mappings are found             | The claim name or capitalization does not match                                        | Use the same claim name and capitalization in the IdP, Cisco Identity, and ThousandEyes. For example, use `groups` consistently instead of `Groups`.                                                  |
| SAML or OIDC | A duplicate user is created or the email address is not updated        | The linking attribute is missing, unstable, or not mapped to `externalId`              | Map a stable, immutable IdP attribute or OIDC claim to `externalId`. Confirm that the profile-update option is enabled when profile updates are required.                                             |
| OIDC         | Authentication fails before claims are received                        | Incorrect issuer, redirect URI, client ID, client secret, or endpoint configuration    | Verify the OIDC discovery URL, issuer, redirect URI, client ID, client secret, and endpoint values.                                                                                                   |
| SAML or OIDC | An administrator loses tenant admin portal access                      | The administrator does not receive a mapped built-in **Organization Admin** role       | Have another administrator restore the built-in **Organization Admin** role under **Manage > Account Settings > Users and Roles**, add the matching IdP group or role, and sign in again through SSO. |

{% hint style="info" %}
If logs show **No role mappings found**, inspect the custom claims data first. The message often means that no role or group values were received, not that the ThousandEyes mappings are necessarily missing.
{% endhint %}

For additional help, see [Troubleshoot Login Errors](https://docs.thousandeyes.com/product-documentation/user-management/authentication/troubleshoot-login).

## Learn More

* [Configure SSO with Cisco Account](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account) — Configure SAML or OIDC authentication in Cisco Identity.
* [Test Your SSO Setup](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/test-your-sso-setup) — Test the SSO configuration before activating it.
* [Configure Routing Rules](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules) — Route users to the correct IdP and maintain a break-glass rule.
* [Verify Your Domain](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/verify-domains) — Verify domains before creating domain-based routing rules.
* [Role-Based Access, Explained](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/role-based-access-control-explained) — Learn how roles and permissions control access.