> 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-saml-jit-with-cisco-account.md). # Configuring SAML JIT with Cisco Account {% hint style="info" %} Any information provided in this document regarding future functionalities is for informational purposes only and is subject to change including ceasing any further development of such functionality. Many of these future functionalities remain in varying stages of development and will be offered on a when-and-if available basis, and Cisco makes no commitment as to the final delivery of any of such future functionalities. Cisco will have no liability for Cisco's failure to deliver any or all future functionalities and any such failure would not in any way imply the right to return any previously purchased Cisco products. {% endhint %} [Security Assertion Markup Language (SAML)](https://www.cisco.com/site/us/en/learn/topics/security/what-is-saml.html) just-in-time (JIT) provisioning uses SAML authentication to verify a user's identity when they log in. If the user does not already exist in ThousandEyes, the system automatically creates the user account during the login process. This process is called just-in-time provisioning because users do not need advance provisioning. Each time a user logs in, SAML JIT provisioning creates or updates the user's profile using the attributes provided by the identity provider (IdP). If your organization previously provisioned users with SCIM or another method, SAML JIT provisioning overwrites the existing profile information with the latest values from the IdP. This behavior helps keep user records up to date. {% hint style="info" %} SAML JIT provisioning with Cisco Identity supports service provider (SP)-initiated login only. IdP-initiated login is not supported, including launches from your IdP application catalog. Users can log in from the ThousandEyes login screen or an SP-initiated link such as `https://app.thousandeyes.com/v2/login?fwd=/account/switch/`, where `` is your account group ID. {% endhint %} ## Use Cases Organizations of any size can use SAML JIT provisioning. It is especially useful for organizations with large numbers of users, multiple roles or account groups, and a need to assign different permissions based on those roles and groups. This approach is well suited for organizations with frequently changing workforces, such as those that employ seasonal workers or operate large customer support centers. ## Prerequisites * An account or subscription with your chosen IdP. * You must enable SSO. For more information on SSO configuration, see [Configure SSO with Cisco Account](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account). * Your IdP must send role information alongside identity attributes. The attribute name must match the **SAML Role Name Attribute** you configure under **User Provisioning > SAML Just-In-Time Settings** in ThousandEyes. * Do not use SAML JIT provisioning and SCIM provisioning together. SAML JIT overwrites user records on every login. * Keep SSO enabled while you use SAML JIT provisioning. You cannot fully disable SSO while JIT is in use. * 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 on permissions, see [Role-Based Access, Explained](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/role-based-access-control-explained). ## About This Task When you log in through SSO with SAML JIT enabled, the JIT update flow replaces your ThousandEyes roles with the values from your IdP assertion. In organizations with Cisco Identity enabled, the built-in **Organization Admin** role controls access to the tenant admin portal under **Manage > Account Settings > Organization Settings** (**Single Sign-On (SSO) > Go to admin portal**). Legacy SAML JIT provisioning did not have this requirement because no tenant admin portal existed. If your IdP does not send a group or role named **Organization Admin** that matches the ThousandEyes role name exactly, you keep your other ThousandEyes admin permissions but lose access to the tenant admin portal after that login. ### Role Name Matching SAML JIT provisioning maps IdP role or group values to ThousandEyes roles. IdP and ThousandEyes role names must match exactly, including case, spacing, and special characters. For example, a role named *IT* in your IdP does not map to **Organization Admin** in ThousandEyes. If the IdP sends a role that has no matching ThousandEyes mapping, user creation or login can fail. Cisco Identity might create the user, but ThousandEyes provisioning fails when role mappings do not match. Every organization should maintain at least one **Organization Admin** mapping. This built-in role includes the [management permissions](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/role-based-access-control-explained#management-permissions) needed to manage users and SAML JIT settings. Do not remove the **Organization Admin** mapping if any admin needs access to the Cisco Identity tenant admin portal. A custom role with the same management permissions does not provide tenant admin portal access. * **Before you test SSO**: Create a matching **Organization Admin** group or role in your IdP, and assign it to every ThousandEyes admin who needs access to the Cisco Identity tenant admin portal. * **If you lose tenant admin portal access**: Reassign the built-in **Organization Admin** role in **Manage > Account Settings > Users and Roles**. Another admin can do this for you, or you can reassign the role to yourself if you still have user-management permissions. After the role is reassigned, access propagates to Cisco Identity shortly. * **Permanent fix**: Create an **Organization Admin** group or role in your IdP, save your ThousandEyes role mappings, and log in again through SSO. On the next login, JIT provisioning assigns the **Organization Admin** role back to your account. ### Display Name Attributes When SAML JIT provisioning creates or updates a user, ThousandEyes determines the display name from IdP attributes as follows: * If only `displayName` is provided, ThousandEyes uses it. Leading and trailing spaces are trimmed. * If both `displayName` and `http://schemas.microsoft.com/identity/claims/displayname` are provided, the first attribute listed is used. * If `displayName`, `firstName`, and `lastName` are all provided, `displayName` takes precedence. * If `displayName` is not provided, ThousandEyes combines `firstName` and `lastName`. If only one is present, that value is used. If neither is provided, the default name **JIT Created User** is assigned. To avoid the default name **JIT Created User**, configure your IdP and map **Profile Attributes** in the Cisco Identity portal to send at least one of the following: `displayName`, `firstName`, or `lastName`. ## Steps ### Step 1: Configuring SAML JIT in 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**.

