# Configure SSO 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 %} This guide shows you how to set up Single Sign-On (SSO) in ThousandEyes using Cisco account as your identity provider (IdP). With SSO, your users can access ThousandEyes using the same credentials they use elsewhere in your organization. SSO improves security and simplifies user access by letting your identity provider manage authentication. ThousandEyes supports multiple IdPs in a single organization, so you can configure routing rules to control how users are authenticated based on their email domain or other attributes. {% hint style="warning" %} **Critical SSO Warning** **Do not upload your existing ThousandEyes SSO metadata file into the Cisco Identity portal.** The ThousandEyes-generated SSO metadata file is **not** compatible with the Cisco Identity portal.\ Uploading it will break authentication and can lock all users out of your organization, including administrators. {% endhint %} ## How it Works Single Sign-On (SSO) lets users log in to ThousandEyes using credentials managed by an identity provider (IdP). When a user logs in, ThousandEyes evaluates routing rules in order and applies the first rule that matches that user. There is no fallback authentication to another IdP or to local authentication if authentication fails or if a matched IdP is unavailable. To reduce the risk of administrative lockout during SSO setup or IdP misconfiguration, create a [break glass routing rule (dedicated local authentication only)](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules#add-a-break-glass-routing-rule-dedicated-local-authentication-only). Configure it so designated administrators match this rule first and therefore log in with local Cisco credentials only, without being sent to an external IdP. This is not a backup path for users who are matched first by a different rule. In this process: * **Create and test the break glass rule first**: Add yourself to the associated group and verify local Cisco account login before applying routing rules broadly. * **Verified identity claims are required**: ThousandEyes requires your identity provider (IdP) to send a stable, unique, and verified identifier for each user. This is typically: * A verified email address claim, or * Another stable unique identifier (for example, an immutable user ID) that can be consistently mapped to a ThousandEyes user. This identifier is used to: match users during authentication, prevent duplicate accounts, ensure secure user provisioning, and to maintain consistent access control. ThousandEyes validates ID tokens and SAML assertions in accordance with the [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) and [SAML 2.0 Core](https://docs.oasis-open.org/security/saml/v2.0/sstc-saml-approved-errata-2.0.html) specifications, which define subject identifiers used to uniquely identify authenticated users.

Some IdPs do not include a verified email claim by default, particularly when using OpenID Connect (OIDC). If a verified and stable identifier is not provided, authentication or user matching might fail.

