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

# Access Control & SSO

> Protect your status page with SSO authentication, access tokens, role-based visibility, and session management.

## Visibility Modes

Every status page has a visibility setting that controls who can view it:

| Mode         | Access                            | Auth Method | Plan      |
| ------------ | --------------------------------- | ----------- | --------- |
| **Public**   | Anyone on the internet            | None        | All plans |
| **Private**  | Users with the password           | Password    | Pro+      |
| **Internal** | Users from your identity provider | SSO (OIDC)  | Team+     |

Configure visibility per status page in **Dashboard > Status Pages > \[your page] > Visibility**. Each [status page](/status-management/status-pages) can have its own visibility setting.

***

## Private Mode (Password)

Private status pages require a password to view. This is useful when you want to share your status page with a limited audience without setting up SSO.

1. Go to **Dashboard > Status Pages > \[your page] > Visibility** and set visibility to **Private**.
2. Enter a password. This is the password your viewers will use to access the page.
3. Optionally add a **password hint** that will be shown on the login screen.
4. Save.

When a user visits the status page, they are prompted to enter the password. Authenticated sessions last 24 hours.

<Info>
  Password-authenticated users always receive **Full** access. Role-based access controls (Full vs Limited) only apply to SSO-authenticated users.
</Info>

***

## SSO Authentication