If you're setting up a new SAML IdP, skip Edit IdP. Follow Configure SAML IdP with Cisco Account to add your IdP, then return to this guide and configure the SAML mapping attribute.

4. For the SAML IdP you want to edit, click **...**. 5. Select **Edit IdP**. 6. If needed, edit the SAML configuration and click **Next**. 7. Configure the **SAML mapping attribute**. Cisco Identity uses the SAML mapping attribute to match the authenticated user to the provisioned user record. Use the SAML attribute name your IdP sends. The following example maps `uid` to the user's email, UPN, or `eduPersonPrincipalName`. | **SAML attribute name** | **Cisco Identity attribute name** | **Attribute description** | | ----------------------- | --------------------------------- | ----------------------------------------------------------------------------------------- | | uid | Username/Primary email address | Maps the UID attribute to the provisioned user's email, UPN, or `eduPersonPrincipalName`. | 8. Click the **Configure custom claims, JIT settings, and linking attributes** dropdown. 9. Add **Custom Claims**. Custom claims pass additional IdP attributes, such as role or group values, to Cisco Identity. ThousandEyes uses these claims with SAML JIT role mappings to assign access when users are created or updated. Include the attribute your IdP uses for roles (for example, `Group`). The name must match the **SAML Role Name Attribute** you configure under **User Provisioning > SAML Just-In-Time Settings** in ThousandEyes. 1. Click **+ Add custom claim**. 2. Enter your custom claim. You can add a maximum of 25 custom claims. 10. Select **Just-In-Time (JIT) settings**. Select the following options as needed: * **Create or activate users** (required): Select this option. If Cisco Identity does not find an active user, it creates the user and updates the attributes after the user logs in to the IdP. * **Update user with SAML attributes** (optional): If Cisco Identity finds a user with the specified email address, it updates the user with the attributes mapped in the SAML assertion.

If you enable Update user with SAML attributes, see Role Name Matching for how role updates affect access to the tenant admin portal.