If your IdP cannot provide a verified email claim via OIDC, configure SAML 2.0 and ensure the `NameID` or mapped attribute contains a verified and stable identifier. ### Supported Authentication Protocols ThousandEyes supports the following authentication protocols for SSO. * **SAML**\ [Configure SAML](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account#configure-saml) to securely exchange authentication metadata between your IdP and ThousandEyes. SAML 2.0 is required for all SAML-based integrations. * **OpenID Connect (OIDC)**\ [Configure OpenID Connect](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account#configure-openid-connect) to authenticate users using the OAuth 2.0 framework. You can optionally map a unique identifier to each ThousandEyes account. ### Authentication Redirects For IdP-initiated logins to work, your IdP must be configured with the correct `RelayState` parameter. After a successful authentication, your IdP uses this parameter to control where users are directed. It must be configured in your IdP, not in ThousandEyes, and your IdP must return the value exactly as sent by ThousandEyes. If the `RelayState` parameter is modified, omitted, or not returned correctly, your login attempt might fail or result in a redirect loop. Set your IdP's default `RelayState` to `https://app.thousandeyes.com/login/cui/idp`. To direct users to a specific page after login, append the `fwd` parameter. For example, to land on the **Alerts** list page: `https://app.thousandeyes.com/login/cui/idp?fwd=/alerts/list` ### Related Procedures To continue your SSO setup, you can also see these related procedures: * [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 based on domain or group. It is recommended you add a [break glass routing rule (dedicated local authentication only)](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules#add-a-break-glass-routing-rule-dedicated-local-authentication-only) for added protection. * [Verify Your Domain](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/verify-domains) — Verify your domains and subdomains to confirm ownership within ThousandEyes. * [Test Your SSO Setup](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/test-your-sso-setup) — Verify that your SSO integration is working correctly before going live. * [Manage Service Provider (SP) Certificates](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/manage-your-service-provider-certificates) — Add or download SP certificates used in SAML integrations. ## Prerequisites * You must have ThousandEyes Organization Admin permissions. 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). * Before enabling or modifying SSO routing rules, configure and test a break glass routing rule so at least one administrator is matched first by a rule that uses local Cisco account credentials (not an external IdP). For details, see [Add a Break Glass Routing Rule (Dedicated Local Authentication Only)](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules#add-a-break-glass-routing-rule-dedicated-local-authentication-only). * You must have a metadata file from the IdP to provide to ThousandEyes and a metadata file from ThousandEyes to provide to the IdP. For more information, see the [Identity Provider Setup](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account#identity-provider-setup) section below. This is only applicable to the SAML configuration. * Plan your routing rules behavior before setting up multiple IdPs. ## Identity Provider Setup Log in to your chosen IdP and follow the prompts to configure a new service provider (SP). Below are links to SP configuration documentation for popular SAML 2.0-based IdPs: * [Duo](https://duo.com/docs/sso) * [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/saas-apps/thousandeyes-tutorial) * [PingOne](https://docs.pingidentity.com/pingone/p1_cloud__platform_main_landing_page.html) * [Auth0](https://auth0.com/docs/authenticate/single-sign-on) * [Okta](https://help.okta.com/oie/en-us/content/topics/apps/apps_overview_of_managing_apps_and_sso.htm) * [Google Workspace](https://support.google.com/cloudidentity/answer/6087519?hl=en\&ref_topic=7558947) * [OneLogin](https://developers.onelogin.com/saml) * [miniOrange](https://www.miniorange.com/iam/content-library/admin-docs/how-to-add-saml-app) Each IdP has a different process for setting up SSO on their system. However, the following steps are common among the above IdPs: 1. Find and select the ThousandEyes application in the IdP’s application or service provider (SP) directory. Some IdPs might require you to manually add the ThousandEyes application. 2. For static configuration: * Enter the necessary parameter settings in the required fields (refer to the IdP Configuration Details section). * Take note of any SSO URLs or Entity IDs generated during this step — they will be needed in the SP configuration. 3. Download a certificate or metadata: * For static configuration: download a verification certificate. * For imported metadata configuration: download the metadata file to upload to ThousandEyes. 4. Configure SSO for your users: This step might occur at different points in the IdP setup process—even after the ThousandEyes configuration is complete. ## Configure SAML SAML 2.0 is required for all SAML-based integrations with ThousandEyes. SAML provides a structured framework that allows IdPs and service providers to communicate with each other, making federated identity and single sign-on possible and efficient. You have a choice when setting up a SAML IdP. You can manually enter your IdP's metadata or directly upload the metadata to the admin 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**. 4. Click **+ Add an IDP**. 5. Select **SAML** as your IdP and click **Next**. ![](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-6696e4649ac0f342529c048dcdd269495a27f8f0%2Fcisco-identity-sso-idp-saml.png?alt=media) 6. Select one of the following methods to connect your identity provider (IdP). * **Fill out configuration form** — Manually enter your IdP's metadata. * **Upload your IdP's metadata** — Upload an XML file containing your IdP's metadata. ![](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-6afd9f548c00c7ec5db3873ec83bc289b63c4f1b%2Fconfigure-saml-idp.png?alt=media) 7. If you select **Fill out the configuration form**, do the following: 1. Enter your **Entity ID (SAML Identifier)**. 2. Enter your **Single sign-on URL**. 3. Select a binding method: **HTTP-Post** or **HTTP-Redirect**. 4. (Optional) Enter your **Single sign-out URL**. 5. (Optional) Select a binding method: **HTTP-Post** or **HTTP-Redirect**. 6. Click the checkbox to enable **Sign SAML request**. Select this checkbox if your IdP requires authentication requests from ThousandEyes to be signed. 7. Select a **NameID format**. You can select from the following options: * `urn:oasis:names:tc:SAML1.1:nameid-format:emailAddress` (default): This format uses your email address as your NameID. * `urn:oasis:names:tc:SAML2.0:nameid-format:transient`: This format generates a temporary, one-time NameID for each authentication. * `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`: This format indicates that no specific NameID format is requested, leaving it to your IdP to determine or default to an appropriate format. 8. Upload your **IdP certificate files**. Upload up to two IdP certificate files (in `.pem` or `.cer` format), if your IdP uses multiple signing certificates. 9. Click **Next**. 8. If you select **Upload your IdP’s metadata**, do the following: 1. Upload an XML file containing your IdP’s metadata. When uploading the metadata file, there are two ways to validate the metadata from the Customer IdP: * Not signed, self-signed, or private CA-signed IdP metadata file: Your IdP provides a self-signed private CA or doesn’t provide a signature for their metadata. This option is less secure. * Signed by a public certificate authority: Your IdP provides a signature in the metadata that is signed by a Public Root CA. 2. Click **Next**. {% hint style="warning" %} **Metadata Compatibility Warning** **Do not upload a ThousandEyes-generated SSO metadata file here.** Only upload metadata generated by your IdP. The ThousandEyes metadata file cannot be reused. Uploading the wrong metadata file will cause SSO failure and might lock all administrators out of the account. {% endhint %} 9. (Optional) Configure SAML attributes and settings. The SAML identity provider (IdP), by default, uses the uid attribute to identify the user when sending authentication data to ThousandEyes. If the IdP supports other NameID configurations, you can modify this configuration. 10. Click **Add IdP**. If this is the first IdP you have configured, the IdP is saved as your default IdP, and a default routing rule is created. Consider adding a [break glass routing rule (dedicated local authentication only)](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules#add-a-break-glass-routing-rule-dedicated-local-authentication-only) and ordering it so designated administrators match it first. ## Configure OpenID Connect Use OpenID Connect (OIDC) to set up Single Sign-On (SSO) in ThousandEyes using your identity provider. OIDC is built on the OAuth 2.0 framework and supports secure authentication through encrypted tokens and built-in certificate validation. {% hint style="info" %} When you set up OpenID Connect with Entra ID or an IdP where the email isn’t a permanent identifier, we recommend that you use the `externalId` linking attribute to map to a unique identifier. For Entra ID, we suggest mapping OIDC to `externalId`. If the email you enter doesn’t match the linking attribute, you’re prompted to verify your identity or create a new user with the correct email address. {% endhint %} 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**. 4. Click **+ Add an IDP**. ![](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-7104ecf29f87eb6edf00eed5bb388b480af5ad0e%2Fcisco-identity-sso-idp.png?alt=media) 5. Select **OpenID Connect** as your IdP and click **Next**. 6. Enter your IdP information. 1. Enter your **IdP Name**. 2. Enter your **Client ID**. The unique ID to identify you and your IdP. 3. Enter your **Client Secret**. This is the password that you and your IdP know. 4. Select the scopes you want to associate with your IdP. **OpenID** and **Email** are selected by default. 7. Choose how to add endpoints. You can select from the following: * **Use the discovery URL**. Enter the discovery URL for your IdP. This URL will automatically populate the necessary endpoints for OIDC single logout (SLO). * **Manually add all endpoint information**. Select this option if your IdP doesn’t support discovery URLs. You’ll be prompted to enter each endpoint manually. Fill in the following fields: * **Issuers (comma-separated)** – Enter one or more issuer URIs, separated by commas. * **Authorization endpoint** – URL used to initiate the authorization flow. * **Token endpoint** – URL to retrieve access tokens. * **JWKS URI** – (Optional) URL to retrieve the JSON Web Key Set. * **Userinfo endpoint** – (Optional) URL to retrieve user profile information. * **End session endpoint** – (Optional) URL to support single sign-out. ![](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-a783b3a3fda480c34ac315d3396f8f7061db08ed%2Fmanually-add-endpoint-info.png?alt=media) 8. (Optional) Check **Allow the session to automatically sign out** if you want to enable automatic sign-out. 9. Click **Add IdP**. If this is the first IdP you have configured, the IdP is saved as your default IdP and a default routing rule is created. Consider adding a [break glass routing rule (dedicated local authentication only)](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules#add-a-break-glass-routing-rule-dedicated-local-authentication-only) and ordering it so designated administrators match it first. ## Edit an IdP Configuration 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**. 4. Next to the IdP you want to edit, click the `...` icon. 5. Click **Edit IdP**. 6. Update the IdP configuration, and then click **Save**. ## Delete an Identity Provider {% hint style="warning" %} Before deleting an IdP, you must deactivate or delete its routing rules. Deleting an IdP that has active routing rules can deactivate SSO for your organization. For more details, see [Deactivate or Delete Routing Rules](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules#deactivate-or-delete-routing-rules). {% endhint %} 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**. 4. Next to the IdP you want to delete, click the `...` icon. 5. Click **Delete**. 6. To confirm, click **Delete IdP**. ## Next Steps * [Configure Routing Rules](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/configure-routing-rules) — It’s strongly recommended that you create a break glass routing rule so at least one user or group is matched first to local Cisco authentication (not an external IdP), reducing lockout risk during SSO setup. Rules use first-match order and do not fall back to another rule. * [Verify Your Domain](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/verify-domains) — Verify your domains and subdomains to confirm ownership within ThousandEyes. * [Test Your SSO Setup](https://docs.thousandeyes.com/product-documentation/user-management/authentication/configure-sso-with-cisco-account/test-your-sso-setup) — Verify that your SSO integration is working correctly before going live.