--- id: oidc title: OpenID Connect --- Added in: v0.1.0-alpha.11 pnpr supports OIDC browser sign-in and keyless npm publishing from workloads such as GitHub Actions. Both use discovery and signed ID tokens from explicitly configured issuers. Local password authentication keeps working alongside them. ## Browser sign-in Register a web application with your identity provider. Set its callback to `https://registry.example/-/oidc/company/callback`, replacing the hostname and `company` with your pnpr provider name, and enable the authorization code flow. Start pnpr with `--public-url https://registry.example`, its HTTPS origin without a path prefix. ```yaml title="pnpr.yaml" auth: oidc: - name: company issuer: https://accounts.google.com audience: your-client-id login: clientSecret: ${OIDC_CLIENT_SECRET} users: - subject: 'the-users-stable-sub-claim' username: alice claims: hd: example.com ``` `audience` is the application's client ID. `clientSecret` can be omitted for providers that support public clients with PKCE. `subject` is the exact `sub` claim issued to this application, not an email address. Each binding maps that subject to a pnpr username, and the registry's existing access rules and teams then apply. Extra `claims` are exact string matches and all of them must match. There is no automatic account creation, and no linking by email. ### Teams from groups A signed-in session can also join teams through the groups your identity provider puts in the ID token: ```yaml title="pnpr.yaml" auth: oidc: - name: company issuer: https://login.microsoftonline.com//v2.0 audience: your-client-id login: users: - subject: 'the-users-stable-sub-claim' username: alice groups: claim: groups teams: - group: 7f3c2a10-0000-0000-0000-000000000000 registry: private team: platform ``` - `claim` names the ID-token claim that lists the groups, either as a list of strings or as one string. It defaults to `groups`. - A session whose claim lists `group` is a member of `team` on the hosted registry `registry`, as if the team listed its username. `registry` is the registry's key in `registries:`. - The membership lasts as long as the session. Removing someone from a group takes effect at their next sign-in, within an hour. It never applies to the user's password logins or `npm token`s. - On a registry whose teams are the config's, the team must be declared in its `teams:`. With [`teamsManagedBy: api`](configuration.md#managing-teams-through-the-api), it may name a team the admin API creates later. Configure the provider to issue the claim, and use the values it emits as `group`. Entra ID emits group object IDs under `groups` once group claims are enabled for the application, as in the example above. Okta emits group names under `groups` when a groups claim is added to the authorization server. Use the issuer your provider publishes: | Provider | Issuer | | --- | --- | | Google Workspace | `https://accounts.google.com` | | Microsoft Entra ID | `https://login.microsoftonline.com//v2.0` | | Okta org authorization server | `https://.okta.com` | | Okta custom authorization server | `https://.okta.com/oauth2/` | Use a tenant-specific Entra issuer. For Google Workspace, require the `hd` claim for your organization's domain, as shown above. See the provider documentation for [Google](https://developers.google.com/identity/openid-connect/reference), [Entra](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc), and [Okta](https://developer.okta.com/docs/concepts/auth-servers/). Open `https://registry.example/-/oidc/company/login` in a browser. After sign-in, pnpr displays a token to put in the registry's `_authToken` setting, for example in your private user `.npmrc`: ```ini title=".npmrc" //registry.example/:_authToken=THE_DISPLAYED_TOKEN ``` The browser session expires at the earlier of one hour or the ID token's expiry, and `npm logout` revokes it. Sessions live in memory and disappear on restart, so a multi-replica deployment needs affinity for both the login flow and the authenticated requests that follow. They do not appear in `npm token list`. The [web UI](web-ui.md) lists these providers on its sign-in screen and returns to the UI after sign-in. `pnpm login` and `npm login` use this flow automatically via `/-/v1/login`. The CLI opens the browser to sign in and polls until authentication completes. If no OIDC provider declares `login:`, `/-/v1/login` returns `404` and the CLI falls back to username and password authentication (`/-/user/org.couchdb.user:{name}`). An OIDC session cannot yet be exchanged for an [OCI scoped bearer token](container-images.md#authentication). ## GitHub Actions keyless publishing Configure a dedicated workload username, a named hosted npm registry, and exact package names. The package's normal `publish` rule must grant that username access too. ```yaml title="pnpr.yaml" registries: private: type: hosted packages: '@example/widget': publish: [release-ci] auth: oidc: - name: github issuer: https://token.actions.githubusercontent.com audience: https://registry.example workloads: - identity: subject: repo:example/widgets:ref:refs/heads/main username: release-ci claims: repository_id: '123456789' repository_owner_id: '987654321' workflow_ref: example/widgets/.github/workflows/release.yml@refs/heads/main registry: private packages: ['@example/widget'] ``` Use immutable repository and owner IDs so trust does not transfer when names are reused. For reusable workflows, also require `job_workflow_ref` to pin the workflow that performs the publication. A job using a GitHub environment has an environment-based subject, such as `repo:example/widgets:environment:production`. Configure the exact subject and the additional claims you intend to trust. See [GitHub's OIDC reference](https://docs.github.com/en/actions/reference/security/oidc). The publishing job needs `id-token: write`. Request an ID token with pnpr's configured audience and prefix it with `pnpr_workload_` as the registry token. No pnpr password, persistent API key, or token exchange is involved: ```yaml permissions: contents: read id-token: write steps: # Check out, install dependencies, and build before requesting the token. - name: Publish to pnpr shell: bash run: | response=$(curl --fail --silent --show-error \ -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \ "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=https%3A%2F%2Fregistry.example") token=$(jq -er '.value' <<< "$response") echo "::add-mask::$token" export NODE_AUTH_TOKEN="pnpr_workload_${token}" npm publish --registry=https://registry.example/npm/~private/ ``` The project's `.npmrc` holds only the environment reference: ```ini title=".npmrc" //registry.example/npm/~private/:_authToken=${NODE_AUTH_TOKEN} ``` The credential permits ordinary `PUT` publications to the configured packages through that named registry and nothing else. It cannot read packages, unpublish, change dist-tags separately, manage accounts, publish batches, or reach other pnpr services. Request the token after building so it stays valid through the publish request; its issuer's expiry applies to every request. ## Keys Every block rejects unknown keys. | Key | Required | Description | | --- | --- | --- | | `name` | yes | Provider name, used in the `/-/oidc//` URLs. | | `issuer` | yes | The provider's issuer URL. | | `audience` | yes | The expected `aud` claim. For browser sign-in, the client ID. | | `login.clientSecret` | no | Client secret for browser sign-in. Omit for public clients with PKCE. | | `login.users` | yes, with `login` | Bindings of `subject`, `username`, and optional `claims`. | | `login.groups.claim` | no | The ID-token claim that lists groups. Defaults to `groups`. | | `login.groups.teams` | yes, with `groups` | Grants of `group`, `registry`, and `team`. See [Teams from groups](#teams-from-groups). | | `workloads[].identity` | yes | A binding of `subject`, `username`, and optional `claims`. | | `workloads[].registry` | yes | The hosted npm registry the workload publishes to. | | `workloads[].packages` | yes | The exact package names the workload may publish. | ## Validation and operations pnpr accepts RS256 and ES256 signatures and verifies the issuer, audience, authorized party where present, expiry, issue time, and not-before claims. Browser login also verifies a browser-bound state, a nonce, and S256 PKCE. Unmapped and ambiguous identities are rejected, and user subjects must be unique within a provider, its workload bindings included. The `pnpr_oidc_` and `pnpr_workload_` credential prefixes are reserved for OIDC, and workload credentials bypass the persistent token backend. Discovery and JWKS use HTTPS with redirects disabled and bounded response sizes and deadlines. Literal and DNS-resolved destinations must be public IP addresses, and OIDC requests ignore environment-configured HTTP proxies. Metadata is cached for five minutes, and a verification failure can trigger a refresh at most once every 30 seconds per provider, so an unavailable provider can never turn an invalid credential into anonymous access. Login state lives in a signed HttpOnly cookie for five minutes. Anonymous login starts reserve no server-side entries. Successful login replays and browser sessions are each capped at 1,024 per process, and a separate 1,024-entry callback-attempt history rejects recent failed and concurrent replays before token exchange, evicting the oldest attempt when full. At most 16 browser callbacks perform network operations concurrently. pnpr omits OIDC callback query strings from its request logs. Configure reverse proxies to omit them too.