11. Configure the **Linking Attribute**. The linking attribute uniquely identifies a user so Cisco Identity can update the user's profile. If you enabled **Update user with SAML attributes** and use a linking attribute other than `email` or `uid`, users can update their email address through JIT provisioning. 1. Click the **Select an attribute** dropdown and select `externalId` as the **Cisco Identity attribute name**. 2. For the **SAML attribute name**, enter an attribute name. For example: | **SAML Attribute Name** | **Cisco Identity Attribute Name** | **Attribute Description** | | ----------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Example: user.objectid | externalId | A unique attribute for identifying a user and updating their profile and information, including their email address. | 12. Configure **Profile Attributes**. Profile attributes map user profile details from your IdP to Cisco Identity attributes. Cisco Identity can use these mappings to create or update the user's profile during JIT provisioning. See [Display Name Attributes](#display-name-attributes) for how ThousandEyes resolves display names from IdP attributes. | **SAML Attribute Name** | **Cisco Identity Attribute Name** | **Attribute Description** | | ------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Example: user.preferredlanguage | preferredLanguage | The user's preferred language. | | Example: user.locale | locale | The user's locale. | | Example: user.timezone | timezone | The user's primary time zone. | | Example: user.displayname | displayName | The user's display name. | | Example: user.givenname | name.givenName | The user's first name. | | Example: user.surname | name.familyName | The user's last name. | | Example: user.streetaddress | addresses.streetAddress | The street address of their primary work location. | | Example: user.locality | addresses.locality | The city or locality of the user's primary work location. | | Example: user.region | addresses.region | The state or region of the user's primary work location. | | Example: user.country | addresses.country | The country of their primary work location. | | Example: user.postalcode | addresses.postalCode | The postal code of the user's primary work location. | | Example: work phonenumber | phoneNumbers.work | The work phone number of their primary work location. Use the international E.164 format only (15 digits maximum). | | Example: mobile phonenumber | phoneNumbers.mobile | The user's mobile phone number. Use the international E.164 format only (15 digits maximum). | | Example: extension phonenumber | phoneNumbers.extension | The work extension of their primary work location. Use the international E.164 format only (15 digits maximum). | | Example: user.jobtitle | title | The user's job title. | | Example: user.department | department | The user's job department or team. | | Example: work emails | emails.work | The user's work email. | | Example: user.organization | organization | The user's organization ID. | 13. Configure **Group attributes**. Group attributes map group identifiers from your IdP to Cisco Identity group attributes. Cisco Identity can use these mappings to associate the user with a group for licensing or service settings. | **SAML Attribute Name** | **Cisco Identity Attribute Name** | **Attribute Description** | | ----------------------------- | --------------------------------- | ------------------------------------------------------------------------------- | | Example: user.groupid | groupId | Maps the IdP group identifier to the Cisco Identity group ID. | | Example: user.groupexternalid | groupExternalId | Maps the IdP external group identifier to the Cisco Identity external group ID. | Configure the row that matches the group identifier your IdP sends. If your IdP sends both values, configure both rows. 14. Click **Save**. ### Step 2: Configuring Role Mappings in ThousandEyes 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** you want to map. * If the role name attribute is not listed in the dropdown, select **Custom…** to enter a new role name attribute. This value must match the custom claim you add for roles in the Cisco Identity portal. 5. In the **Role** dropdown, select a role to add. 6. In the **Account Groups** dropdown, select all the account groups you want this role to access. 7. Click **+ Add mapping** or **-** to add or remove role and account group mappings as needed. Include a mapping for **Organization Admin** before you test the SSO login. 8. Click **Save**. ## Testing SAML JIT Login After you complete the Cisco Identity portal and ThousandEyes configuration, test with an SP-initiated login: 1. In your browser, open `https://app.thousandeyes.com/v2/login?fwd=/account/switch/`, where `` is your account group ID. 2. Log in to your IdP when prompted. 3. Confirm that ThousandEyes creates or updates the user and assigns the expected roles. 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 your IdP and then back to ThousandEyes to complete provisioning and the login process. ## Editing or Disabling SAML JIT Settings ### Editing Settings 1. Go to **Manage > Account Settings > Organization Settings > Security and Authentication > User Provisioning > SAML Just-In-Time Settings**. 2. To change attributes, select or type a new attribute name. 3. To change roles, select a new role from the dropdown. You must first create the role under **Manage > Account Settings > Users and Roles > Roles** before it appears in the dropdown. 4. To change account group access, select or clear account groups in the **Account Groups** dropdown. 5. Click **Save**. ### Disabling SAML JIT To stop using SAML JIT provisioning, switch the **Enable** toggle off. Your settings remain saved but are inactive. ## Troubleshooting Common SAML JIT issues are caused by configuration errors in ThousandEyes or the Cisco Identity portal: * **SSO or SAML JIT not enabled**: Confirm that SSO is enabled and that the **Enable** toggle is on under **User Provisioning > SAML Just-In-Time Settings**. * **No SAML Role Name Attribute configured**: Set the **SAML Role Name Attribute** under **User Provisioning > SAML Just-In-Time Settings** in ThousandEyes. It must match the role custom claim in the Cisco Identity portal. * **Role names do not match**: The role values your IdP sends must exactly match ThousandEyes role names and the role and account group mappings under **SAML Just-In-Time Settings** in ThousandEyes. * **No roles in IdP assertion**: Confirm that your IdP sends role or group values in the attribute you configured as a custom claim. For additional help, see [Test Your SSO Setup](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/test-your-sso-setup) and [Troubleshoot Login Errors](https://docs.thousandeyes.com/product-documentation/user-management/authentication/troubleshoot-login). ## Learn More * [Identity Provider Setup](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account#identity-provider-setup): Configure IdP-side metadata, certificates, and user assignments before you add SAML in the Cisco Identity portal. * [Configure Routing Rules](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules): Define how authentication requests are routed by domain or group after you add an IdP. * [Edit an IdP Configuration](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account#edit-an-idp-configuration): Edit or delete IdP records in the Cisco Identity portal after initial setup.