> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO

> Use SSO to login to the Gitar App

## Overview

Single Sign-On (SSO) allows your organization to use your existing identity provider to authenticate with Gitar. Instead of managing separate credentials, your team members can sign in using the same identity provider they already use for other services.

<Note>
  SSO is available on the Enterprise plan. Contact [developers@gitar.ai](mailto:developers@gitar.ai) to enable SSO for your organization.
</Note>

## Supported Providers

Gitar supports the following identity providers:

* **Okta** -- Full setup guide documented below.
* **Any SAML 2.0 compatible provider** -- Azure AD, Google Workspace, OneLogin, and other providers that support the SAML 2.0 protocol.

## Okta Setup

<Steps>
  <Step title="Request SSO Configuration">
    Contact your Gitar account manager or email [developers@gitar.ai](mailto:developers@gitar.ai) to request SSO configuration. You will receive an email with your **SSO URL** and **Audience URI**, which are required to set up the Okta integration.
  </Step>

  <Step title="Create Okta Application">
    In your Okta admin console, create a new **SAML 2.0** App Integration. Name the application "Gitar" and optionally use the Gitar logo at `/assets/images/gitar-brand-logo-dark.png`.

    Follow [Clerk's Okta SAML directions](https://clerk.com/docs/authentication/enterprise-connections/saml/okta) for the full walkthrough.

    <img src="https://mintcdn.com/gitar/IlYvr_ecMR0aE0ph/assets/images/okta-saml-1.png?fit=max&auto=format&n=IlYvr_ecMR0aE0ph&q=85&s=10310f66653734d90c422959741023d2" alt="Okta SAML setup" width="2140" height="1160" data-path="assets/images/okta-saml-1.png" />
  </Step>

  <Step title="Configure SAML Settings">
    Enter the **SSO URL** and **Audience URI** from the email you received from Gitar into the SAML settings of your Okta application.

    <img src="https://mintcdn.com/gitar/IlYvr_ecMR0aE0ph/assets/images/okta-saml-2.png?fit=max&auto=format&n=IlYvr_ecMR0aE0ph&q=85&s=7321f2e3df4b639d18fd4ab869190952" alt="SAML settings" width="2208" height="1428" data-path="assets/images/okta-saml-2.png" />
  </Step>

  <Step title="Set Attribute Mappings">
    Map the following attributes in your Okta SAML configuration:

    | Attribute   | Value            |
    | ----------- | ---------------- |
    | `mail`      | `user.email`     |
    | `firstName` | `user.firstName` |
    | `lastName`  | `user.lastName`  |

    <img src="https://mintcdn.com/gitar/IlYvr_ecMR0aE0ph/assets/images/okta-saml-3.png?fit=max&auto=format&n=IlYvr_ecMR0aE0ph&q=85&s=5c780da82e07581dc655c0d6e14c32df" alt="Attribute mappings" width="1540" height="832" data-path="assets/images/okta-saml-3.png" />
  </Step>

  <Step title="Complete Configuration">
    Assign the appropriate users and groups to the Gitar application in Okta. Once assignments are complete, copy the **Metadata URL** from Okta and send it to your Gitar account manager to finalize the setup.
  </Step>
</Steps>

## Generic SAML 2.0 Provider

For identity providers other than Okta, the setup follows the same general pattern:

1. Contact [developers@gitar.ai](mailto:developers@gitar.ai) to request your **SSO URL** and **Audience URI**.
2. Create a new **SAML 2.0** application in your identity provider and configure it with the SSO URL and Audience URI provided by Gitar.
3. Map the `email`, `firstName`, and `lastName` attributes to the corresponding user fields in your identity provider.
4. Send the **Metadata URL** from your identity provider to your Gitar account manager to complete the setup.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Users can't sign in with SSO">
    Verify that the affected users are assigned to the Gitar application in your identity provider. Check that the attribute mappings for `mail`, `firstName`, and `lastName` are configured correctly and match the expected values.
  </Accordion>

  <Accordion title="SSO login redirects to the wrong page">
    Ensure the SSO URL configured in your identity provider matches exactly what was provided by Gitar. Even small differences such as a trailing slash or protocol mismatch can cause redirect issues.
  </Accordion>

  <Accordion title="How do I update my SSO configuration?">
    Contact [developers@gitar.ai](mailto:developers@gitar.ai) to update your SSO settings or rotate credentials. Changes to your identity provider configuration may also require updating the Metadata URL on the Gitar side.
  </Accordion>
</AccordionGroup>