@softistx/janus-social 0.0.0-stage → 0.7.0
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 +356 -2
- package/dist/authorization-url.d.ts +21 -0
- package/dist/authorization-url.d.ts.map +1 -0
- package/dist/check-options.d.ts +22 -0
- package/dist/check-options.d.ts.map +1 -0
- package/dist/claims.d.ts +15 -0
- package/dist/claims.d.ts.map +1 -0
- package/dist/code-exchange.d.ts +79 -0
- package/dist/code-exchange.d.ts.map +1 -0
- package/dist/connections/abort.d.ts +8 -0
- package/dist/connections/abort.d.ts.map +1 -0
- package/dist/connections/at-hash.d.ts +24 -0
- package/dist/connections/at-hash.d.ts.map +1 -0
- package/dist/connections/body-limit.d.ts +15 -0
- package/dist/connections/body-limit.d.ts.map +1 -0
- package/dist/connections/build.d.ts +7 -0
- package/dist/connections/build.d.ts.map +1 -0
- package/dist/connections/check.d.ts +25 -0
- package/dist/connections/check.d.ts.map +1 -0
- package/dist/connections/claims.d.ts +16 -0
- package/dist/connections/claims.d.ts.map +1 -0
- package/dist/connections/discovery.d.ts +20 -0
- package/dist/connections/discovery.d.ts.map +1 -0
- package/dist/connections/domain.d.ts +15 -0
- package/dist/connections/domain.d.ts.map +1 -0
- package/dist/connections/guarded-fetch.d.ts +49 -0
- package/dist/connections/guarded-fetch.d.ts.map +1 -0
- package/dist/connections/id-token-steps.d.ts +15 -0
- package/dist/connections/id-token-steps.d.ts.map +1 -0
- package/dist/connections/id-token.d.ts +63 -0
- package/dist/connections/id-token.d.ts.map +1 -0
- package/dist/connections/index.d.ts +10 -0
- package/dist/connections/index.d.ts.map +1 -0
- package/dist/connections/ip.d.ts +14 -0
- package/dist/connections/ip.d.ts.map +1 -0
- package/dist/connections/issuer-cache.d.ts +40 -0
- package/dist/connections/issuer-cache.d.ts.map +1 -0
- package/dist/connections/issuer.d.ts +4 -0
- package/dist/connections/issuer.d.ts.map +1 -0
- package/dist/connections/key-flights.d.ts +16 -0
- package/dist/connections/key-flights.d.ts.map +1 -0
- package/dist/connections/memory.d.ts +10 -0
- package/dist/connections/memory.d.ts.map +1 -0
- package/dist/connections/oidc-connections.d.ts +63 -0
- package/dist/connections/oidc-connections.d.ts.map +1 -0
- package/dist/connections/provider.d.ts +25 -0
- package/dist/connections/provider.d.ts.map +1 -0
- package/dist/connections/server.d.ts +55 -0
- package/dist/connections/server.d.ts.map +1 -0
- package/dist/connections/types.d.ts +87 -0
- package/dist/connections/types.d.ts.map +1 -0
- package/dist/connections/url-policy.d.ts +30 -0
- package/dist/connections/url-policy.d.ts.map +1 -0
- package/dist/connections/wiring.d.ts +5 -0
- package/dist/connections/wiring.d.ts.map +1 -0
- package/dist/discovery.d.ts +11 -0
- package/dist/discovery.d.ts.map +1 -0
- package/dist/dpop.d.ts +18 -0
- package/dist/dpop.d.ts.map +1 -0
- package/dist/failure.d.ts +14 -0
- package/dist/failure.d.ts.map +1 -0
- package/dist/github-identity.d.ts +11 -0
- package/dist/github-identity.d.ts.map +1 -0
- package/dist/github.d.ts +11 -0
- package/dist/github.d.ts.map +1 -0
- package/dist/google.d.ts +11 -0
- package/dist/google.d.ts.map +1 -0
- package/dist/guard-error.d.ts +14 -0
- package/dist/guard-error.d.ts.map +1 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1821 -0
- package/dist/index.js.map +51 -0
- package/dist/microsoft-tenant.d.ts +32 -0
- package/dist/microsoft-tenant.d.ts.map +1 -0
- package/dist/microsoft.d.ts +16 -0
- package/dist/microsoft.d.ts.map +1 -0
- package/dist/oauth2.d.ts +13 -0
- package/dist/oauth2.d.ts.map +1 -0
- package/dist/oidc-engine.d.ts +62 -0
- package/dist/oidc-engine.d.ts.map +1 -0
- package/dist/oidc-step-up.d.ts +15 -0
- package/dist/oidc-step-up.d.ts.map +1 -0
- package/dist/oidc.d.ts +11 -0
- package/dist/oidc.d.ts.map +1 -0
- package/dist/options.d.ts +108 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/pushed-authorization.d.ts +23 -0
- package/dist/pushed-authorization.d.ts.map +1 -0
- package/dist/step-up.d.ts +50 -0
- package/dist/step-up.d.ts.map +1 -0
- package/dist/transport.d.ts +18 -0
- package/dist/transport.d.ts.map +1 -0
- package/docs/README.md +35 -0
- package/docs/guide/custom-providers.md +182 -0
- package/docs/guide/github.md +109 -0
- package/docs/guide/google.md +103 -0
- package/docs/guide/microsoft.md +158 -0
- package/docs/guide/oidc-connections.md +255 -0
- package/docs/guide/oidc-step-up.md +122 -0
- package/docs/guide/par-dpop.md +63 -0
- package/docs/roadmap.md +33 -0
- package/docs/troubleshooting.md +632 -0
- package/package.json +67 -5
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# OIDC with step-up
|
|
2
|
+
|
|
3
|
+
This page is for signing in with an OpenID Connect tenant that enforces a step-up: the wiring, what identity you
|
|
4
|
+
get, and how to require a level of assurance or a recent authentication.
|
|
5
|
+
|
|
6
|
+
```ts
|
|
7
|
+
import { oidcStepUp } from '@softistx/janus-social';
|
|
8
|
+
|
|
9
|
+
export const provider = oidcStepUp({
|
|
10
|
+
issuer: 'https://login.example.com', // yours: your OpenID Connect tenant's issuer
|
|
11
|
+
clientId: process.env.OIDC_CLIENT_ID!, // yours: from the client you registered
|
|
12
|
+
clientSecret: process.env.OIDC_CLIENT_SECRET!, // yours
|
|
13
|
+
redirectUri: 'https://app.example.com/auth/oidc/callback', // yours: the route that calls social.complete
|
|
14
|
+
});
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Put it under `social.providers` of your user type (`providers: { oidcStepUp: provider }`)
|
|
18
|
+
as in the [README](../../README.md). Register `redirectUri` with the tenant
|
|
19
|
+
byte for byte (scheme, case, trailing slash).
|
|
20
|
+
|
|
21
|
+
## Options
|
|
22
|
+
|
|
23
|
+
| Option | Type | Default | Effect |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `issuer` | `string` | required | The tenant's issuer, `https` only |
|
|
26
|
+
| `clientId` | `string` | required | The client's id |
|
|
27
|
+
| `clientSecret` | `string` | required | Its secret |
|
|
28
|
+
| `redirectUri` | `string` | required | `https`, or `http` on a loopback host; registered exactly |
|
|
29
|
+
| `acrValues` | `string[]` | absent | Non-empty. Asked for, and the ID token's `acr` must be one of them |
|
|
30
|
+
| `maxAge` | `number` | absent | Non-negative integer seconds. Asked for, and the ID token's `auth_time` must be no older |
|
|
31
|
+
| `fetch` | `SocialFetch` | global `fetch` | Used for every request to the tenant |
|
|
32
|
+
| `timeout` | `number` | `10000` | Milliseconds each request may take |
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
interface OidcStepUpOptions extends ProviderCredentials {
|
|
36
|
+
readonly issuer: string;
|
|
37
|
+
readonly acrValues?: readonly string[];
|
|
38
|
+
readonly maxAge?: number;
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## The identity
|
|
43
|
+
|
|
44
|
+
| Field | From |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| `accountId` | the ID token's `sub` |
|
|
47
|
+
| `email` | the `email` claim, or `null` when absent |
|
|
48
|
+
| `emailVerified` | `email_verified` is `true` (a boolean or the string `"true"`) |
|
|
49
|
+
| `name`, `picture` | the `name` and `picture` claims, when present |
|
|
50
|
+
|
|
51
|
+
The scopes asked for are `openid email profile`. The tenant is read through
|
|
52
|
+
OpenID Connect: its discovery document is fetched on first use and kept (a
|
|
53
|
+
failure is not kept). The ID token's `iss`, `aud`, `exp` and `nonce` are checked.
|
|
54
|
+
|
|
55
|
+
## Step-up
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
import { oidcStepUp } from '@softistx/janus-social';
|
|
59
|
+
|
|
60
|
+
export const strong = oidcStepUp({
|
|
61
|
+
issuer: 'https://login.example.com', // yours
|
|
62
|
+
clientId: process.env.OIDC_CLIENT_ID!,
|
|
63
|
+
clientSecret: process.env.OIDC_CLIENT_SECRET!,
|
|
64
|
+
redirectUri: 'https://app.example.com/auth/oidc/callback',
|
|
65
|
+
acrValues: ['urn:example:mfa'], // yours: the values your tenant defines
|
|
66
|
+
maxAge: 300, // the visitor authenticated within the last 5 minutes
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`acrValues` adds `acr_values=urn:example:mfa` (several values are space-joined)
|
|
71
|
+
and `maxAge` adds `max_age=300` to the authorization URL. Those parameters are
|
|
72
|
+
hints the visitor can edit, so the ID token is what is trusted. The sign-in is
|
|
73
|
+
refused with `SOCIAL_STEP_UP_UNMET` (403) when:
|
|
74
|
+
|
|
75
|
+
- `acrValues` is set and the token's `acr` is missing or not one of the values;
|
|
76
|
+
- `maxAge` is set and `auth_time` is missing, not a number, or older than
|
|
77
|
+
`maxAge` seconds plus 60 s before the server's clock at the exchange, or more
|
|
78
|
+
than 60 s in the future (the tolerance for clock skew, in both directions,
|
|
79
|
+
compared in milliseconds: `maxAge: 0` means roughly the last minute).
|
|
80
|
+
|
|
81
|
+
Before 0.5.0 this refusal was `PROVIDER_ERROR` with `reason: 'refused'`; code that caught that for a failed
|
|
82
|
+
step-up catches `SOCIAL_STEP_UP_UNMET` now.
|
|
83
|
+
|
|
84
|
+
## One sign-in at a time
|
|
85
|
+
|
|
86
|
+
The fixed step-up above applies to every sign-in through that provider. To ask for more on **one**
|
|
87
|
+
sign-in (a sensitive action, a recent re-authentication), pass `stepUp` to `social.start` or
|
|
88
|
+
`social.link` (see the [core guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md)):
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
const start = await auth.social.start({
|
|
92
|
+
provider: 'oidcStepUp',
|
|
93
|
+
stepUp: { acrValues: ['urn:example:mfa'], maxAge: 300 }, // yours: the values your tenant defines
|
|
94
|
+
});
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`oidcStepUp` and `oidcProvider` both support it (`supportsStepUp: true`): they send the request as
|
|
98
|
+
`acr_values` and `max_age` (inside the pushed request too, when PAR is on), and report the ID token's
|
|
99
|
+
`acr` and `auth_time` so the core can check them. **The core does the checking**, on its own clock, and
|
|
100
|
+
answers `SOCIAL_STEP_UP_UNMET` when the proof is missing.
|
|
101
|
+
|
|
102
|
+
With `oidcStepUp`'s fixed values **both hold**: the URL sends the `acr_values` the fixed list and the
|
|
103
|
+
request share (in the request's order) and the smaller `max_age`. When they share no value, `start`
|
|
104
|
+
fails (a `PROVIDER_ERROR` with `reason: 'refused'`, never naming the values) rather than send a request
|
|
105
|
+
nothing could satisfy. A request weaker than the fixed values is never sent alone.
|
|
106
|
+
|
|
107
|
+
`google()` and `microsoft()` do **not** support it (`supportsStepUp: false`): neither honours
|
|
108
|
+
`acr_values` (Google ignores it; Microsoft answers its own `acrs` values), so `start` refuses
|
|
109
|
+
a step-up flow with a `TypeError` before any token. `github()` and `oauth2Provider()` do not either.
|
|
110
|
+
|
|
111
|
+
## Traps
|
|
112
|
+
|
|
113
|
+
- The tenant must return `acr` and `auth_time` in the ID token. When it does
|
|
114
|
+
not, every sign-in that asks for them is refused (`SOCIAL_STEP_UP_UNMET`): drop the option, or configure the tenant.
|
|
115
|
+
- `acr_values` is only a request: a tenant may ignore it and sign the visitor in
|
|
116
|
+
anyway, which is why the ID token's `acr` is checked and a missing one is a refusal.
|
|
117
|
+
- An empty `acrValues`, or a `maxAge` that is negative or fractional, is a
|
|
118
|
+
`TypeError` at wiring; so is an `issuer` that is not `https`.
|
|
119
|
+
- An account is one link per instance, like any provider: see the
|
|
120
|
+
[core guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md).
|
|
121
|
+
|
|
122
|
+
More in [troubleshooting](../troubleshooting.md).
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Servers that require PAR or DPoP
|
|
2
|
+
|
|
3
|
+
This page is for signing in with an OpenID Connect server that wants the authorization request pushed
|
|
4
|
+
(RFC 9126), or the tokens bound to a key (DPoP, RFC 9449). Both are options of `oidcProvider` and
|
|
5
|
+
`oidcStepUp`. Google, Microsoft, GitHub and `oauth2Provider` take no option; Google and
|
|
6
|
+
Microsoft still push when their discovery says the server requires it.
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import { oidcProvider } from '@softistx/janus-social';
|
|
10
|
+
|
|
11
|
+
export const provider = oidcProvider({
|
|
12
|
+
issuer: 'https://login.example.com', // yours
|
|
13
|
+
clientId: process.env.OIDC_CLIENT_ID!, // yours
|
|
14
|
+
clientSecret: process.env.OIDC_CLIENT_SECRET!, // yours
|
|
15
|
+
redirectUri: 'https://app.example.com/auth/oidc/callback', // yours
|
|
16
|
+
pushedAuthorization: 'auto', // the default: push when the server requires it
|
|
17
|
+
dpop: true, // opt in: ES256 proofs on the token request
|
|
18
|
+
});
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Pushed authorization requests
|
|
22
|
+
|
|
23
|
+
A server that sets `require_pushed_authorization_requests: true` in its discovery refuses an authorization
|
|
24
|
+
URL that carries the parameters: the sign-in fails at its page with `invalid_request`. With
|
|
25
|
+
`pushedAuthorization: 'auto'` (the default) the package sees that flag and pushes instead.
|
|
26
|
+
|
|
27
|
+
| Value | Pushes when | Fails with `PROVIDER_ERROR` when |
|
|
28
|
+
| --- | --- | --- |
|
|
29
|
+
| `'auto'` (default) | discovery says `require_pushed_authorization_requests: true` | it does, and discovery lists no `pushed_authorization_request_endpoint` |
|
|
30
|
+
| `'always'` | the server lists a `pushed_authorization_request_endpoint`, required or not | it lists none |
|
|
31
|
+
|
|
32
|
+
What is pushed: every parameter the URL carries otherwise (PKCE challenge, `state`, `nonce`, the scopes, a
|
|
33
|
+
step-up's `acr_values` and `max_age`), authenticated with the client secret the way the token request is
|
|
34
|
+
(`client_secret_post`, or basic when the server does not list post). The visitor is then sent to the
|
|
35
|
+
authorization endpoint (its own query, if it has one, is kept and not pushed) with only `client_id` and
|
|
36
|
+
the `request_uri` the server answered. A refusal, or an
|
|
37
|
+
answer without a `request_uri`, is a `PROVIDER_ERROR` at the step "the pushed authorization request";
|
|
38
|
+
the message carries no parameter and no secret.
|
|
39
|
+
|
|
40
|
+
## DPoP
|
|
41
|
+
|
|
42
|
+
With `dpop: true` (ES256) or `dpop: { algorithm: 'EdDSA' }`, the token request carries a `DPoP` proof
|
|
43
|
+
(`typ: dpop+jwt`, the public key as `jwk`, `htm: POST`, `htu` the token endpoint) signed by a fresh,
|
|
44
|
+
non-extractable key pair made for that exchange. The tokens are used once, to read the ID token, so no
|
|
45
|
+
key is kept.
|
|
46
|
+
|
|
47
|
+
`EdDSA` makes an Ed25519 key, and the proof's `alg` header then reads `Ed25519`. A server whose
|
|
48
|
+
`dpop_signing_alg_values_supported` lists only `EdDSA` will refuse that proof; use `ES256` there. A
|
|
49
|
+
runtime without Ed25519 throws a `TypeError` naming the algorithm.
|
|
50
|
+
|
|
51
|
+
A server that answers a DPoP request with a Bearer token is refused, not accepted: the tokens would not be
|
|
52
|
+
bound to the key.
|
|
53
|
+
|
|
54
|
+
When the token endpoint answers `use_dpop_nonce`, the request is sent once more with the server's nonce. A
|
|
55
|
+
second refusal is a `PROVIDER_ERROR` at the step "the token response". The nonce is not kept across
|
|
56
|
+
sign-ins, so a server that requires a nonce costs one extra token round trip per sign-in. Without `dpop`
|
|
57
|
+
there is no retry.
|
|
58
|
+
|
|
59
|
+
Not covered, on purpose: `dpop_jkt` at the authorization request (the key does not exist yet), and refresh
|
|
60
|
+
(janus-social redeems one code per sign-in and never refreshes).
|
|
61
|
+
|
|
62
|
+
See the [troubleshooting entries](../troubleshooting.md) for the errors, and the
|
|
63
|
+
[roadmap](../roadmap.md) for key persistence.
|
package/docs/roadmap.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Roadmap
|
|
2
|
+
|
|
3
|
+
Where `@softistx/janus-social` 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 is in flight.
|
|
9
|
+
|
|
10
|
+
## Next
|
|
11
|
+
|
|
12
|
+
- **GitHub Enterprise Server** — a base URL option on `github()`, for GitHub on your own domain.
|
|
13
|
+
- **A userinfo fallback** — read the account from the userinfo endpoint when the ID token carries no `email`, for providers that keep claims there: `oidcProvider`, and an opt-in field on an OIDC connection record, added when the fallback exists. The `sub` must match the ID token's.
|
|
14
|
+
- **Per-connection Google Workspace check (`hd`)** — a record rule that requires the `hd` claim, so a personal Google account on your domain no longer passes as verified.
|
|
15
|
+
|
|
16
|
+
## Later
|
|
17
|
+
|
|
18
|
+
- **Apple** — Sign in with Apple: the `form_post` callback and the client secret that is a signed JWT.
|
|
19
|
+
- **Provider tokens** — keep and refresh the provider's access token, to call the provider's API on the user's behalf. Today the access token is used once, to read the account, and dropped. DPoP would then keep its key too, and send `dpop_jkt` at the authorization request.
|
|
20
|
+
|
|
21
|
+
## Not planned
|
|
22
|
+
|
|
23
|
+
- **Verifying the ID token's signature for the presets' direct exchange** — the code goes to the token endpoint over TLS and OpenID Connect Core 3.1.3.7 lets the client trust that answer; oauth4webapi does not verify it either. `iss`, `aud`, `exp` and `nonce` are checked. This still holds for the presets and `oidcProvider`; **OIDC connections verify the signature**, always, with asymmetric algorithms only.
|
|
24
|
+
- **An option to allow insecure requests** — endpoints carry secrets; `https` only (a loopback `http` redirect URI excepted).
|
|
25
|
+
|
|
26
|
+
## Shipped
|
|
27
|
+
|
|
28
|
+
- **The deprecated step-up alias is removed.** The old alias of `oidcStepUp()` and its options type are gone; use `oidcStepUp` and `OidcStepUpOptions`.
|
|
29
|
+
- **OIDC connections at runtime, v0.6.0.** `oidcConnections({ source, redirectUri })` turns identity providers stored in your database into providers for `social.resolveProvider`: add, edit or drop a tenant's OpenID Connect connection with no restart. The ID token's signature is verified; the e-mail is trusted by `emailTrust` (`'claimAndDomain'` by default) against the connection's verified `domains`; claim names are mapped per record; `forEmail` finds a company's sign-in from an e-mail address; `checkConnection` validates a record on your write path; every URL a tenant names goes through an https-only, public-address policy; discovery and signing keys are cached per issuer. `createMemoryConnections` is a reference source for specs. Needs `@softistx/janus` with `social.resolveProvider`. [#509](https://github.com/softistx/nxgt-janus/issues/509)
|
|
30
|
+
- **The first release, v0.1.0.** `google()`, `github()` and `microsoft()`; `oidcProvider()` for any OpenID Connect provider and `oauth2Provider()` for a plain OAuth 2.0 one; PKCE `S256`, `state` and `nonce`; Google `hostedDomain`; Microsoft tenants and the `xms_edov` e-mail rule; `PROVIDER_ERROR` with a `reason` for logs.
|
|
31
|
+
- **`oidcStepUp()`, v0.2.0.** A preset for an OpenID Connect tenant, by its `issuer`, with an optional fixed step-up: `acrValues` and `maxAge` are sent as `acr_values` and `max_age`, and the sign-in is refused unless the ID token's `acr` and `auth_time` prove them.
|
|
32
|
+
- **Pushed authorization requests and DPoP for OpenID Connect providers.** `oidcProvider()` and `oidcStepUp()` take `pushedAuthorization` (`'auto'` pushes when the server requires it, `'always'`) and `dpop` (`true` or `{ algorithm }`): the request is pushed to the server's endpoint, and the token request carries a DPoP proof with a single nonce retry. [#856](https://github.com/softistx/nxgt-janus/issues/856)
|
|
33
|
+
- **Step-up per request, v0.5.0.** `social.start` / `social.link` take `stepUp` (`acr_values`, `max_age`): `oidcProvider` and `oidcStepUp` send it (PAR included) and report the ID token's `acr` and `auth_time`, the core checks them; `google` and `microsoft` do not support it. `oidcStepUp`'s fixed-value refusal is now `SOCIAL_STEP_UP_UNMET`, with the core's 60 s tolerance both ways. [#643](https://github.com/softistx/nxgt-janus/issues/643)
|