@softistx/janus-oidc 0.0.0-stage → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +175 -2
  3. package/dist/claims/scopes.d.ts +15 -0
  4. package/dist/claims/scopes.d.ts.map +1 -0
  5. package/dist/claims/types.d.ts +36 -0
  6. package/dist/claims/types.d.ts.map +1 -0
  7. package/dist/create.d.ts +19 -0
  8. package/dist/create.d.ts.map +1 -0
  9. package/dist/http/discovery.d.ts +13 -0
  10. package/dist/http/discovery.d.ts.map +1 -0
  11. package/dist/http/handlers.d.ts +16 -0
  12. package/dist/http/handlers.d.ts.map +1 -0
  13. package/dist/http/respond.d.ts +8 -0
  14. package/dist/http/respond.d.ts.map +1 -0
  15. package/dist/http/source.d.ts +13 -0
  16. package/dist/http/source.d.ts.map +1 -0
  17. package/dist/http/urls.d.ts +7 -0
  18. package/dist/http/urls.d.ts.map +1 -0
  19. package/dist/http/userinfo.d.ts +15 -0
  20. package/dist/http/userinfo.d.ts.map +1 -0
  21. package/dist/id-token/at-hash.d.ts +4 -0
  22. package/dist/id-token/at-hash.d.ts.map +1 -0
  23. package/dist/id-token/hook.d.ts +15 -0
  24. package/dist/id-token/hook.d.ts.map +1 -0
  25. package/dist/id-token/sign.d.ts +16 -0
  26. package/dist/id-token/sign.d.ts.map +1 -0
  27. package/dist/index.d.ts +15 -0
  28. package/dist/index.d.ts.map +1 -0
  29. package/dist/index.js +423 -0
  30. package/dist/index.js.map +20 -0
  31. package/dist/types.d.ts +99 -0
  32. package/dist/types.d.ts.map +1 -0
  33. package/docs/README.md +18 -0
  34. package/docs/guide/claims.md +92 -0
  35. package/docs/guide/discovery.md +51 -0
  36. package/docs/guide/getting-started.md +79 -0
  37. package/docs/guide/issuers.md +54 -0
  38. package/docs/roadmap.md +32 -0
  39. package/docs/troubleshooting.md +112 -0
  40. package/package.json +67 -5
