@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.
- package/LICENSE +21 -0
- package/README.md +175 -2
- package/dist/claims/scopes.d.ts +15 -0
- package/dist/claims/scopes.d.ts.map +1 -0
- package/dist/claims/types.d.ts +36 -0
- package/dist/claims/types.d.ts.map +1 -0
- package/dist/create.d.ts +19 -0
- package/dist/create.d.ts.map +1 -0
- package/dist/http/discovery.d.ts +13 -0
- package/dist/http/discovery.d.ts.map +1 -0
- package/dist/http/handlers.d.ts +16 -0
- package/dist/http/handlers.d.ts.map +1 -0
- package/dist/http/respond.d.ts +8 -0
- package/dist/http/respond.d.ts.map +1 -0
- package/dist/http/source.d.ts +13 -0
- package/dist/http/source.d.ts.map +1 -0
- package/dist/http/urls.d.ts +7 -0
- package/dist/http/urls.d.ts.map +1 -0
- package/dist/http/userinfo.d.ts +15 -0
- package/dist/http/userinfo.d.ts.map +1 -0
- package/dist/id-token/at-hash.d.ts +4 -0
- package/dist/id-token/at-hash.d.ts.map +1 -0
- package/dist/id-token/hook.d.ts +15 -0
- package/dist/id-token/hook.d.ts.map +1 -0
- package/dist/id-token/sign.d.ts +16 -0
- package/dist/id-token/sign.d.ts.map +1 -0
- package/dist/index.d.ts +15 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +423 -0
- package/dist/index.js.map +20 -0
- package/dist/types.d.ts +99 -0
- package/dist/types.d.ts.map +1 -0
- package/docs/README.md +18 -0
- package/docs/guide/claims.md +92 -0
- package/docs/guide/discovery.md +51 -0
- package/docs/guide/getting-started.md +79 -0
- package/docs/guide/issuers.md +54 -0
- package/docs/roadmap.md +32 -0
- package/docs/troubleshooting.md +112 -0
- 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.
|
package/docs/roadmap.md
ADDED
|
@@ -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
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
+
}
|