Shared foundation

View Markdown

Google Workspace & Entra ID.mdDownload .md

# IdP setup: Google Workspace & Microsoft Entra ID

Runku (MCP `runku` and AI Gateway `runku-ai`) verify bearer JWTs via standard
OIDC discovery. Both products follow the same
`auth.oidc` YAML shape.

## Quick validation (no credentials required)

```bash
# Google Workspace
runku-ai auth oidc check --issuer https://accounts.google.com

# Microsoft Entra ID (replace TENANT_ID)
runku-ai auth oidc check --issuer https://login.microsoftonline.com/TENANT_ID/v2.0
```

Discovery must return `authorization_endpoint` and `token_endpoint`. If that
fails, the issuer URL is wrong (common Entra mistake: missing `/v2.0`).

## Google Workspace

Example configs:

- AI: `configs/config.ai.oidc-google.example.yaml`
- MCP: `configs/config.oidc-google.example.yaml`

Rules:

| Field | Value |
|-------|--------|
| `issuer` | `https://accounts.google.com` |
| `audience` | OAuth **Client ID** |
| `portal_client_id` | Same Client ID (public PKCE client) |
| Bearer token | **ID token** (auto via `prefer_id_token` for Google) |

Google access tokens are opaque — Runku cannot verify them as JWTs. Portals and
`runku-ai login` therefore send the `id_token` when discovery sets
`prefer_id_token: true`.

## Microsoft Entra ID

Example configs:

- AI: `configs/config.ai.oidc-entra.example.yaml`
- MCP: `configs/config.oidc-entra.example.yaml`

Rules:

| Field | Value |
|-------|--------|
| `issuer` | `https://login.microsoftonline.com/<tenant-id>/v2.0` |
| `audience` | API app ID / App ID URI (`api://…`) |
| `portal_client_id` | SPA / public client ID |
| Bearer token | **Access token** JWT (`prefer_id_token: false`) |

Expose an API scope and grant the SPA client access so the access token’s `aud`
matches `auth.oidc.audience`.

## CLI login (AI Gateway)

Point the CLI at a running gateway — discovery (`GET /auth/config`) decides
whether SSO and/or a consumer key (`rk_ai_…`) are available. **Never** use
`rk_admin_…` here (that is portal/admin only).

```bash
# Auto: asks SSO vs key when OIDC is configured; otherwise prompts for rk_ai_
runku-ai login --url http://localhost:8088

# Consumer key only
runku-ai login --url http://localhost:8088 --key rk_ai_...

# Force IdP redirect (requires auth.oidc on the gateway)
runku-ai login --url http://localhost:8088 --sso

runku-ai whoami
runku-ai logout
```

SSO path: browser PKCE → optional `POST /admin/v1/me/keys` → stores `rk_ai_…`
under `~/.config/runku/ai/credentials.json`.


## MCP portal SSO

Same discovery endpoint: `GET /auth/config`. MCP portal uses the same PKCE
flow; send the token type advertised by `prefer_id_token`.

IdP setup: Google Workspace & Microsoft Entra ID

Runku (MCP runku and AI Gateway runku-ai) verify bearer JWTs via standard OIDC discovery. Both products follow the same auth.oidc YAML shape.

Quick validation (no credentials required)

# Google Workspace
runku-ai auth oidc check --issuer https://accounts.google.com

# Microsoft Entra ID (replace TENANT_ID)
runku-ai auth oidc check --issuer https://login.microsoftonline.com/TENANT_ID/v2.0

Discovery must return authorization_endpoint and token_endpoint. If that fails, the issuer URL is wrong (common Entra mistake: missing /v2.0).

Google Workspace

Example configs:

AI: configs/config.ai.oidc-google.example.yaml
MCP: configs/config.oidc-google.example.yaml

Rules:

Field	Value
`issuer`	`https://accounts.google.com`
`audience`	OAuth Client ID
`portal_client_id`	Same Client ID (public PKCE client)
Bearer token	ID token (auto via `prefer_id_token` for Google)

Google access tokens are opaque — Runku cannot verify them as JWTs. Portals and runku-ai login therefore send the id_token when discovery sets prefer_id_token: true.

Microsoft Entra ID

Example configs:

AI: configs/config.ai.oidc-entra.example.yaml
MCP: configs/config.oidc-entra.example.yaml

Rules:

Field	Value
`issuer`	`https://login.microsoftonline.com/<tenant-id>/v2.0`
`audience`	API app ID / App ID URI (`api://…`)
`portal_client_id`	SPA / public client ID
Bearer token	Access token JWT (`prefer_id_token: false`)

Expose an API scope and grant the SPA client access so the access token’s aud matches auth.oidc.audience.

CLI login (AI Gateway)

Point the CLI at a running gateway — discovery (GET /auth/config) decides whether SSO and/or a consumer key (rk_ai_…) are available. Never use rk_admin_… here (that is portal/admin only).

# Auto: asks SSO vs key when OIDC is configured; otherwise prompts for rk_ai_
runku-ai login --url http://localhost:8088

# Consumer key only
runku-ai login --url http://localhost:8088 --key rk_ai_...

# Force IdP redirect (requires auth.oidc on the gateway)
runku-ai login --url http://localhost:8088 --sso

runku-ai whoami
runku-ai logout

SSO path: browser PKCE → optional POST /admin/v1/me/keys → stores rk_ai_… under ~/.config/runku/ai/credentials.json.

MCP portal SSO

Same discovery endpoint: GET /auth/config. MCP portal uses the same PKCE flow; send the token type advertised by prefer_id_token.