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

# Azure Entra OIDC dashboard auth

> Log into the Thoras dashboard via Azure Entra ID (formerly Azure AD) using the chart's built-in oauth2-proxy sidecar in OIDC mode.

This guide covers the Entra-specific steps for authenticating dashboard users
against Azure Entra ID. See the
[dashboard authentication overview](/guides/dashboard-auth) for how the built-in
sidecar works and how the two auth modes compare.

<Tip>
  If you already run your own oauth2-proxy sidecar against Azure Entra ID from a
  pre-5.0 install, your app registration and Secret carry over unchanged. See
  [Migrating from a hand-rolled oauth2-proxy
  sidecar](/guides/dashboard-auth#migrating-from-a-hand-rolled-oauth2-proxy-sidecar).
</Tip>

## Setup

### 1. Register an app in Azure Entra

1. In the Azure Portal, go to **Microsoft Entra ID -> App registrations -> New
   registration**.
2. For **Supported account types**, pick **Accounts in this organizational
   directory only (single tenant)**. Multi-tenant works but needs extra
   configuration (see the `issuerURL` field note below).
3. Set a **Redirect URI** of type "Web":
   `https://thoras.yourcompany.com/oauth2/callback`.
4. Note the **Application (client) ID** and **Directory (tenant) ID**. You'll
   need both.
5. Under **Certificates & secrets**, create a new client secret and copy its
   value immediately (it's only shown once).
6. **API permissions** need no changes. The default `Microsoft Graph User.Read`
   permission is enough for sign-in; oauth2-proxy requests the
   `openid email profile` scopes at sign-in, and users consent to them on first
   login.

<img src="https://mintcdn.com/thoras/inK4v_abKcgkVun6/guides/static/azure-app-registration.png?fit=max&auto=format&n=inK4v_abKcgkVun6&q=85&s=3b91aef57b2ba27827fd656c0ac13047" alt="azure-app-registration" width="752" height="294" data-path="guides/static/azure-app-registration.png" />

See oauth2-proxy's own walkthrough of this same registration process:
[Microsoft Entra ID provider config](https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/ms_entra_id).

### 2. Create the Kubernetes secret

The sidecar needs three values, read from a Kubernetes Secret you manage rather
than inlined in `values.yaml`. The chart never generates these:

| Key             | Purpose                                                        |
| --------------- | -------------------------------------------------------------- |
| `client-id`     | The application's client ID                                    |
| `client-secret` | The application's client secret                                |
| `cookie-secret` | A random value oauth2-proxy uses to encrypt its session cookie |

Generate the cookie secret with:

```bash theme={null}
openssl rand -base64 32 | head -c 32 | base64
```

Create the secret (values below are base64-encoded automatically by `kubectl`
when using `--from-literal`):

```bash theme={null}
kubectl create secret generic oauth2-proxy-secrets \
  --namespace thoras \
  --from-literal=client-id="<your-client-id>" \
  --from-literal=client-secret="<your-client-secret>" \
  --from-literal=cookie-secret="$(openssl rand -base64 32 | head -c 32 | base64)"
```

### 3. Switch the chart into OIDC mode

In `values.yaml`, set `thorasDashboard.auth.mode: oidc` and fill in the OIDC
block:

```yaml theme={null}
thorasDashboard:
  auth:
    mode: oidc
    oidc:
      provider: entra-id
      issuerURL: https://login.microsoftonline.com/<tenant-id>/v2.0
      redirectURL: https://thoras.yourcompany.com/oauth2/callback
      emailDomains: [yourcompany.com]
      existingSecret:
        secretName: oauth2-proxy-secrets
```

#### Field notes

* `provider`: `entra-id` selects Entra-specific handling in oauth2-proxy (group
  overage via Microsoft Graph, multi-tenant issuer checks). `oidc` also works
  against Entra but drops those Entra-specific features.
* `issuerURL`: points at your Entra tenant's v2.0 OIDC endpoint. Replace
  `<tenant-id>` with your Directory (tenant) ID. For a multi-tenant app, use
  `https://login.microsoftonline.com/common/v2.0` and add
  `--insecure-oidc-skip-issuer-verification` to `thorasDashboard.auth.extraArgs`
  (oauth2-proxy will otherwise reject the per-tenant issuer returned in tokens).
  See the
  [Entra ID provider docs](https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/ms_entra_id)
  for the full multi-tenant setup, including `entra-id-allowed-tenant`.
* `redirectURL`: must be the real external hostname of the dashboard, over
  HTTPS, and must exactly match a redirect URI registered on the Entra app
  registration.
* `emailDomains`: restricts login to your org's email domain(s). Use `["*"]` to
  allow any authenticated user.
* `existingSecret.secretName`: points at the Secret you created in step 2.

### 4. Deploy and verify

1. `helm upgrade` the release with the updated `values.yaml`.
2. Confirm the dashboard pod comes up healthy, and check the sidecar logs if
   something goes wrong:
   ```bash theme={null}
   kubectl -n thoras get pods -l app=thoras-dashboard
   kubectl -n thoras logs deploy/thoras-dashboard -c oauth2-proxy
   ```
3. Visit the dashboard URL. You should be redirected to your identity provider's
   login page, and land back on the dashboard after authenticating.
4. If the redirect fails or loops, double-check that `redirectURL` exactly
   matches a redirect URI registered on your identity provider's app, and that
   `issuerURL` is correct.

## Exposing the sidecar externally

The chart's built-in oauth2-proxy sidecar owns the dashboard's `containerPort`,
so the existing `thorasDashboard` Service already routes external traffic
through the auth check. No `service.targetPort` override is needed.

Expose the Service using whichever mechanism the chart already supports:

**Ingress**

```yaml theme={null}
thorasDashboard:
  ingress:
    enabled: true
    hosts:
      - host: thoras.yourcompany.com
        paths:
          - path: /
            pathType: Prefix
```

**Gateway API**

```yaml theme={null}
thorasDashboard:
  gatewayAPI:
    enabled: true
    parentRefs:
      - name: eg
        sectionName: http
    hostnames:
      - thoras.yourcompany.com
```

Adjust `ingressClassName`/`parentRefs` to match your cluster's actual Ingress
controller or `Gateway`, and terminate TLS there (or upstream at a
cert-manager-issued `Certificate` bound to it). Once DNS for
`thoras.yourcompany.com` resolves and a valid TLS cert is issued, visiting the
dashboard URL should trigger the login flow described above.

## Further reading

* [oauth2-proxy documentation home](https://oauth2-proxy.github.io/oauth2-proxy/)
* [Microsoft Entra ID provider configuration](https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/ms_entra_id)
* [Configuration overview / full flag reference](https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview)
* [Session storage options](https://oauth2-proxy.github.io/oauth2-proxy/configuration/session_storage)
* [TLS configuration](https://oauth2-proxy.github.io/oauth2-proxy/configuration/tls)