DocumentationAccess ControlAuthentication

OIDC Setup

View as Markdown

Connect NeMo Platform to an external OIDC identity provider (IdP) so users sign in with your organization’s identity and receive OAuth2 access tokens for API access.

Prerequisites: You need an OAuth application registered in your IdP with the client ID, issuer URL, and device flow grant enabled. See the Minimum IdP Checklist below.

For login after setup, see Using Authentication. For the full config reference, see Auth Configuration.

How OIDC Fits in NeMo Platform

When OIDC is enabled:

  1. Platform configuration points to your IdP (issuer URL, client ID, optional scope prefix and claim names).
  2. Discovery: Clients and the platform discover token and device-auth endpoints from the IdP’s .well-known/openid-configuration (or from NeMo Platform’s aggregated discovery at {BASE_URL}/apis/auth/discovery).
  3. Login: Users obtain access tokens via device flow (browser) or password grant (CI) using the CLI.
  4. API calls: Requests send the access token in the Authorization: Bearer <token> header. NeMo Platform validates the JWT (signature, issuer, audience, expiry) and extracts the principal and scopes for authorization.

OIDC provides the identity; authorization (workspace roles, scopes) works the same as with any other auth method.

Flows Supported

  • Device authorization flow: User runs nemo auth login; the CLI shows a code and opens the IdP page; after the user signs in and consents, the CLI receives an access token (and optionally a refresh token). Best for interactive use.
  • Resource owner password grant: For non-interactive environments (CI), nemo auth login --username <user> --password <pass> exchanges credentials for a token. Your IdP must support this grant type.

Password grant sends user credentials directly to the IdP. It bypasses MFA and is disabled by many production IdPs. Use it only for CI/testing. Prefer device flow for interactive users.

Step-by-Step Configuration

Step 1: Register an OAuth Application

In your IdP (Azure AD, Okta, Keycloak, etc.):

  1. Create a new application registration
  2. Note the client ID
  3. Enable device flow (device authorization grant)
  4. (Optional) Create custom API scopes (platform:read, platform:write) if you want token-level scope restrictions. See API Scopes.
  5. If you created custom scopes, grant admin consent for them (if required by your IdP)

Step 2: Configure NeMo Platform

Set the OIDC settings in your platform config under auth.oidc:

1auth:
2 enabled: true
3 admin_email: "platform-admin@company.com"
4 oidc:
5 enabled: true
6 issuer: "https://your-idp.example.com/realm"
7 client_id: "your-client-id"
8 # Optional: strip IdP scope prefix (e.g., Azure AD prepends API URI)
9 # scope_prefix: "api://your-client-id/"
10 # Optional: override claim names if your IdP uses non-standard names
11 # email_claim: "upn"
12 # subject_claim: "oid"
13 # groups_claim: "groups"

Step 3: Configure Scopes (Optional)

This step is only needed if you created custom API scopes in Step 1. If you skip scopes, NeMo Platform still enforces RBAC — scopes add an additional token-level restriction on top. See API Scopes.

If you are using scopes, configure the default scopes requested during login:

1auth:
2 oidc:
3 default_scopes: "openid profile email offline_access platform:read platform:write"

If your IdP prefixes scopes (e.g., Azure AD uses api://client-id/platform:read), set scope_prefix so NeMo Platform strips it before authorization:

1auth:
2 oidc:
3 scope_prefix: "api://your-client-id/"

Step 4: Verify

After deploying the configuration:

$# Log in via device flow
$nemo auth login
$
$# Check login status
$nemo auth status
$# Expected: shows principal email, scopes, token expiry
$
$# Verify API access
$nemo workspaces list

OIDC Configuration Reference

FieldTypeDescription
enabledboolEnable OIDC token validation.
issuerstringIdP issuer URL (e.g., https://login.microsoftonline.com/<tenant>/v2.0).
client_idstringOAuth client ID for NeMo Platform.
additional_issuerslistExtra issuer URLs to accept (e.g., Azure AD v1 format).
audiencestringExpected token audience (defaults to client_id).
email_claimstringJWT claim for email (default: email).
subject_claimstringJWT claim for subject (default: sub).
groups_claimstringJWT claim for groups (default: groups).
default_scopesstringSpace-separated scopes requested when user does not pass --scope.
scope_prefixstringPrefix stripped from token scopes before authorization.
token_endpointstringOverride token endpoint (otherwise discovered from IdP).
device_authorization_endpointstringOverride device auth endpoint.
jwks_uristringOverride JWKS URI.

Minimum IdP Checklist

Regardless of IdP, ensure:

  1. You have registered an OAuth application and have the client ID (and client secret if required).
  2. The application supports the device authorization grant (for nemo auth login).
  3. The access token includes claims for email, subject, and groups (or you have configured email_claim, subject_claim, groups_claim to match your IdP’s claim names).
  4. (If using scopes) Custom API scopes (platform:read, platform:write) are exposed, included in access tokens, and admin consent is granted if required.

Claim mapping

NeMo Platform maps JWT claims to trusted identity headers using email_claim, subject_claim, and groups_claim (defaults: email, sub, groups). Override them when your IdP uses different claim names — values must match what you use for workspace members and authorization.

PurposeConfig keyDefaultHeader
Subject (Principal ID)subject_claimsubX-NMP-Principal-Id
Emailemail_claimemailX-NMP-Principal-Email
Groupsgroups_claimgroupsX-NMP-Principal-Groups

Group values are extracted from the JWT and included in the X-NMP-Principal-Groups header and OPA policy data, but automatic group-to-role mapping is not yet implemented. Role assignments must be made explicitly via the members API. See Managing Access.

Provider-Specific Notes

  • Azure AD: See Azure AD Setup (issuer, additional_issuers, device flow, claim overrides).
  • Okta: Choose the correct authorization server (custom vs org). Ensure device flow is enabled.
  • Keycloak: Configure realm, client, and role mappers. Enable device flow in client settings.
  • Other providers: See Generic OIDC Provider for a provider-agnostic checklist.