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

# Okta

> Authenticate users via Okta OpenID Connect with `oktaProvider()`. Create an OIDC web app in the Okta Admin Console, copy your domain, and configure the provider.

## Get credentials

<Steps>
  <Step>
    ### Create an OIDC app

    In the Okta Admin Console, go to **Applications > Create App Integration** and choose **OIDC - OpenID Connect** with application type **Web Application**.

    Set the **Sign-in redirect URI** to:

    ```
    https://your-app.com/api/kavach/auth/oauth/callback/okta
    ```
  </Step>

  <Step>
    ### Copy your credentials

    From the app settings, copy the **Client ID** and **Client Secret**. Your domain is shown at the top of the console: `your-org.okta.com`.
  </Step>
</Steps>

## Configuration

```typescript title="lib/kavach.ts" theme={"system"}
import { createKavach } from 'kavachos';
import { oauth, oktaProvider } from 'kavachos/auth';

const kavach = await createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  secret: process.env.KAVACH_SECRET!,
  baseUrl: 'https://your-app.com',
  plugins: [
    oauth({
      providers: [
        oktaProvider(
          process.env.OKTA_DOMAIN!,        // your-org.okta.com
          process.env.OKTA_CLIENT_ID!,
          process.env.OKTA_CLIENT_SECRET!,
        ),
      ],
    }),
  ],
});
```

```bash theme={"system"}
OKTA_DOMAIN=your-org.okta.com
OKTA_CLIENT_ID=...
OKTA_CLIENT_SECRET=...
```

## Scopes

Default scopes: `openid`, `profile`, `email`

| Scope            | What it unlocks                                 |
| ---------------- | ----------------------------------------------- |
| `openid`         | OIDC authentication, issues ID token            |
| `profile`        | Name, locale, and profile metadata              |
| `email`          | Email address and verification status           |
| `groups`         | Group membership (requires group claim in Okta) |
| `offline_access` | Refresh token support                           |

<Info>
  For Okta Identity Engine orgs, the domain may be a custom domain. Use the exact domain shown in your Okta Admin Console rather than the default `okta.com` subdomain.
</Info>

## Endpoints

| Method | Path                         | Description      |
| ------ | ---------------------------- | ---------------- |
| GET    | `/auth/oauth/authorize/okta` | Redirect to Okta |
| GET    | `/auth/oauth/callback/okta`  | Handle callback  |