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

# Single sign-on

> Sign in to CostGraph through Okta, Microsoft Entra ID, Google Workspace, or any SAML or OpenID Connect provider

Single sign-on (SSO) lets your team sign in to CostGraph with your company
identity provider. You verify the email domains you own, connect one identity
provider, and choose whether people from those domains join automatically and
whether SSO is required.

Organization owners set up SSO under **Settings > Single sign-on**. The page
has three sections: **Domains**, **Identity provider**, and **Require single
sign-on**.

## Verify a domain

You prove you own a domain by adding a DNS record. Only people with an email
address at a verified domain can sign in through your identity provider.

<Steps>
  <Step title="Add the domain">
    Under **Domains**, enter the domain, such as `example.com`, and click **Add
    domain**.
  </Step>

  <Step title="Create the TXT record">
    CostGraph shows a TXT record **Name** and **Value**. Copy the value now,
    because it's shown only once. At your DNS provider, create a TXT record
    with that name and value.
  </Step>

  <Step title="Verify">
    Click **Verify now**. DNS changes can take a while to spread; if it
    doesn't verify straight away, try again later.
  </Step>
</Steps>

A domain shows one of these statuses:

| Status | Meaning |
| - | - |
| **Pending** | Waiting for the TXT record. Unverified domains expire after 7 days |
| **Verified** | The record was found. SSO and auto-join work for this domain |
| **Suspended** | The record has been missing on three daily checks in a row. Existing members keep access, but nobody new can join or sign in through SSO until you restore it |
| **Expired** | The domain wasn't verified within 7 days. Remove it and add it again |

Keep the TXT record in place after verification. CostGraph checks it daily.

## Connect your identity provider

Choose **SAML** for Okta, Microsoft Entra ID, or Google Workspace, or
**OpenID Connect** for another OIDC provider. You can't switch protocol later
without removing the identity provider.

For SAML, add CostGraph as an app in your identity provider first, then give
CostGraph its metadata, as a **Metadata URL** or by uploading the metadata
file. CostGraph needs your provider to send the user's email address in the
attribute named:

```text theme={null}
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```

After you save, CostGraph lists the values your identity provider needs under
**Enter these values in your identity provider**. SAML uses the **Entity ID
(audience)** and **ACS URL (reply URL)**. OpenID Connect uses the **Redirect
URI**. Copy them from the page; they're specific to CostGraph's sign-in
service, not to your organization.

Sign-in must start from CostGraph. Opening the app from your identity
provider's dashboard isn't supported.

<Tabs>
  <Tab title="Okta">
    1. In the Okta admin console, go to **Applications > Applications** and click
       **Create App Integration**. Select **SAML 2.0**.
    2. Name the app `CostGraph`. For **Single sign-on URL**, enter the **ACS URL**
       from CostGraph. For **Audience URI (SP Entity ID)**, enter the **Entity ID**.
    3. Under **Attribute Statements**, add an attribute named
       `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` with
       the value `user.email`.
    4. To map groups to roles, under **Group Attribute Statements**, add an
       attribute named `groups` with a filter that matches the groups to send.
    5. Finish the app, assign people or groups to it, and copy the **Metadata URL**
       from the **Sign On** tab into CostGraph.
  </Tab>

  <Tab title="Microsoft Entra ID">
    1. In the Microsoft Entra admin center, go to **Enterprise applications** and
       click **New application > Create your own application**. Name it
       `CostGraph` and choose the non-gallery option.
    2. Open **Single sign-on** and select **SAML**. Under **Basic SAML
       Configuration**, set **Identifier (Entity ID)** to the **Entity ID** and
       **Reply URL** to the **ACS URL** from CostGraph.
    3. Entra ID sends the email address attribute by default. Check that
       **Attributes & Claims** maps it to the user's email.
    4. To map groups to roles, click **Add a group claim**. In CostGraph, set
       **Groups attribute** to the group claim's name, and use the group values
       Entra sends, which are group object IDs unless you choose otherwise.
    5. Assign users or groups to the app, and copy the **App Federation Metadata
       Url** into CostGraph.
  </Tab>

  <Tab title="Google Workspace">
    1. In the Google Admin console, go to **Apps > Web and mobile apps** and click
       **Add app > Add custom SAML app**. Name it `CostGraph`.
    2. Download the IdP metadata file. You'll upload it to CostGraph.
    3. Set **ACS URL** to the **ACS URL** and **Entity ID** to the **Entity ID**
       from CostGraph. Set **Name ID format** to
       `EMAIL`.
    4. Under **Attribute mapping**, map **Primary email** to
       `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`.
    5. To map groups to roles, under **Group membership**, choose the groups and set
       the app attribute to `groups`.
    6. Turn the app on for the organizational units that need it, and upload the
       metadata file in CostGraph with **Upload metadata file**.
  </Tab>

  <Tab title="OpenID Connect">
    1. In your identity provider, create a web application client.
    2. Save the identity provider in CostGraph first to get the **Redirect URI**,
       and add it to the client's allowed redirect URIs.
    3. In CostGraph, enter the **Issuer URL**, **Client ID**, and **Client
       secret**. CostGraph asks for the `openid`, `email`, and `profile` scopes.
    4. To map groups to roles, set **Groups attribute** to the claim that carries
       group names.

    CostGraph never shows the client secret again. Enter it each time you save.
  </Tab>
</Tabs>

People sign in by entering their work email on the CostGraph sign-in page.
CostGraph sends them to your identity provider.

## Roles from groups

Set a **Default role** for people who sign in through SSO. To map groups to
roles, click **Map a group**, then enter the group name your identity provider
sends and the CostGraph role it grants. **Groups attribute** is the name of the
attribute that carries the groups, such as `groups`.

You can grant **Member**, **Admin**, or **Billing admin** this way. CostGraph
applies the role every time the person signs in. When several groups match,
the highest role wins, in the order Admin, Billing admin, Member. People in no
mapped group get the default role. Organization owners keep their role.

## Auto-join

Turn on **Auto-join** for a verified domain to let anyone with an email address
at that domain join your organization without an invitation. People who join
this way get the **Member** role. Auto-join is off by default.

## Require single sign-on

Turn on **Require single sign-on** to make your identity provider the only way
in. You need a verified domain and an identity provider first.

When you turn it on:

* Everyone's current sessions and app authorizations end, and they sign in
  again through SSO.
* You choose what happens to personal API keys: **Keep personal API keys** or
  **Revoke personal API keys**. Keys for agents and installs keep working.

Organization owners can still sign in with a password and an authenticator
app, so you can get in if your identity provider is down. Set up an
authenticator app under your account's **Security** settings before you turn
on enforcement.

## Self-hosted

Self-hosted deployments sign in with email and password or Google. SAML and
OpenID Connect aren't available on self-hosted deployments yet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.