<Warning>
  Internal visibility (SSO) requires a **Team** plan or higher. RBAC features require **Enterprise**. [View pricing](https://kodostatus.com/pricing).
</Warning>

Internal status pages require users to sign in through an OIDC-compatible identity provider before viewing the page. The authentication flow uses PKCE for security, validates JWT signatures via JWKS, and creates time-limited sessions.

### Supported Providers

* **Google** — Google Workspace / Cloud Identity
* **Microsoft** — Azure AD / Entra ID
* **Okta** — Okta Workforce Identity
* **Custom OIDC** — Any provider with a `.well-known/openid-configuration` endpoint

### Setting Up SSO

1. Go to **Dashboard > Settings > Access Control** and click **Add Provider**.
2. Select your identity provider type.
3. Enter your **Client ID** and **Client Secret** from your IdP.
4. For Okta or Custom OIDC, enter the **Issuer URL** (e.g. `https://your-domain.okta.com`).
5. If your IdP uses a non-standard JWT claim name for groups, enter it in the **Group Claim Name** field (see [Custom Group Claim Names](#custom-group-claim-names) below).
6. Copy the **Callback URL** shown in the dialog and register it with your IdP as an authorized redirect URI.
7. Click **Test Connection** to verify OIDC discovery works.
8. Save the provider.

Then set any status page to **Internal** visibility in its Visibility tab.

<Note>
  For Okta, ensure your application's scopes include `groups` so that group claims appear in the ID token. This is required for role-based access controls.
</Note>

***

## Allowed Email Domains

Restrict SSO access to specific email domains. Only users whose email address matches an allowed domain can authenticate.

* Navigate to **Dashboard > Settings > Access Control > Allowed Email Domains**
* Add domains like `company.com` or `partner.org`
* Leave the list empty to allow any authenticated user from your IdP

Domain matching gates whether a viewer can sign in at all. To control *what they see* once signed in, use Audiences.

***

## Status-page access is binary

Once a viewer is authenticated and their email domain is allowed, they're authorized to view the page. There is no per-row "full" vs "limited" role on status pages — that distinction was retired in favor of **Audiences**, which give you finer control by routing viewers to scoped views of services and incidents.

If you previously used the page-scoped or org-scoped group mapping table, those mappings have been migrated; new role assignment for status-page viewers should be done through Audiences.

### Audiences (recommended)

Audiences let you publish different curated views of the same status page to different viewer groups. A viewer is matched to an audience by either their IdP group claims or their email domain. They see only the services and incidents that the matched audience is configured to expose.

This replaces the older two-role model with something more flexible: instead of "everything vs nothing", you define exactly what each segment sees.

### Group-claim-driven matching

Audiences are matched against the same IdP group claim used for dashboard SSO. Configure the claim name on the SSO provider — by default Kodo reads `groups` (Okta), `roles` (Azure AD), and `cognito:groups` (AWS Cognito), and you can override per-provider.

### Custom Group Claim Names

Enterprise identity providers often use non-standard JWT claim names for group membership. You can configure this per SSO provider.

In the SSO provider dialog, enter your custom claim name in the **Group Claim Name** field. This supports:

* **Simple claim names** — e.g. `custom_groups`, `team_roles`
* **Dotted paths** — e.g. `custom.groups` or `attributes.roles` for nested claims

When a custom claim name is configured, Kodo checks it first, then falls back to the standard claim names (`groups`, `roles`, `cognito:groups`).

<Tip>
  **Finding your claim name**: Log into your IdP admin console, inspect the ID token payload for a test user, and look for the claim containing group membership arrays. Common examples:

  * Okta custom authorization server: `custom:groups`
  * Azure AD app roles: `roles`
  * Auth0: `https://your-app/roles`
</Tip>

### Authorization Resolution

When a user authenticates:

1. **Domain allowlist** — if any allowed domains are configured for the page (or org-wide), the viewer's email domain must be on the list. Otherwise sign-in is denied.
2. **Audience match** — the viewer's IdP groups and email domain are matched to a configured Audience. Their view of services and incidents is scoped to that audience.
3. **Fallback** — if no audience matches, the viewer sees the page's default view.

***

## Access Tokens

Access tokens provide programmatic or automated access to non-public status pages. Use them for CI/CD pipelines, monitoring dashboards, internal tools, or any system that needs to read your status page without interactive login.

### Creating a Token

1. Navigate to **Dashboard > Status Pages > \[your page] > Visibility**.
2. In the **Access Tokens** section, click **Create Token**.
3. Enter a descriptive **name** (e.g. "CI/CD Pipeline", "Grafana Dashboard").
4. Choose an **access role**: **Full** or **Limited**.
5. Optionally set an **expiry date**. Tokens without an expiry remain valid until revoked.
6. Click **Create Token**.

<Warning>
  The full token value is shown **only once** after creation. Copy it immediately and store it securely. You will not be able to view it again.
</Warning>

### Using a Token

Append the token as a query parameter to your status page URL:

```
https://kodostatus.com/status/your-slug?token=YOUR_TOKEN
```

The `verify_status_page_access` check will validate the token, update its `last_used_at` timestamp, and grant the configured access role.

### Managing Tokens

The **Access Tokens** table in the Visibility tab shows all tokens for the page:

| Column        | Description                                     |
| ------------- | ----------------------------------------------- |
| **Name**      | The label you gave the token                    |
| **Token**     | Masked value showing only the last 8 characters |
| **Role**      | `Full` or `Limited` access                      |
| **Expires**   | Expiry date, or "Never" for non-expiring tokens |
| **Last Used** | When the token was last used to access the page |

Click the trash icon to **revoke** a token. Revoked tokens are immediately invalid.

### Token Best Practices

* **One token per integration** — create separate tokens for each system so you can revoke independently
* **Use expiry dates** for temporary access (e.g. a contractor's dashboard view)
* **Use Limited role** for external consumers who should only see overall status
* **Rotate tokens periodically** for long-lived integrations

***

## Session Management

The **Active Sessions** section in the Visibility tab shows all currently authenticated sessions on your status page. This includes sessions from SSO logins, password authentications, and any other auth method.

### Viewing Sessions

Each session row shows:

| Column      | Description                                                       |
| ----------- | ----------------------------------------------------------------- |
| **Email**   | The authenticated user's email (SSO sessions)                     |
| **Method**  | How the user authenticated: `SSO`, `Password`, or `Token`         |
| **Role**    | The access role assigned to this session                          |
| **IP**      | The IP address the session was created from                       |
| **Login**   | When the session was created                                      |
| **Expires** | When the session will automatically expire (24 hours after login) |

### Revoking Sessions

* **Revoke a single session** — click the trash icon on any session row. The user will be prompted to re-authenticate on their next visit.
* **Revoke all sessions** — click the **Revoke All** button at the top of the section. This immediately invalidates all active sessions for this status page.

<Tip>
  Use session revocation when you suspect compromised credentials, when an employee leaves the organization, or when you change the status page visibility from internal back to public.
</Tip>

***

## Audit Trail

All authentication events are logged to the [Audit Log](/audit-log) for compliance and security review:

| Event                               | When it's logged                                             |
| ----------------------------------- | ------------------------------------------------------------ |
| `sso.login_success`                 | A user successfully authenticates via SSO                    |
| `sso.login_failed`                  | An SSO attempt fails (bad token, wrong domain, JWKS failure) |
| `status_page.password_auth_success` | A user enters the correct password                           |
| `status_page.password_auth_failed`  | A user enters the wrong password                             |
| `access_token.created`              | An admin creates a new access token                          |
| `access_token.revoked`              | An admin revokes an access token                             |

Each entry includes the actor (email or IP), the status page, and relevant metadata such as the SSO provider type, resolved role, or failure reason. View these in **Settings > Audit Log** and filter by resource type `Status Pages` or `Access Tokens`.