@softistx/janus-social 0.0.0-stage → 0.8.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 +11 -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 +71 -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 +1825 -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 +265 -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,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What `oidcProvider`, Google and Microsoft share: an OpenID Connect
|
|
3
|
+
* `SocialProvider` that differs from the next only in where its server comes
|
|
4
|
+
* from and how its claims read.
|
|
5
|
+
*/
|
|
6
|
+
import type { SocialIdentity, SocialProvider } from '@softistx/janus';
|
|
7
|
+
import type * as oauth from 'oauth4webapi';
|
|
8
|
+
import { type IdTokenSteps } from './code-exchange';
|
|
9
|
+
import type { OidcSecurityOptions, ProviderCredentials } from './options';
|
|
10
|
+
import { type FixedStepUp } from './step-up';
|
|
11
|
+
import { transport } from './transport';
|
|
12
|
+
/**
|
|
13
|
+
* What one exchange or authorization URL runs against: the server, the
|
|
14
|
+
* transport to reach it and, for an upstream connection, the ID token steps.
|
|
15
|
+
*/
|
|
16
|
+
export interface EngineSession {
|
|
17
|
+
readonly server: oauth.AuthorizationServer;
|
|
18
|
+
readonly http: ReturnType<typeof transport>;
|
|
19
|
+
/** Set for a connection: the signature check is then mandatory. Absent for the presets. */
|
|
20
|
+
readonly idToken?: IdTokenSteps;
|
|
21
|
+
}
|
|
22
|
+
/** The server a preset reaches (read lazily) or the session a connection runs in, never both. */
|
|
23
|
+
export type EngineServer = {
|
|
24
|
+
/** The server, read lazily: discovery, or a fixed description. */
|
|
25
|
+
readonly server: () => Promise<oauth.AuthorizationServer>;
|
|
26
|
+
readonly session?: never;
|
|
27
|
+
} | {
|
|
28
|
+
/**
|
|
29
|
+
* Looks up the whole session at once, so the server, its transport
|
|
30
|
+
* and the signature check come from the same lookup.
|
|
31
|
+
*/
|
|
32
|
+
readonly session: () => Promise<EngineSession>;
|
|
33
|
+
readonly server?: never;
|
|
34
|
+
};
|
|
35
|
+
/** One OpenID Connect provider, as its preset describes it. */
|
|
36
|
+
export type OidcEngine = EngineServer & EngineBase;
|
|
37
|
+
interface EngineBase {
|
|
38
|
+
readonly credentials: ProviderCredentials;
|
|
39
|
+
/** `pushedAuthorization` and `dpop`, as the application gave them. */
|
|
40
|
+
readonly security?: OidcSecurityOptions;
|
|
41
|
+
readonly scopes: readonly string[];
|
|
42
|
+
/** How the secret reaches the token endpoint; by default the method the server lists. */
|
|
43
|
+
readonly authentication?: 'post' | 'basic';
|
|
44
|
+
/** Parameters the authorization URL carries beside the standard ones. */
|
|
45
|
+
readonly authorizationParams?: Readonly<Record<string, string>>;
|
|
46
|
+
/** For a server whose issuer is known only from the token response. */
|
|
47
|
+
readonly serverForTokens?: (server: oauth.AuthorizationServer, answer: Response) => Promise<oauth.AuthorizationServer>;
|
|
48
|
+
/** Step-up values every sign-in must meet (`oidcStepUp`); sent with each request and held by `identity`. */
|
|
49
|
+
readonly fixedStepUp?: FixedStepUp;
|
|
50
|
+
/**
|
|
51
|
+
* Whether a flow's `stepUp` request is sent and the ID token's `acr` and
|
|
52
|
+
* `auth_time` are reported on the identity: the provider's
|
|
53
|
+
* `supportsStepUp`. `false` for a server that ignores `acr_values`.
|
|
54
|
+
*/
|
|
55
|
+
readonly perRequestStepUp: boolean;
|
|
56
|
+
/** The account the validated ID token's claims describe. */
|
|
57
|
+
readonly identity: (claims: oauth.IDToken) => SocialIdentity;
|
|
58
|
+
}
|
|
59
|
+
/** Builds the `SocialProvider` of an OpenID Connect engine. */
|
|
60
|
+
export declare function createOidcProvider(engine: OidcEngine): SocialProvider;
|
|
61
|
+
export {};
|
|
62
|
+
//# sourceMappingURL=oidc-engine.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"oidc-engine.d.ts","sourceRoot":"","sources":["../src/oidc-engine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,KAAK,YAAY,EAAU,MAAM,iBAAiB,CAAC;AAG5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,EAEN,KAAK,WAAW,EAGhB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAc,SAAS,EAAE,MAAM,aAAa,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;IAC5C,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,iGAAiG;AACjG,MAAM,MAAM,YAAY,GACrB;IACA,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;CACxB,GACD;IACA;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;CACvB,CAAC;AAEL,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC;AAEnD,UAAU,UAAU;IACnB,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yFAAyF;IACzF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,CAC1B,MAAM,EAAE,KAAK,CAAC,mBAAmB,EACjC,MAAM,EAAE,QAAQ,KACZ,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACxC,4GAA4G;IAC5G,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,KAAK,cAAc,CAAC;CAC7D;AASD,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CA2ErE"}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/** `oidcStepUp`: an OpenID Connect tenant that enforces a step-up. */
|
|
2
|
+
import { type SocialProvider } from '@softistx/janus';
|
|
3
|
+
import type { OidcStepUpOptions } from './options';
|
|
4
|
+
/**
|
|
5
|
+
* Sign-in, by the tenant's issuer. The e-mail counts when the ID
|
|
6
|
+
* token's `email_verified` is true. With `acrValues` and `maxAge`, the
|
|
7
|
+
* authorization request asks for them and the sign-in is refused unless the
|
|
8
|
+
* ID token's `acr` and `auth_time` prove them: the request parameters are
|
|
9
|
+
* hints the visitor can edit, so the claims are what is trusted; an unproven
|
|
10
|
+
* step-up is `SOCIAL_STEP_UP_UNMET`. "Now" is `Date.now()` at the exchange.
|
|
11
|
+
* A flow's own `stepUp` request is held too, on top of these fixed values
|
|
12
|
+
* (the `acr_values` both list, the smaller `max_age`).
|
|
13
|
+
*/
|
|
14
|
+
export declare function oidcStepUp(options: OidcStepUpOptions): SocialProvider;
|
|
15
|
+
//# sourceMappingURL=oidc-step-up.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"oidc-step-up.d.ts","sourceRoot":"","sources":["../src/oidc-step-up.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAKnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAInD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CA+BrE"}
|
package/dist/oidc.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** `oidcProvider`: any OpenID Connect provider, by its issuer. */
|
|
2
|
+
import type { SocialProvider } from '@softistx/janus';
|
|
3
|
+
import type { OidcProviderOptions } from './options';
|
|
4
|
+
/**
|
|
5
|
+
* An OpenID Connect provider, found through
|
|
6
|
+
* `<issuer>/.well-known/openid-configuration` on first use. The authorization
|
|
7
|
+
* code flow with PKCE; the ID token's `iss`, `aud`, `exp` and `nonce` are
|
|
8
|
+
* checked, and `email_verified` decides whether its e-mail counts.
|
|
9
|
+
*/
|
|
10
|
+
export declare function oidcProvider(options: OidcProviderOptions): SocialProvider;
|
|
11
|
+
//# sourceMappingURL=oidc.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../src/oidc.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAUtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAKrD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,CAezE"}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/** The options of every provider this package builds. */
|
|
2
|
+
import type { SocialIdentity } from '@softistx/janus';
|
|
3
|
+
/**
|
|
4
|
+
* The `fetch` a provider calls the identity provider with: the global one
|
|
5
|
+
* when absent. Typed narrower than `typeof fetch` so a plain function fits.
|
|
6
|
+
*/
|
|
7
|
+
export type SocialFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
|
|
8
|
+
/** What every provider needs to be a client of the identity provider. */
|
|
9
|
+
export interface ProviderCredentials {
|
|
10
|
+
/** The client id the identity provider issued for this application. */
|
|
11
|
+
readonly clientId: string;
|
|
12
|
+
/** The client secret that goes with it. Never logged, never put in an error. */
|
|
13
|
+
readonly clientSecret: string;
|
|
14
|
+
/**
|
|
15
|
+
* The callback URL registered with the identity provider. **It must be
|
|
16
|
+
* exactly the one registered there**, scheme, host, port and path. `https`,
|
|
17
|
+
* or `http` on a loopback host while developing.
|
|
18
|
+
*/
|
|
19
|
+
readonly redirectUri: string;
|
|
20
|
+
/** Replaces the global `fetch` for every request to the identity provider. */
|
|
21
|
+
readonly fetch?: SocialFetch;
|
|
22
|
+
/**
|
|
23
|
+
* Milliseconds each request to the identity provider may take, its body
|
|
24
|
+
* included. `10000` when absent. A request past it fails as a
|
|
25
|
+
* `PROVIDER_ERROR` with the reason `'unreachable'`.
|
|
26
|
+
*/
|
|
27
|
+
readonly timeout?: number;
|
|
28
|
+
}
|
|
29
|
+
/** The algorithms a DPoP key may use. */
|
|
30
|
+
export type DpopAlgorithm = 'ES256' | 'EdDSA';
|
|
31
|
+
/** What the OpenID Connect presets add for servers with stricter rules (RFC 9126, RFC 9449). */
|
|
32
|
+
export interface OidcSecurityOptions {
|
|
33
|
+
/**
|
|
34
|
+
* Pushed authorization requests (RFC 9126). `'auto'` (the default) pushes
|
|
35
|
+
* when the server's discovery says `require_pushed_authorization_requests`.
|
|
36
|
+
* `'always'` pushes whenever the server lists a
|
|
37
|
+
* `pushed_authorization_request_endpoint`, and fails with `PROVIDER_ERROR`
|
|
38
|
+
* when it lists none. The URL then carries only `client_id` and `request_uri`.
|
|
39
|
+
*/
|
|
40
|
+
readonly pushedAuthorization?: 'auto' | 'always';
|
|
41
|
+
/**
|
|
42
|
+
* Sender-constrain the tokens with DPoP (RFC 9449): the token request carries
|
|
43
|
+
* a proof signed by a fresh, non-extractable key pair made for that exchange.
|
|
44
|
+
* `true` means `ES256`. Off when absent.
|
|
45
|
+
*/
|
|
46
|
+
readonly dpop?: true | {
|
|
47
|
+
readonly algorithm: DpopAlgorithm;
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
/** An OpenID Connect provider found through its discovery document. */
|
|
51
|
+
export interface OidcProviderOptions extends ProviderCredentials, OidcSecurityOptions {
|
|
52
|
+
/** The issuer URL (`https`), whose `/.well-known/openid-configuration` is read on first use. */
|
|
53
|
+
readonly issuer: string;
|
|
54
|
+
/** Scopes to ask for; `openid` is always added. `['openid', 'email', 'profile']` when absent. */
|
|
55
|
+
readonly scopes?: readonly string[];
|
|
56
|
+
}
|
|
57
|
+
/** What a plain OAuth 2.0 provider tells the core about the account. */
|
|
58
|
+
export type OAuth2Identity = SocialIdentity;
|
|
59
|
+
/** A plain OAuth 2.0 provider: no ID token, so you say how to read the account. */
|
|
60
|
+
export interface OAuth2ProviderOptions extends ProviderCredentials {
|
|
61
|
+
/** The provider's authorization endpoint (`https`). */
|
|
62
|
+
readonly authorizationEndpoint: string;
|
|
63
|
+
/** The provider's token endpoint (`https`). */
|
|
64
|
+
readonly tokenEndpoint: string;
|
|
65
|
+
/** Scopes to ask for. */
|
|
66
|
+
readonly scopes: readonly string[];
|
|
67
|
+
/** How the client secret is sent to the token endpoint. `'post'` when absent. */
|
|
68
|
+
readonly clientAuthentication?: 'post' | 'basic';
|
|
69
|
+
/**
|
|
70
|
+
* Reads the account with the access token. It is given the `fetch` to use
|
|
71
|
+
* (yours, when you passed one). Throw to refuse; anything but a `SocialError`
|
|
72
|
+
* becomes a `PROVIDER_ERROR`.
|
|
73
|
+
*/
|
|
74
|
+
readonly identity: (accessToken: string, fetch: SocialFetch) => Promise<OAuth2Identity>;
|
|
75
|
+
}
|
|
76
|
+
/** Google, through OpenID Connect. */
|
|
77
|
+
export interface GoogleOptions extends ProviderCredentials {
|
|
78
|
+
/** Only accounts of this Google Workspace domain. Checked on the ID token's `hd`, not only asked for. */
|
|
79
|
+
readonly hostedDomain?: string;
|
|
80
|
+
}
|
|
81
|
+
/** GitHub, through OAuth 2.0. */
|
|
82
|
+
export type GithubOptions = ProviderCredentials;
|
|
83
|
+
/** Microsoft identity platform (Entra ID and personal accounts), through OpenID Connect. */
|
|
84
|
+
export interface MicrosoftOptions extends ProviderCredentials {
|
|
85
|
+
/**
|
|
86
|
+
* Whose accounts may sign in: `'common'` (any, the default), `'organizations'`,
|
|
87
|
+
* `'consumers'`, a tenant id (a GUID) or a verified domain.
|
|
88
|
+
*/
|
|
89
|
+
readonly tenant?: string;
|
|
90
|
+
}
|
|
91
|
+
/** An OpenID Connect tenant that can require a step-up (`acr`, `max_age`). */
|
|
92
|
+
export interface OidcStepUpOptions extends ProviderCredentials, OidcSecurityOptions {
|
|
93
|
+
/** The tenant's issuer URL (`https`), whose `/.well-known/openid-configuration` is read on first use. */
|
|
94
|
+
readonly issuer: string;
|
|
95
|
+
/**
|
|
96
|
+
* Authentication context class references to ask for (`acr_values`, space
|
|
97
|
+
* joined). Non-empty. The sign-in is refused unless the ID token's `acr` is
|
|
98
|
+
* one of them.
|
|
99
|
+
*/
|
|
100
|
+
readonly acrValues?: readonly string[];
|
|
101
|
+
/**
|
|
102
|
+
* Seconds since the visitor last authenticated (`max_age`), a non-negative
|
|
103
|
+
* integer. The sign-in is refused unless the ID token's `auth_time` is a
|
|
104
|
+
* number no older than that.
|
|
105
|
+
*/
|
|
106
|
+
readonly maxAge?: number;
|
|
107
|
+
}
|
|
108
|
+
//# sourceMappingURL=options.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,yDAAyD;AAEzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CACzB,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,IAAI,CAAC,EAAE,WAAW,KACd,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yCAAyC;AACzC,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9C,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG;QAAE,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;KAAE,CAAC;CAC7D;AAED,uEAAuE;AACvE,MAAM,WAAW,mBAChB,SAAQ,mBAAmB,EAC1B,mBAAmB;IACpB,gGAAgG;IAChG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC;AAE5C,mFAAmF;AACnF,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IACjE,uDAAuD;IACvD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,iFAAiF;IACjF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,WAAW,KACd,OAAO,CAAC,cAAc,CAAC,CAAC;CAC7B;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAc,SAAQ,mBAAmB;IACzD,yGAAyG;IACzG,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,iCAAiC;AACjC,MAAM,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAEhD,4FAA4F;AAC5F,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC5D;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAChB,SAAQ,mBAAmB,EAC1B,mBAAmB;IACpB,yGAAyG;IACzG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB"}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pushed authorization requests (RFC 9126): the parameters go to the server's
|
|
3
|
+
* endpoint, authenticated like the token request, and the visitor is sent
|
|
4
|
+
* with only `client_id` and the `request_uri` it answered.
|
|
5
|
+
*/
|
|
6
|
+
import * as oauth from 'oauth4webapi';
|
|
7
|
+
import type { transport } from './transport';
|
|
8
|
+
/** Whether this authorization request is pushed, or throws when it must be and cannot. */
|
|
9
|
+
export declare function shouldPush(server: oauth.AuthorizationServer, mode: 'auto' | 'always'): boolean;
|
|
10
|
+
/** What a push needs beside the parameters. */
|
|
11
|
+
export interface PushSetup {
|
|
12
|
+
readonly server: oauth.AuthorizationServer;
|
|
13
|
+
readonly clientId: string;
|
|
14
|
+
readonly auth: oauth.ClientAuth;
|
|
15
|
+
readonly http: ReturnType<typeof transport>;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Pushes `url`'s query and returns the URL the visitor is sent to. Every
|
|
19
|
+
* failure leaves as `PROVIDER_ERROR` at the step "the pushed authorization
|
|
20
|
+
* request", never carrying a parameter.
|
|
21
|
+
*/
|
|
22
|
+
export declare function push(setup: PushSetup, url: URL, endpoint: string): Promise<URL>;
|
|
23
|
+
//# sourceMappingURL=pushed-authorization.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pushed-authorization.d.ts","sourceRoot":"","sources":["../src/pushed-authorization.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,0FAA0F;AAC1F,wBAAgB,UAAU,CACzB,MAAM,EAAE,KAAK,CAAC,mBAAmB,EACjC,IAAI,EAAE,MAAM,GAAG,QAAQ,GACrB,OAAO,CAMT;AAED,+CAA+C;AAC/C,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CACnB,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,GAAG,CAAC,CA4Bd"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The step-up of an OpenID Connect preset: the fixed values `oidcStepUp()`
|
|
3
|
+
* holds the ID token to, the request one flow adds, and the evidence the ID
|
|
4
|
+
* token gives.
|
|
5
|
+
*/
|
|
6
|
+
import type { SocialStepUpRequest } from '@softistx/janus';
|
|
7
|
+
import type { IDToken } from 'oauth4webapi';
|
|
8
|
+
/** A fixed step-up: what a preset is configured to require on every sign-in. */
|
|
9
|
+
export interface FixedStepUp {
|
|
10
|
+
readonly acrValues?: readonly string[];
|
|
11
|
+
readonly maxAge?: number;
|
|
12
|
+
}
|
|
13
|
+
/** Throws unless `acrValues` is a non-empty array of tokens with no spaces, and `maxAge` a non-negative integer. */
|
|
14
|
+
export declare function checkStepUp(where: string, acrValues: unknown, maxAge: unknown): void;
|
|
15
|
+
/** The `acr_values` and `max_age` request parameters. */
|
|
16
|
+
export declare function stepUpParams({ acrValues, maxAge, }: {
|
|
17
|
+
readonly acrValues?: readonly string[] | undefined;
|
|
18
|
+
readonly maxAge?: number | undefined;
|
|
19
|
+
}): Record<string, string>;
|
|
20
|
+
/**
|
|
21
|
+
* The step-up a request effectively asks for: **both the preset's fixed values
|
|
22
|
+
* and the flow's request must hold**, so the URL sends the `acr_values` they
|
|
23
|
+
* share and the smaller `max_age`. Throws a `TypeError` when the two share no
|
|
24
|
+
* `acr_values`, since no sign-in could satisfy both.
|
|
25
|
+
*/
|
|
26
|
+
export declare function combineStepUp(fixed: FixedStepUp, request: SocialStepUpRequest | null): {
|
|
27
|
+
acrValues: readonly string[] | undefined;
|
|
28
|
+
maxAge: number | undefined;
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* The evidence an ID token gives the core: its `acr` (a non-empty string of at
|
|
32
|
+
* most 256 characters) and `auth_time` (a finite number of seconds). A claim
|
|
33
|
+
* that is missing or malformed is left out, and the core refuses the flow
|
|
34
|
+
* that needed it.
|
|
35
|
+
*/
|
|
36
|
+
export declare function stepUpClaims(claims: IDToken): {
|
|
37
|
+
acr?: string;
|
|
38
|
+
authTime?: Date;
|
|
39
|
+
};
|
|
40
|
+
/**
|
|
41
|
+
* Whether the ID token proves the step-up: its `acr` is one of `acrValues`,
|
|
42
|
+
* and its `auth_time` lies within `[now - maxAge - 60 s, now + 60 s]`
|
|
43
|
+
* (`now` in epoch milliseconds), so `maxAge: 0` means roughly the last minute.
|
|
44
|
+
* A missing claim fails; a request parameter alone proves nothing, since the
|
|
45
|
+
* visitor can edit the URL. **The same rule as `proveStepUp` in
|
|
46
|
+
* `@softistx/janus`** (AGENTS.md, "Deliberate duplications"): change one,
|
|
47
|
+
* change both.
|
|
48
|
+
*/
|
|
49
|
+
export declare function holdsStepUp(claims: IDToken, acrValues: readonly string[] | undefined, maxAge: number | undefined, now: number): boolean;
|
|
50
|
+
//# sourceMappingURL=step-up.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"step-up.d.ts","sourceRoot":"","sources":["../src/step-up.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAQ5C,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oHAAoH;AACpH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,OAAO,GACb,IAAI,CAmBN;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,EAC5B,SAAS,EACT,MAAM,GACN,EAAE;IACF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKzB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,mBAAmB,GAAG,IAAI,GACjC;IAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAkB1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,IAAI,CAAC;CAChB,CAeA;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAC1B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACxC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,GAAG,EAAE,MAAM,GACT,OAAO,CAeT"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** How requests leave: the `fetch` in use, and the client authentication. */
|
|
2
|
+
import * as oauth from 'oauth4webapi';
|
|
3
|
+
import type { SocialFetch } from './options';
|
|
4
|
+
/** Milliseconds a request to the identity provider may take when `timeout` is absent. */
|
|
5
|
+
export declare const DEFAULT_TIMEOUT = 10000;
|
|
6
|
+
/** The request options that route oauth4webapi through `fetch`, when it is not the global one. */
|
|
7
|
+
export declare function transport(fetchWith: SocialFetch | undefined, timeout: number | undefined): {
|
|
8
|
+
signal: () => AbortSignal;
|
|
9
|
+
[oauth.customFetch]?: (url: string, options: object) => Promise<Response>;
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* The `fetch` the provider hands to code of the application's (the identity
|
|
13
|
+
* callback). Each call gets its own timeout, unless the caller passes a `signal`.
|
|
14
|
+
*/
|
|
15
|
+
export declare function fetcher(fetchWith: SocialFetch | undefined, timeout: number | undefined): SocialFetch;
|
|
16
|
+
/** The client authentication for a secret, by the method the provider takes. */
|
|
17
|
+
export declare function clientAuth(secret: string, method: 'post' | 'basic'): oauth.ClientAuth;
|
|
18
|
+
//# sourceMappingURL=transport.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,yFAAyF;AACzF,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,kGAAkG;AAClG,wBAAgB,SAAS,CACxB,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,GAAG,SAAS,GACzB;IACF,MAAM,EAAE,MAAM,WAAW,CAAC;IAC1B,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC1E,CAQA;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACtB,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,GAAG,SAAS,GACzB,WAAW,CAOb;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,OAAO,GACtB,KAAK,CAAC,UAAU,CAIlB"}
|
package/docs/README.md
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# @softistx/janus-social — documentation
|
|
2
|
+
|
|
3
|
+
The [README](../README.md) shows the wiring of the four presets and the two
|
|
4
|
+
core calls; these pages give the detail, one per provider and one for connections stored at runtime.
|
|
5
|
+
|
|
6
|
+
| Page | Read it when |
|
|
7
|
+
| --- | --- |
|
|
8
|
+
| [Google](guide/google.md) | You register an OAuth client in Google Cloud, restrict sign-in to a Workspace domain, or wonder which Google claim counts as a verified e-mail |
|
|
9
|
+
| [GitHub](guide/github.md) | You register an OAuth app or a GitHub App, and need to know which e-mail GitHub gives you and when it gives none |
|
|
10
|
+
| [Microsoft](guide/microsoft.md) | You register an app in Microsoft Entra: work, school or personal accounts, the tenant to choose, and the `xms_edov` claim that makes the e-mail count |
|
|
11
|
+
| [OIDC step-up](guide/oidc-step-up.md) | You sign in with an OpenID Connect tenant, and want to require a level of assurance (`acr`) or a recent authentication (`max_age`) |
|
|
12
|
+
| [PAR and DPoP](guide/par-dpop.md) | Your OpenID Connect server requires pushed authorization requests (`invalid_request` at the authorize page) or wants DPoP-bound tokens |
|
|
13
|
+
| [OIDC connections](guide/oidc-connections.md) | Your customers bring their own OpenID Connect identity provider (Entra ID, Okta, Google Workspace) and you store the connections in your database: wiring, the record, e-mail trust, home-realm discovery |
|
|
14
|
+
| [Your own provider](guide/custom-providers.md) | You sign in with another OpenID Connect provider (`oidcProvider`), a plain OAuth 2.0 one (`oauth2Provider`), or write a `SocialProvider` by hand |
|
|
15
|
+
| [Troubleshooting](troubleshooting.md) | You paste an error message into a search box: a wiring `TypeError`, a `PROVIDER_ERROR` step, `redirect_uri_mismatch`, `EMAIL_UNVERIFIED` after a Microsoft sign-up |
|
|
16
|
+
| [Roadmap](roadmap.md) | You want to know what is coming and what is not planned |
|
|
17
|
+
|
|
18
|
+
The flow itself (`start`, `complete`, the flow cookie, linking, the cases a
|
|
19
|
+
callback decides) is in
|
|
20
|
+
[Social sign-in](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md)
|
|
21
|
+
of `@softistx/janus`.
|
|
22
|
+
|
|
23
|
+
## Words
|
|
24
|
+
|
|
25
|
+
The words of [`@softistx/janus`'s vocabulary](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/vocabulary.md)
|
|
26
|
+
keep their meaning. This package adds:
|
|
27
|
+
|
|
28
|
+
| Word | Means | Not |
|
|
29
|
+
| --- | --- | --- |
|
|
30
|
+
| **provider** | A `SocialProvider`: the object under `social.providers` with `authorizationUrl` and `exchange`. Also the identity provider it talks to, where the sentence says so | "strategy", "connector" |
|
|
31
|
+
| **preset** | `google()`, `github()`, `microsoft()` or `oidcStepUp()`: a provider with its endpoints and rules already known | "adapter" |
|
|
32
|
+
| **app registration** | What you create in the identity provider's console to get a client id and a secret | "app" alone, "project" |
|
|
33
|
+
| **OIDC connection** | One tenant's identity provider as your application stores it (`OidcConnection`), read through a `ConnectionSource` and answered by `oidcConnections` as a provider named by its `id`. Not a database connection | "tenant provider", "SSO config" |
|
|
34
|
+
| **redirect URI** | The callback URL of your application, registered with the identity provider and given as `redirectUri`. They must be the same string | "callback URL" for the registration field only |
|
|
35
|
+
| **account id** | The provider's stable id for an account (`accountId`): `sub`, or GitHub's numeric id. The key of a link, never the e-mail | "user id" (that is yours) |
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# Your own provider
|
|
2
|
+
|
|
3
|
+
This page is for signing in with an identity provider the presets do not cover:
|
|
4
|
+
`oidcProvider` for anything that speaks OpenID Connect, `oauth2Provider` for a
|
|
5
|
+
plain OAuth 2.0 provider, and a hand-written `SocialProvider` for the rest.
|
|
6
|
+
|
|
7
|
+
## OpenID Connect: `oidcProvider`
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import { oidcProvider } from '@softistx/janus-social';
|
|
11
|
+
|
|
12
|
+
export const provider = oidcProvider({
|
|
13
|
+
issuer: 'https://id.example.com', // yours: the provider's issuer URL
|
|
14
|
+
clientId: process.env.OIDC_CLIENT_ID!, // yours
|
|
15
|
+
clientSecret: process.env.OIDC_CLIENT_SECRET!, // yours
|
|
16
|
+
redirectUri: 'https://app.example.com/auth/sso/callback', // yours: registered with the provider
|
|
17
|
+
});
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
| Option | Type | Default | Effect |
|
|
21
|
+
| --- | --- | --- | --- |
|
|
22
|
+
| `issuer` | `string` | required | An `https` URL; `<issuer>/.well-known/openid-configuration` is read on first use and kept (a failure is not kept) |
|
|
23
|
+
| `clientId`, `clientSecret`, `redirectUri` | `string` | required | The app registration; the redirect URI is `https`, or `http` on a loopback host |
|
|
24
|
+
| `scopes` | `readonly string[]` | `['openid', 'email', 'profile']` | Scopes to ask for; `openid` is always added; none may hold a space |
|
|
25
|
+
| `fetch` | `SocialFetch` | global `fetch` | Used for discovery and every other request |
|
|
26
|
+
| `timeout` | `number` | `10000` | Milliseconds each request may take; past it the step fails as `unreachable` |
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
interface OidcProviderOptions extends ProviderCredentials {
|
|
30
|
+
readonly issuer: string;
|
|
31
|
+
readonly scopes?: readonly string[];
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The identity comes from the ID token alone: `accountId` is `sub`, `email` is the
|
|
36
|
+
`email` claim, and `emailVerified` is `email_verified` being `true` (or `"true"`).
|
|
37
|
+
There is no userinfo call, so the provider must put `email` and `email_verified`
|
|
38
|
+
in the ID token (ask for the `email` scope). The token's `iss`, `aud`, `exp` and
|
|
39
|
+
`nonce` are checked; its signature is not, for the direct TLS exchange. The secret
|
|
40
|
+
is sent in the body when the provider lists `client_secret_post`, else as HTTP
|
|
41
|
+
Basic.
|
|
42
|
+
|
|
43
|
+
A flow's `stepUp` request (`acr_values`, `max_age`) is sent by `oidcProvider` and
|
|
44
|
+
`oidcStepUp` and not by the other presets: see [OIDC step-up](oidc-step-up.md#one-sign-in-at-a-time).
|
|
45
|
+
|
|
46
|
+
## Plain OAuth 2.0: `oauth2Provider`
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
import { oauth2Provider } from '@softistx/janus-social';
|
|
50
|
+
|
|
51
|
+
export const provider = oauth2Provider({
|
|
52
|
+
authorizationEndpoint: 'https://id.example.com/oauth/authorize', // yours
|
|
53
|
+
tokenEndpoint: 'https://id.example.com/oauth/token', // yours
|
|
54
|
+
clientId: process.env.SSO_CLIENT_ID!,
|
|
55
|
+
clientSecret: process.env.SSO_CLIENT_SECRET!,
|
|
56
|
+
redirectUri: 'https://app.example.com/auth/sso/callback',
|
|
57
|
+
scopes: ['profile', 'email'], // yours: exactly what is asked for
|
|
58
|
+
identity: async (accessToken, fetch) => {
|
|
59
|
+
const answer = await fetch('https://id.example.com/api/me', {
|
|
60
|
+
headers: { authorization: `Bearer ${accessToken}` },
|
|
61
|
+
});
|
|
62
|
+
if (!answer.ok) throw new Error('the profile request failed');
|
|
63
|
+
const me = (await answer.json()) as { id: number; email?: string; email_confirmed?: boolean };
|
|
64
|
+
return {
|
|
65
|
+
accountId: String(me.id),
|
|
66
|
+
email: me.email ?? null,
|
|
67
|
+
emailVerified: me.email !== undefined && me.email_confirmed === true,
|
|
68
|
+
};
|
|
69
|
+
},
|
|
70
|
+
});
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
| Option | Type | Default | Effect |
|
|
74
|
+
| --- | --- | --- | --- |
|
|
75
|
+
| `authorizationEndpoint`, `tokenEndpoint` | `string` | required | `https` URLs |
|
|
76
|
+
| `scopes` | `readonly string[]` | required | Asked for exactly as given, no spaces inside one |
|
|
77
|
+
| `identity` | `(accessToken, fetch) => Promise<OAuth2Identity>` | required | Reads the account with the access token |
|
|
78
|
+
| `clientAuthentication` | `'post' \| 'basic'` | `'post'` | How the secret reaches the token endpoint |
|
|
79
|
+
| `clientId`, `clientSecret`, `redirectUri`, `fetch` | | | As above |
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
// The same shape as the core's SocialIdentity: OAuth2Identity is an alias of it
|
|
83
|
+
interface OAuth2Identity {
|
|
84
|
+
readonly accountId: string;
|
|
85
|
+
readonly email: string | null;
|
|
86
|
+
readonly emailVerified: boolean;
|
|
87
|
+
readonly name?: string;
|
|
88
|
+
readonly picture?: string;
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
- **`identity` is the only voucher for the e-mail.** Answer `emailVerified: true`
|
|
93
|
+
only for an address the provider itself says the account holds. The core links
|
|
94
|
+
accounts by e-mail on that word.
|
|
95
|
+
- **`accountId` is the provider's stable id**, not a login or an e-mail, which can
|
|
96
|
+
change.
|
|
97
|
+
- **Use the `fetch` you are given**, not the global one: it is yours when you
|
|
98
|
+
passed `fetch` to the provider, so a test stub reaches it.
|
|
99
|
+
- **Throw to refuse.** A `SocialError` passes through; anything else becomes
|
|
100
|
+
`PROVIDER_ERROR` at "the account request" (`unreachable` for a network error,
|
|
101
|
+
else `refused`).
|
|
102
|
+
- PKCE `S256` and `state` are used; there is no `nonce`, since there is no ID token.
|
|
103
|
+
|
|
104
|
+
## Neither: a `SocialProvider` by hand
|
|
105
|
+
|
|
106
|
+
For a provider that needs a signed JWT as its client secret, a form post, or
|
|
107
|
+
anything else, write the two calls the core asks for. The contract (what the
|
|
108
|
+
provider must check, how `emailVerified` is honest) is in the
|
|
109
|
+
[core guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md#writing-a-provider).
|
|
110
|
+
Throw a `SocialError('PROVIDER_ERROR', ...)` with a `reason` to be logged the
|
|
111
|
+
way this package's providers are.
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
import { SocialError, type SocialProvider } from '@softistx/janus';
|
|
115
|
+
|
|
116
|
+
export const provider: SocialProvider = {
|
|
117
|
+
async authorizationUrl({ state }) {
|
|
118
|
+
const url = new URL('https://id.example.com/authorize');
|
|
119
|
+
url.searchParams.set('state', state);
|
|
120
|
+
// ...client_id, redirect_uri, scope, code_challenge from codeVerifier, nonce
|
|
121
|
+
return url;
|
|
122
|
+
},
|
|
123
|
+
async exchange({ callback, state }) {
|
|
124
|
+
if (callback.get('state') !== state) {
|
|
125
|
+
throw new SocialError('PROVIDER_ERROR', 'the authorization response: refused', { reason: 'refused' });
|
|
126
|
+
}
|
|
127
|
+
// ...trade callback.get('code') with codeVerifier, read the account
|
|
128
|
+
return { accountId: 'abc', email: null, emailVerified: false };
|
|
129
|
+
},
|
|
130
|
+
};
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Supporting a step-up
|
|
134
|
+
|
|
135
|
+
A provider by hand opts in with `supportsStepUp: true`. It then gets `flow.stepUp`
|
|
136
|
+
(`{ acrValues: string[] | null, maxAge: number | null }`, or `null`) on both calls, sends it to the
|
|
137
|
+
authorization server, and reports `acr` and `authTime` (a `Date`) on the identity it answers; the core
|
|
138
|
+
refuses a flow whose identity does not prove the request. Without the flag, a flow asking for a step-up is
|
|
139
|
+
refused at `start`: set it only when the server honours `acr_values`.
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
export const provider: SocialProvider = {
|
|
143
|
+
supportsStepUp: true,
|
|
144
|
+
async authorizationUrl({ state, stepUp }) {
|
|
145
|
+
const url = new URL('https://id.example.com/authorize');
|
|
146
|
+
url.searchParams.set('state', state);
|
|
147
|
+
if (stepUp?.acrValues) url.searchParams.set('acr_values', stepUp.acrValues.join(' '));
|
|
148
|
+
if (stepUp?.maxAge !== null && stepUp?.maxAge !== undefined) url.searchParams.set('max_age', String(stepUp.maxAge));
|
|
149
|
+
return url;
|
|
150
|
+
},
|
|
151
|
+
async exchange() {
|
|
152
|
+
return { accountId: 'abc', email: null, emailVerified: false, acr: 'urn:example:mfa', authTime: new Date() };
|
|
153
|
+
},
|
|
154
|
+
};
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Testing
|
|
158
|
+
|
|
159
|
+
Pass `fetch` to the provider and answer the provider's endpoints from a stub; no
|
|
160
|
+
network is needed, and nothing else reaches the identity provider. A fake
|
|
161
|
+
`SocialProvider` for the whole flow is in the core guide.
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
import { oauth2Provider } from '@softistx/janus-social';
|
|
165
|
+
|
|
166
|
+
const calls: string[] = [];
|
|
167
|
+
export const provider = oauth2Provider({
|
|
168
|
+
authorizationEndpoint: 'https://id.example.com/authorize',
|
|
169
|
+
tokenEndpoint: 'https://id.example.com/token',
|
|
170
|
+
clientId: 'client',
|
|
171
|
+
clientSecret: 'secret',
|
|
172
|
+
redirectUri: 'http://localhost:3000/callback',
|
|
173
|
+
scopes: ['profile'],
|
|
174
|
+
fetch: async (input) => {
|
|
175
|
+
calls.push(String(input));
|
|
176
|
+
return Response.json({ access_token: 'token', token_type: 'bearer' });
|
|
177
|
+
},
|
|
178
|
+
identity: async () => ({ accountId: '1', email: null, emailVerified: false }),
|
|
179
|
+
});
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
More in [troubleshooting](../troubleshooting.md).
|