@@ -0,0 +1,92 @@
1
+ # Claims and scopes
2
+
3
+ `claims(user, scopes, { issuer })` is the one place your user data enters. It is
4
+ given the user's id (`{ id }`), the scopes the token carries and the issuer the
5
+ request went through, and may be async. A callback that takes only the first
6
+ two arguments keeps working.
7
+
8
+ ```ts
9
+ createOidcProvider({
10
+ claims: async ({ id }) => {
11
+ const user = await directory.find(id);
12
+ return {
13
+ name: user.name,
14
+ given_name: user.firstName,
15
+ email: user.email,
16
+ email_verified: user.emailVerified,
17
+ phone_number: user.phone,
18
+ roles: user.roles, // a claim of your own
19
+ };
20
+ },
21
+ });
22
+ ```
23
+
24
+ Return **everything you know**: the provider keeps the claims the granted scopes
25
+ release and drops the rest. The standard claim names are typed as OpenID Connect
26
+ spells them (`given_name`, `email_verified`, `updated_at` a number, `address` an
27
+ object); any other key is a claim of your own.
28
+
29
+ ## What a scope releases
30
+
31
+ (OpenID Connect Core §5.4.)
32
+
33
+ | Scope | Claims |
34
+ | --- | --- |
35
+ | `openid` | `sub` only |
36
+ | `profile` | `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`, `updated_at` |
37
+ | `email` | `email`, `email_verified` |
38
+ | `address` | `address` |
39
+ | `phone` | `phone_number`, `phone_number_verified` |
40
+
41
+ For scopes of your own, name the claims they release:
42
+
43
+ ```ts
44
+ createOidcProvider({ claims, scopeClaims: { roles: ['roles'], 'read:orders': ['customer_id'] } });
45
+ ```
46
+
47
+ A scope named in `scopeClaims` replaces the standard table for that scope. A
48
+ scope still has to be offered by a resource of the server to be requested.
49
+
50
+ ## The issuer
51
+
52
+ The third argument is `{ issuer }`: the issuer identifier of the server that
53
+ authenticated the userinfo token, or that signs the ID Token. With one server it
54
+ is always the same string; with `issuers()` (several tenants) it is the issuer
55
+ `resolve` answered for the request, so users kept in one pool per issuer are
56
+ looked up in the right one:
57
+
58
+ ```ts
59
+ createOidcProvider({
60
+ claims: async ({ id }, _scopes, { issuer }) => {
61
+ const user = await directory.partition(issuer).find(id);
62
+ return { email: user.email };
63
+ },
64
+ });
65
+ ```
66
+
67
+ The same applies on both paths: userinfo and the ID Token (`includeClaims`).
68
+
69
+ ## `sub` and the reserved claims
70
+
71
+ `sub` is always the user's id; it is the same in the ID Token and at userinfo.
72
+ `iss`, `aud`, `exp`, `iat`, `nbf`, `jti`, `auth_time`, `nonce`, `at_hash`,
73
+ `c_hash`, `amr`, `acr` and `azp` can never come from `claims` or a scope table.
74
+ The type refuses a `sub` in the returned object.
75
+
76
+ ## Claims in the ID Token
77
+
78
+ By default the ID Token is small and the claims are at userinfo (Core §5.4: the
79
+ client asks for them with the access token). For a client that does not call
80
+ userinfo:
81
+
82
+ ```ts
83
+ createOidcProvider({ claims, idToken: { includeClaims: true } });
84
+ ```
85
+
86
+ `claims` then runs for each token response, with the same filtering.
87
+
88
+ ## Failures
89
+
90
+ `claims` is on the path of every userinfo request. When it throws, the request
91
+ rejects and nothing is stored: the framework answers 503. Cache in the function
92
+ if your directory is slow.
@@ -0,0 +1,51 @@
1
+ # Discovery
2
+
3
+ `openid.discovery` answers `GET /.well-known/openid-configuration` (for an
4
+ issuer with a path, `/.well-known/openid-configuration/<path>`, Discovery §4.1;
5
+ anything else is a 404, a method other than GET a 405). It is public, cacheable
6
+ for five minutes and readable from any origin.
7
+
8
+ ## What is in it
9
+
10
+ `janus-oauth`'s RFC 8414 metadata for the same issuer (its endpoints,
11
+ `code_challenge_methods_supported`, `token_endpoint_auth_methods_supported`,
12
+ `authorization_response_iss_parameter_supported`, `device_authorization_endpoint` when the server has the device grant on, and `pushed_authorization_request_endpoint` (with `require_pushed_authorization_requests` when required) when it has pushed authorization requests on, and `dpop_signing_alg_values_supported` when it has `dpop` on, …) with these members added
13
+ or stated:
14
+
15
+ | Member | Value |
16
+ | --- | --- |
17
+ | `issuer` | The server's issuer, the one every `iss` carries |
18
+ | `userinfo_endpoint` | `<issuer>/userinfo`, or `paths.userinfo` |
19
+ | `jwks_uri` | From `janus-oauth` |
20
+ | `id_token_signing_alg_values_supported` | The algorithms of the published keys (`['ES256']`, `['EdDSA']`, or both during a switch) |
21
+ | `subject_types_supported` | `['public']` |
22
+ | `response_types_supported` | `['code']` |
23
+ | `scopes_supported` | The scopes of the server's resources |
24
+ | `claims_supported` | The ID Token claims, plus every claim a scope can release (your `scopeClaims` included) |
25
+ | `acr_values_supported` | Your `acrValuesSupported` option; the member is absent when it is unset |
26
+ | `claim_types_supported` | `['normal']` |
27
+ | `claims_parameter_supported`, `request_parameter_supported`, `request_uri_parameter_supported` | `false` |
28
+
29
+ ## Urls
30
+
31
+ `openid.urls.discovery` and `openid.urls.userinfo` are the absolute URLs. The
32
+ document is built on each request from the server's metadata, so it follows a
33
+ key rotation (the algorithms) without a restart.
34
+
35
+ ## It needs a JWKS and the `openid` scope
36
+
37
+ A server with opaque access tokens has no JWKS, and a server none of whose
38
+ resources offers `openid` cannot issue an ID Token. `endpoints()` refuses the
39
+ first at wiring time (`TypeError`); both are an `Error` at request time for
40
+ `issuers()`, whose servers are built on demand.
41
+ See [troubleshooting](../troubleshooting.md).
42
+
43
+ ## Reading it with oauth4webapi
44
+
45
+ ```ts
46
+ const response = await fetch(`${issuer}/.well-known/openid-configuration`);
47
+ const as = await oauth.processDiscoveryResponse(new URL(issuer), response);
48
+ ```
49
+
50
+ `processDiscoveryResponse` checks that the document's `issuer` is the one you
51
+ asked for: the same rule `iss` follows.
@@ -0,0 +1,79 @@
1
+ # Getting started
2
+
3
+ This page turns a working `@softistx/janus-oauth` server into an OpenID
4
+ Provider. It assumes the server issues JWT access tokens; if it does not yet,
5
+ start with [keys](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-oauth/docs/guide/keys.md).
6
+
7
+ ## 1. Signing keys
8
+
9
+ The ID Token is signed with the **current** key of the store that signs your
10
+ access tokens, and verified with the JWKS the OAuth server already serves.
11
+ Rotate once before the first token:
12
+
13
+ ```ts
14
+ import { createMemorySigningKeys, rotateSigningKeys } from '@softistx/janus-oauth';
15
+
16
+ const keys = createMemorySigningKeys(); // production: createMongoSigningKeys(db, { encryptionKey })
17
+ await rotateSigningKeys(keys, { now: new Date(), lead: '1h', retireAfter: '2h' });
18
+ ```
19
+
20
+ Call `rotateSigningKeys` again from a scheduled job. A client that cached the
21
+ JWKS keeps verifying through `lead` and `retireAfter`.
22
+
23
+ ## 2. The provider and the server
24
+
25
+ ```ts
26
+ const oidc = createOidcProvider({ claims });
27
+
28
+ const oauth = createOAuthServer({
29
+ auth, store, issuer,
30
+ resources: { [userinfo]: { scopes: ['openid', 'profile', 'email'] } },
31
+ defaultResource: userinfo,
32
+ accessTokens: { format: 'jwt', keys },
33
+ tokenResponse: oidc.tokenResponse({ issuer, keys }),
34
+ });
35
+ ```
36
+
37
+ - `keys` is **one store**: the one given to `accessTokens.keys` and to `tokenResponse`. The ID Token is signed with it and verified with the JWKS the server publishes from it.
38
+ - `tokenResponse` is the `janus-oauth` hook. It cannot override the standard
39
+ token fields, and it adds nothing unless the granted scopes include `openid`, and nothing on a [token exchange](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-oauth/docs/guide/token-exchange.md#janus-oidc) answer, whatever its scopes (the answer's `scope` can include `openid` and still carry no `id_token`).
40
+ - `defaultResource` lets a client that sends no `resource` (most OpenID
41
+ clients do not) get tokens for the userinfo resource.
42
+ - The resource lists the scopes a client may ask for. `openid` is required.
43
+
44
+ ## 3. The handlers
45
+
46
+ ```ts
47
+ const endpoints = createOAuthEndpoints(oauth, { consentUrl: '/consent' });
48
+ const openid = oidc.endpoints(oauth, endpoints, { resource: userinfo });
49
+ ```
50
+
51
+ `openid.routes` holds three routes (the discovery document and userinfo, GET
52
+ and POST), ready to mount beside `endpoints.routes`. `openid.urls` has the
53
+ absolute URLs the document announces. If your API is a different resource from
54
+ userinfo, add it to `resources` and pass the one userinfo accepts as
55
+ `resource`.
56
+
57
+ ## 4. The consent screen passes the authentication
58
+
59
+ The ID Token states how and when the user signed in. Give `approve` what you
60
+ know:
61
+
62
+ ```ts
63
+ await oauth.approve(authenticated, requestId, {
64
+ amr: ['pwd', 'otp'],
65
+ acr: 'urn:example:mfa',
66
+ });
67
+ ```
68
+
69
+ `authTime` defaults to `session.authenticatedAt` when you pass the
70
+ `Authenticated` that `oauth.consent()` answered. The `nonce` of the request is
71
+ carried for you.
72
+
73
+ ## 5. Try it
74
+
75
+ With `oauth4webapi`: read the discovery document with `processDiscoveryResponse`,
76
+ run the code flow with `nonce` and PKCE, validate with
77
+ `processAuthorizationCodeResponse(…, { expectedNonce, requireIdToken: true })`
78
+ and call `userInfoRequest` with the access token. This package's own specs do
79
+ exactly that.
@@ -0,0 +1,54 @@
1
+ # Several issuers
2
+
3
+ `createOAuthIssuers` serves one OAuth server per tenant, built on demand and
4
+ cached. The OpenID provider follows: each issuer has its **own** hook (its
5
+ keys, its `iss`), its own discovery document and its own JWKS, and a token of
6
+ one issuer is no good at another.
7
+
8
+ ```ts
9
+ const oidc = createOidcProvider({ claims });
10
+
11
+ const issuers = createOAuthIssuers({
12
+ resolve: (request) => tenants.byHost(request.headers.get('host')),
13
+ build: async (tenant) => ({
14
+ auth,
15
+ store: await storeOf(tenant),
16
+ issuer: tenant.issuer,
17
+ resources: { [userinfoOf(tenant)]: { scopes: ['openid', 'profile', 'email'] } },
18
+ defaultResource: userinfoOf(tenant),
19
+ accessTokens: { format: 'jwt', keys: tenant.keys },
20
+ // one hook per issuer: made inside build, with the tenant's keys
21
+ tokenResponse: oidc.tokenResponse({ issuer: tenant.issuer, keys: tenant.keys }),
22
+ }),
23
+ endpoints: { consentUrl: '/consent' }, // required: the provider asks the metadata endpoint
24
+ });
25
+
26
+ const openid = oidc.issuers(issuers, { resource: (issuer) => `${issuer}/userinfo` });
27
+
28
+ app.all('*', async (c) => (await openid.handle(c.req.raw)) ?? issuers.handle(c.req.raw));
29
+ ```
30
+
31
+ ## How a request is routed
32
+
33
+ `openid.handle(request)`:
34
+
35
+ 1. asks the issuers for the request's server (`resolve`, then the cache): no
36
+ issuer is `null`;
37
+ 2. compares the pathname with the two routes **of that issuer** (its discovery
38
+ path and its userinfo path);
39
+ 3. answers the matching handler, or `null`, so the request falls through to
40
+ `issuers.handle`.
41
+
42
+ ## Isolation
43
+
44
+ - The hook closes over the tenant's `keys` and `issuer`: an ID Token of tenant
45
+ A verifies only with A's JWKS and states A's `iss`.
46
+ - The `claims` function is the same for all tenants, and it is given the issuer
47
+ as its third argument: `claims(user, scopes, { issuer })`. Look the user up
48
+ within that issuer's partition, on userinfo and in the ID Token alike.
49
+ - `resource` is a string shared by every issuer, or a function of the issuer.
50
+ - A server built by `build` **without** a hook made by this provider is a
51
+ configuration error, thrown on the first OpenID request to that issuer.
52
+ - `issuers` must have `endpoints` given: the provider reads each issuer's RFC
53
+ 8414 document through `issuers.handle`, so a path or host the application
54
+ customised is followed.
@@ -0,0 +1,32 @@
1
+ # Roadmap
2
+
3
+ Where `@softistx/janus-oidc` is heading. A direction, not a commitment: there
4
+ are no dates here, and the version something shipped in is the only number.
5
+
6
+ ## Now
7
+
8
+ Nothing yet.
9
+
10
+ ## Next
11
+
12
+ - **Refresh tokens tied to `offline_access`** — OIDC Core §11: a refresh token only when the request asked for the `offline_access` scope, on top of the client's `grantTypes`. Today `@softistx/janus-oauth` decides from `grantTypes` alone. [#799](https://github.com/softistx/nxgt-janus/issues/799)
13
+ - **An end-to-end guide** — a walkthrough with a client library, from discovery to userinfo. [#502](https://github.com/softistx/nxgt-janus/issues/502)
14
+
15
+ ## Later
16
+
17
+ Nothing yet.
18
+
19
+ ## Not planned
20
+
21
+ - **Implicit and hybrid flows** (`id_token` or `token` response types). `janus-oauth` is the authorization-code flow with PKCE only.
22
+ - **Request objects and the `claims` request parameter** (`request`, `request_uri`, `claims`). The discovery document says they are not supported.
23
+ - **Pairwise subjects.** `sub` is the user id (`subject_types_supported: ['public']`).
24
+ - **Dynamic client registration of OpenID metadata, logout and session management.** Out of scope for the first version.
25
+ - **Error classes of its own.** A wiring mistake is a `TypeError`; a failure is the underlying error.
26
+
27
+ ## Shipped
28
+
29
+ - **`acr_values_supported`** — `createOidcProvider({ acrValuesSupported })` publishes the ACR values the application can reach in discovery. With `@softistx/janus-oauth`'s authentication hints (`AuthorizationView.acrValues`, `maxAge`, `prompt`, `loginHint`) the application sees what a client asked for and decides what proof to demand; nothing is enforced by the package. [#892](https://github.com/softistx/nxgt-janus/issues/892)
30
+ - **No ID Token on a token exchange** (0.3.23) — with `@softistx/janus-oauth`'s `tokenExchange` on, the `tokenResponse` hook adds no `id_token` to an exchange answer, even when the new token's scopes include `openid`: the exchanging client never saw the user authenticate. [#507](https://github.com/softistx/nxgt-janus/issues/507)
31
+ - **Userinfo accepts DPoP-bound tokens** (0.3.20) — with `@softistx/janus-oauth`'s `dpop` option on, the userinfo endpoint reads `Authorization: DPoP` with its proof and answers the `DPoP` challenges and `DPoP-Nonce`. [#506](https://github.com/softistx/nxgt-janus/issues/506)
32
+ - **The provider package** (0.1.0, the first publish) — `createOidcProvider`: the ID Token (`nonce`, `at_hash`, `auth_time`, `amr`, `acr`), userinfo by scope, the discovery document, for one issuer or several. [#502](https://github.com/softistx/nxgt-janus/issues/502), [#557](https://github.com/softistx/nxgt-janus/issues/557), [#558](https://github.com/softistx/nxgt-janus/issues/558)
@@ -0,0 +1,112 @@
1
+ # Troubleshooting `@softistx/janus-oidc`
2
+
3
+ Installing `@softistx/janus*` fails with a 401 or 404? See
4
+ [the install entry](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#installing-softistx-packages).
5
+
6
+ Each entry is headed by the text you see. A wiring mistake is a `TypeError`,
7
+ thrown when the provider or its handlers are made. This package defines no error
8
+ class of its own.
9
+
10
+ ## Index
11
+
12
+ - [`claims` finds the wrong user, or none, with several issuers](#claims-finds-the-wrong-user-or-none-with-several-issuers)
13
+ - [`createOidcProvider: claims must be a function`](#createoidcprovider-claims-must-be-a-function)
14
+ - [`createOidcProvider: scopeClaims.<scope> must be a list of claim names`](#createoidcprovider-scopeclaimsscope-must-be-a-list-of-claim-names)
15
+ - [`createOidcProvider: acrValuesSupported must be a list of non-empty values without spaces`](#createoidcprovider-acrvaluessupported-must-be-a-list-of-non-empty-values-without-spaces)
16
+ - [`idToken.lifetime: "…" is not a duration; write a number followed by ms, s, m, h or d`](#idtokenlifetime-soon-is-not-a-duration-write-a-number-followed-by-ms-s-m-h-or-d-)
17
+ - [`createOidcProvider: paths.userinfo …`](#createoidcprovider-pathsuserinfo-)
18
+ - [`createOidcProvider: keys: …`](#createoidcprovider-keys-)
19
+ - [`createOidcProvider: no tokenResponse hook was made for this server's issuer`](#createoidcprovider-no-tokenresponse-hook-was-made-for-this-servers-issuer)
20
+ - [`createOidcProvider: the provider was wired for another issuer than the OAuth server's`](#createoidcprovider-the-provider-was-wired-for-another-issuer-than-the-oauth-servers-the-id_token-would-carry-the-wrong-iss)
21
+ - [`createOidcProvider: the server has no JWKS`](#createoidcprovider-the-server-has-no-jwks)
22
+ - [`createOidcProvider: no resource of the server offers the 'openid' scope`](#createoidcprovider-no-resource-of-the-server-offers-the-openid-scope)
23
+ - [`createOidcProvider: no current signing key`](#createoidcprovider-no-current-signing-key)
24
+ - [`createOidcProvider: the OAuth metadata endpoint answered <status>`](#createoidcprovider-the-oauth-metadata-endpoint-answered-status)
25
+ - [Userinfo answers 401, 403 or 405](#userinfo-answers-401-403-or-405)
26
+ - [A client says the ID Token's `iss` or signature is wrong](#a-client-says-the-id-tokens-iss-or-signature-is-wrong)
27
+
28
+ ---
29
+
30
+ ### `createOidcProvider: claims must be a function`
31
+
32
+ **When:** `claims` is missing or is not a function. **Fix:** `claims: async ({ id }) => ({ … })`.
33
+
34
+ ### `createOidcProvider: scopeClaims.<scope> must be a list of claim names`
35
+
36
+ **When:** a scope in `scopeClaims` maps to a string, not an array. **Fix:** `{ roles: ['roles'] }`.
37
+
38
+ ### `createOidcProvider: acrValuesSupported must be a list of non-empty values without spaces`
39
+
40
+ **When:** `acrValuesSupported` is a string, or an entry is empty or holds a space (`acr_values` is space-delimited, so an entry cannot). **Fix:** `acrValuesSupported: ['urn:example:pwd', 'urn:example:mfa']`.
41
+
42
+ ### `idToken.lifetime: "soon" is not a duration; write a number followed by ms, s, m, h or d …`
43
+
44
+ **When:** `idToken.lifetime` is not a duration `@softistx/janus` reads (the message names your value). **Fix:** `'10m'`, `'1h'`, or milliseconds as a number.
45
+
46
+ ### `createOidcProvider: paths.userinfo …`
47
+
48
+ **Messages:** `is not a path` (it starts with `//` or holds `#`), `is not a path or an absolute URL`, `must be an https: URL without a fragment (http: only for localhost)`.
49
+
50
+ **Fix:** a path from the origin (`/oidc/me`) or an absolute `https:` URL.
51
+
52
+ ### `createOidcProvider: keys: …`
53
+
54
+ **When:** `tokenResponse({ issuer, keys })` was given something that is not a `SigningKeyStore` (`pass a SigningKeyStore`, `the store has no <method>() method`). **Fix:** pass the store you give `accessTokens.keys`, not its JWKS. A custom store must implement `findCurrentKey(now)`; see `@softistx/janus-oauth`'s keys guide.
55
+
56
+ ### `createOidcProvider: no tokenResponse hook was made for this server's issuer`
57
+
58
+ **When:** `endpoints(oauth, …)` (a `TypeError`, at wiring) or a request through `issuers()` (an `Error`, at request time) meets a server whose issuer no `provider.tokenResponse({ issuer, keys })` was called for. **Why:** that server issues no ID Token, so a discovery document for it would lie.
59
+
60
+ **Fix:** build the server's options with `tokenResponse: oidc.tokenResponse({ issuer, keys })`, from the same provider, and the same `issuer` string. With several issuers, call it inside `build`.
61
+
62
+ ### `createOidcProvider: the provider was wired for another issuer than the OAuth server's; the id_token would carry the wrong iss`
63
+
64
+ **When:** a token request (a `TypeError`, at issuing time) on a server whose `issuer` differs from the one given to `provider.tokenResponse({ issuer, keys })`. No token is stored.
65
+
66
+ **Why:** the ID Token's `iss` would not be the issuer of the discovery document.
67
+
68
+ **Fix:** pass the server's own `issuer` string to `tokenResponse`; with several issuers, call it inside `build` with that issuer.
69
+
70
+ ### `createOidcProvider: the server has no JWKS`
71
+
72
+ **When:** the server issues opaque access tokens. **Fix:** `accessTokens: { format: 'jwt', keys }`. At request time (through `issuers()`) the message continues "…and has no JWKS: give createOAuthServer accessTokens…" as an `Error`.
73
+
74
+ ### `createOidcProvider: no resource of the server offers the 'openid' scope`
75
+
76
+ **When:** the discovery document is asked of a server none of whose resources lists `openid`. **Fix:** add `openid` (and `profile`, `email`, …) to a resource's `scopes`.
77
+
78
+ ### `createOidcProvider: no current signing key`
79
+
80
+ **When:** a token response includes `openid` but the signing-key store has no `current` key. The error is a `NoSigningKeyError` from `@softistx/janus-oauth`, an `OAuthError` of code `temporarily_unavailable` and `status` 503: the token endpoint answers `503 { "error": "temporarily_unavailable" }`, the code is not spent and the client can retry. The server's fault, not the client's. **Fix:** run `rotateSigningKeys` at startup and from a schedule.
81
+
82
+ ### `createOidcProvider: the OAuth metadata endpoint answered <status>`
83
+
84
+ **When:** the discovery document merges `janus-oauth`'s metadata, and its handler did not answer 200. **Why:** typically `issuers()` was given a `createOAuthIssuers` whose `resolve` answers nothing for the rewritten path, or the endpoints' host is not the issuer's. **Fix:** check the issuer's `resolve` for `/.well-known/oauth-authorization-server`.
85
+
86
+ ### Userinfo answers 401, 403 or 405
87
+
88
+ | Status | `WWW-Authenticate` | Cause |
89
+ | --- | --- | --- |
90
+ | 401 | `Bearer realm="userinfo"` | No bearer token was sent |
91
+ | 401 | `…, error="invalid_token"` | Unknown, lapsed or revoked token, token for another resource, deactivated user |
92
+ | 403 | `…, error="insufficient_scope", scope="openid"` | The token was granted without `openid` |
93
+ | 401 | `DPoP realm="userinfo", error="invalid_token", algs="…"` | A DPoP-bound token sent as `Authorization: Bearer`, or an unbound one sent as `DPoP` |
94
+ | 401 | `DPoP realm="userinfo", error="invalid_dpop_proof", error_description="…", algs="…"` | A DPoP-bound token with a missing, malformed, replayed or wrong-request proof (`htm`, `htu`, `ath`), or a proof of another key. The description, also in the JSON body, names the failed check (e.g. `ath does not match the access token`) |
95
+ | 401 | `DPoP realm="userinfo", error="use_dpop_nonce", algs="…"` and a `DPoP-Nonce` header | The OAuth server uses nonces: sign a new proof that carries it |
96
+ | 405 | | A method other than GET and POST |
97
+
98
+ For a 401 with a valid token, check that the token's resource is the `resource` given to `endpoints()`. For a DPoP 401, the proof's `htu` must be the URL userinfo is reached at: behind a proxy the internal URL never matches, so rebuild the `Request` with the public one. The reasons are in the [DPoP guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-oauth/docs/guide/dpop.md#what-a-proof-is-checked-for).
99
+
100
+ ### A client says the ID Token's `iss` or signature is wrong
101
+
102
+ - `iss` is the `issuer` passed to `tokenResponse`; the discovery document's `issuer` is the server's. They must be the same string, trailing slash included.
103
+ - The signature verifies with the JWKS at `jwks_uri` (the `kid` in the header). A client with a stale JWKS fails after a rotation: it should refetch on an unknown `kid`; keep `lead` at least as long as its cache.
104
+
105
+ ### `claims` finds the wrong user, or none, with several issuers
106
+
107
+ **When:** users live in one pool per issuer (`issuers()`) and `claims` looks the
108
+ id up in a single one. **Why:** the same id or e-mail can exist in two
109
+ partitions, and `claims` cannot tell which tenant the request is for from the
110
+ user alone. **Fix:** read the third argument,
111
+ `claims: async ({ id }, scopes, { issuer }) => …`, and look the user up within
112
+ that issuer.
package/package.json CHANGED
@@ -1,6 +1,68 @@
1
1
  {
2
- "name": "@softistx/janus-oidc",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@softistx/janus-oidc",
3
+ "version": "0.4.5",
4
+ "description": "An OpenID Connect provider on top of @softistx/janus-oauth: ID Tokens signed with the server's signing keys, the userinfo endpoint and the discovery document, for one issuer or several",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "files": [
10
+ "dist",
11
+ "docs",
12
+ "README.md",
13
+ "package.json",
14
+ "LICENSE"
15
+ ],
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js",
20
+ "default": "./dist/index.js"
21
+ },
22
+ "./package.json": "./package.json"
23
+ },
24
+ "keywords": [
25
+ "identity",
26
+ "openid-connect",
27
+ "oidc",
28
+ "id-token",
29
+ "oauth",
30
+ "janus",
31
+ "typescript"
32
+ ],
33
+ "repository": {
34
+ "type": "git",
35
+ "url": "git+https://github.com/softistx/nxgt-janus.git",
36
+ "directory": "packages/janus-oidc"
37
+ },
38
+ "publishConfig": {
39
+ "registry": "https://registry.npmjs.org/",
40
+ "access": "public"
41
+ },
42
+ "scripts": {
43
+ "build": "bun run ../../build.ts",
44
+ "test": "bun test src",
45
+ "typecheck": "bun check",
46
+ "typecheck:tsc": "tsc --noEmit"
47
+ },
48
+ "nxgt": {
49
+ "entrypoints": [
50
+ "src/index.ts"
51
+ ]
52
+ },
53
+ "devDependencies": {
54
+ "@softistx/janus": "^0.73.1",
55
+ "@softistx/janus-oauth": "^0.23.6",
56
+ "@types/bun": "^1.4.4",
57
+ "oauth4webapi": "^3.8.8",
58
+ "zod": "^4.6.7"
59
+ },
60
+ "peerDependencies": {
61
+ "@softistx/janus": "^0.73.1",
62
+ "@softistx/janus-oauth": "^0.23.6",
63
+ "typescript": "^6.0.3 || ^7.0.0"
64
+ },
65
+ "dependencies": {
66
+ "jose": "^6.2.18"
67
+ }
68
+ }