# Single Sign-On (SSO) integration {% hint style="info" %} **Note:** If you are using a self-hosted deployment of AI Architect, please refer to the [SSO authentication guide for self-hosted installations](https://docs.bito.ai/installation/install-ai-architect-self-hosted#sso-authentication) instead, as the setup process differs from the cloud version. {% endhint %} Single Sign-On (SSO) enables your team to authenticate with Bito's [AI Architect](https://docs.bito.ai/ai-architect/overview) MCP through your organization's identity provider instead of sharing access tokens with team members. ## Why use SSO SSO addresses a critical security challenge: when teams share access tokens, you lose visibility into who accessed what and when. If someone leaves the company or changes roles, you need to rotate tokens for everyone. SSO solves this by integrating authentication with your existing identity infrastructure. Your organization likely already uses an identity provider like Google Workspace, Okta, Azure Entra ID, Auth0, or others to manage access to email, Slack, and other business tools. SSO extends this same authentication system to AI Architect, giving you centralized control over access without creating a separate credential management burden. The practical benefits include automatic enforcement of your existing security policies (like multi-factor authentication requirements), immediate access revocation when someone leaves, and a complete audit trail of who accessed the system and when. This meets enterprise compliance requirements while making access simpler for your users. ## Supported identity providers AI Architect's SSO implementation uses Descope as the authentication platform, which provides native integrations with enterprise identity providers. Common identity providers include: * Google Workspace * Okta * Azure Entra ID * Microsoft AD FS * PingFederate * PingOne * onelogin * Keycloak * JumpCloud * Auth0 * ClassLink * Cyberark * Descope * Duo * LastPass * miniOrange * Salesforce {% hint style="info" %} If your organization uses a different provider, you can configure it as a custom SAML 2.0 or OpenID Connect (OIDC) integration. {% endhint %} The setup process varies by provider but follows the same general pattern: you'll configure an application in your identity provider, exchange metadata or configuration details, and test the connection. ## Prerequisites To enable SSO, you need: 1. **Workspace admin access**: You must be an admin in your Bito workspace. You can check your role in Bito by going to [Manage Users](https://alpha.bito.ai/home/members) dashboard. 2. **Identity provider account**: Access to configure your organization's IdP (Google Workspace, Okta, etc.). This is typically an IT admin or someone in your identity and access management team. You'll need to add AI Architect as an authorized application and provide configuration details. 3. **AI Architect**: Your workspace must have AI Architect enabled. [Learn more](https://docs.bito.ai/ai-architect/overview) ## How to configure SSO {% stepper %} {% step %} ### Access SSO settings in Bito 1. Log in to [Bito Cloud](https://alpha.bito.ai/auth/login). 2. Navigate to the [Manage integrations](https://alpha.bito.ai/home/cra-integrations) dashboard. 3. In the **Available integrations** section, you will see **Single Sign-On (SSO)**. Click **Connect** to proceed. 4. Click **Connect via SSO**. You will be redirected to Descope. {% endstep %} {% step %} ### Configure your identity provider The SSO configuration uses Descope as the authentication platform, which [supports multiple identity providers](#supported-identity-providers). 1. In the Welcome page, click **SSO Configuration**. 2. Choose your identity provider from the [list](#supported-identity-providers). If you do not find the identity provider, use the generic configuration options such as SAML 2.0 or OpenID Connect (OIDC) at the bottom of the screen. 3. Follow the provider-specific setup wizard to configure SSO. For the sake of this documentation, we'll provide setup guide for Keycloak. For other identity providers, simply follow the step-by-step instructions provided by Descope in the setup wizard. #### Guide for Keycloak: 1. From the **Identity Provider (IdP) Selection** screen, click **Keycloak**. 2. Click **SAML**. 3. From the **Service Provider Information** screen, copy **`Client ID`**. 4. Log in to the Keycloak administration console and follow these steps: 1. In the left menu, select **Clients**, and click on **Create client**. 2. Select **SAML** as the **Client type**, name the client, and paste the **`Client ID`** you copied above in the **Client ID** field. 3. Click **Next**. 4. From the **Service Provider Information** screen of the Descope setup wizard, copy **`SP ACS URL`**. 5. Now in Keycloak administration console, paste the **`SP ACS URL`** to the **`Valid redirect URIs`** and the **`Master SAML Processing URL`** fields. 6. Click **Save**. 7. Scroll down, enable the **`Sign assertions`** toggle and click **Save**. 8. In the top menu, select **Keys** and disable the **`Client signature required`** toggle. 9. In the top menu, select **Client scopes**, and click on the newly created client. 10. Select **Add predefined mapper**. 11. Select **`x500 email`**, **`x500 givenName`** and **`x500 surname`**, and click **Add**. 12. In the left menu, select **Realm settings**. 13. Copy the **`SAML 2.0 Identity Provider Metadata`** link address. 14. Now in Descope setup wizard, open **Identity Provider Information** screen. 15. Paste the **`SAML 2.0 Identity Provider Metadata`** link address you copied from Keycloak administration console in the **`SAML 2.0 Identity Provider Metadata`** field. 16. Click **Continue**. 17. In the **SSO Domains** screen, click **Continue**. 18. In the **Testing** screen, click **Save & Test**. 19. If the configuration is done correctly, you will see **SSO test completed successfully**. 20. Click **Done**, and you will be redirected back to Bito. 21. In Bito Cloud, [Manage integrations](https://alpha.bito.ai/home/cra-integrations) dashboard, you will see **Setup completed** for **Single Sign-On (SSO)** integration. {% endstep %} {% endstepper %} ## How users connect using SSO Once SSO is enabled for your workspace, you can easily connect to AI Architect MCP in your coding agents (Cursor, Windsurf, VS Code, etc.) using the following steps: 1. Connect Bito's AI Architect to your AI coding tools (Cursor, Windsurf, VS Code, etc.) in seconds with our automated installer. 1. [Follow quick MCP integration guide](https://docs.bito.ai/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-coding-agents) 2. Open your IDE's MCP settings. 3. In `BitoAIArchitect` MCP, remove the **Bito MCP Access Token** line. {% hint style="info" %} **Note:** Sometime your changes in MCP settings will not take effect immediately. To fix this, you can try renaming the `BitoAIArchitect` MCP to something else. For example, `BitoAIArchitect_test`. {% endhint %} 4. Enable the `BitoAIArchitect` MCP. 5. Click the **Connect** button next to Bito's AI Architect MCP. The secure authentication link of your organization's identity provider will open in browser. 6. Sign in using your credentials. 7. After successful authentication, return to your IDE. 8. Bito's AI Architect MCP is now connected and ready to use. ## How SSO authentication works In your IDE, when you click "Connect" for Bito's AI Architect MCP, the MCP client generates a secure authorization request. Your browser opens and redirects to your identity provider (like Google or Okta). You authenticate with your credentials. Your identity provider verifies your identity and confirms you're authorized to access the application. It sends a secure token back to Bito, which verifies it and creates a session for you. Your IDE receives confirmation and establishes the MCP connection. This entire process takes about 30 seconds the first time. The IDE stores your session securely, so you won't need to authenticate again unless your session expires (typically after 1 hour of inactivity) or you explicitly disconnect. ## Fallback authentication (when SSO isn't configured yet) If a workspace admin has enabled SSO but hasn't completed the configuration with an identity provider, you will see a different authentication flow. Instead of being redirected to your organization's identity provider login page, you'll be directed to Bito's standard authentication page at [https://alpha.bito.ai/](https://alpha.bito.ai/auth/login?_gl=1*1cgl6kw*_gcl_au*MTcyMDg0Nzg1NC4xNzY2OTg5MDc3). On this page, you need to enter your email address. Bito sends you a one-time code. You enter this code to verify your identity, then select which workspace you want to access. If you're a member of the workspace and have AI Architect enabled, you'll be authenticated successfully. This fallback ensures your team can still work even if SSO configuration is in progress or experiencing issues. However, you lose the centralized access control benefits that SSO provides, so you should complete the full SSO configuration when possible. ## Managing team access Once SSO is configured, you can control team member access to AI Architect by managing workspace membership and seat assignments. #### 1. User already exists in the workspace with an assigned seat If a user already exists in your Bito workspace and has a seat assigned, they can authenticate with AI Architect MCP through SSO immediately. No additional steps required, they simply connect using the SSO flow. [Learn more about seat management](https://docs.bito.ai/help/billing-and-plans/overview#seat-management) #### 2. Manually add new team members To manually add a new team member: * [Log in to Bito Cloud](https://alpha.bito.ai/auth/login) and navigate to [Manage Users](https://alpha.bito.ai/home/members) * Go to the **IDE Code Review** tab and click **Add members** * Enter their email address and click **Add members** * Assign them a seat The team member can now authenticate with AI Architect MCP through SSO. #### 3. Automatically add users to the workspace after successful SSO login When the **`autoAddUser`** flag is enabled in XMCP configuration, team members are automatically added to your workspace (if they don't already exist) after their first successful SSO login. For this to work, your workspace settings must allow adding users with the same email domain. {% hint style="info" %} To enable the **`autoAddUser`** flag, contact the Bito team at . {% endhint %}
#### Removing access You have two options for removing someone's access, and they work differently. 1. If you remove someone from your workspace in Bito, their access is revoked immediately for new authentication attempts. However, if they have an active session (they're already authenticated in their IDE), that session will continue to work until it expires. Sessions expire after 1 hour of inactivity by default. 2. If you need to revoke access immediately, including active sessions, you should remove or disable their account in your identity provider (Google Workspace, Okta, etc.). This prevents them from authenticating at all, and their existing sessions will fail the next time they try to use AI Architect. For employees leaving the company, the standard practice is to disable their account in your identity provider as part of your offboarding process. This automatically revokes their access to AI Architect along with your other business applications. If you want to preserve their workspace membership for record-keeping but remove their AI Architect access, you can unassign their seat instead.