# Single sign-on with Okta

Use [Okta](https://www.okta.com/) to let your team sign in to LedgerBee. You need
an admin account in LedgerBee and permission to create applications in your Okta
org.

Setup has three steps: verify domain ownership, create the application in Okta,
and configure the connection in LedgerBee.

## Verify domain ownership

1. Go to **Settings → Workflows & access → Single sign-on** in LedgerBee, enter
   your domain under **Verified email domains**, and click **Add domain**.
2. Publish the record LedgerBee shows at your DNS provider, as a `TXT` record
   with the host `_ledgerbee-sso`.
3. Click **Check now**. The status changes to **Verified**.

Enter the host as `_ledgerbee-sso` without your domain — DNS providers append
the zone to whatever you type in the name field.

Repeat for every email domain your team signs in with. Leave each record
published; LedgerBee re-checks them daily.

## Create the application in Okta

1. In the Okta Admin Console, go to **Applications → Applications** and select
   **Create App Integration**.
2. Choose **OIDC - OpenID Connect** as the sign-in method and **Web
   Application** as the application type. Select **Next**.
3. Name the application, for example `LedgerBee`.
4. Under **Grant type**, keep **Authorization Code** selected.
5. Under **Sign-in redirect URIs**, paste the redirect URI from the **Identity
   provider** section of the LedgerBee SSO page. Use the **Copy** button — the
   value must match byte-for-byte.
6. Under **Assignments**, choose who can use the application.
7. Select **Save**.

Okta shows the **Client ID** and **Client secret** on the application's
**General** tab. The secret stays retrievable in Okta, unlike some providers.

### Collect the issuer URL

Use the **org** authorization server, whose issuer is your org URL with no path:
`https://<your-org>.okta.com`. Okta recommends it for OIDC single sign-on, and
LedgerBee reads only ID-token claims, so nothing a custom authorization server
adds applies here.

Confirm the value by opening
`https://<your-org>.okta.com/.well-known/openid-configuration`. The `issuer` in
that document is what you enter in LedgerBee, verbatim.

A **custom** authorization server — including the one Okta names `default`,
which issues from `https://<your-org>.okta.com/oauth2/default` — also works, but
it evaluates an **access policy** on every sign-in request, and the `default`
server ships without one on Okta Integrator Free Plan orgs. Sign-in then stops
at an Okta **400 Bad Request** page reading "Policy evaluation failed for this
request", before Okta ever returns to LedgerBee. To use one, go to
**Security → API**, open the server, and under **Access Policies** add a policy
that includes this application, with a rule granting `openid`, `email` and
`profile`.

The two forms are different issuers publishing different documents. Mixing them
is the most common cause of a failed connection check.

## Configure the connection in LedgerBee

On the SSO page, fill in **Identity provider**:

| Field | Value |
| --- | --- |
| **Issuer URL** | The **Issuer URI** from your Okta authorization server |
| **Client ID** | The **Client ID** from the application's General tab |
| **Client secret** | The **Client secret** from the same tab |
| **Subject claim** | `sub` |

Select **Save**. Saving runs the check.

Leave the application's **Client authentication** on **Client secret**.
LedgerBee reads the method to use from your org's published metadata, so there
is nothing to match up by hand.

## Check the connection

Saving reads Okta's metadata and presents your client credentials to it. When
Okta accepts them, the connection is live — no separate step. If it does not
pass, the connection is still saved and **Check again** re-runs it.

Assign the application to the people who should sign in — the check confirms
your credentials, not who Okta admits.

## Sign in

Members reach the connection through the login URL shown on the SSO page. Set it
as the **Initiate login URI** on the application's General tab so the LedgerBee
tile works from the Okta dashboard.

If the check fails, or a member's first sign-in does, see [Troubleshoot SSO](/guides/sso/troubleshooting).