@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,632 @@
|
|
|
1
|
+
# Troubleshooting `@softistx/janus-social`
|
|
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. Wiring mistakes are `TypeError`s
|
|
7
|
+
thrown when you call a provider function, before any request; they name the
|
|
8
|
+
option and never its value. Failures during a flow are the core's `SocialError`
|
|
9
|
+
with the code `PROVIDER_ERROR` and a `reason` for your logs; this package
|
|
10
|
+
defines no error class. The refusals the core itself decides (`EMAIL_UNVERIFIED`,
|
|
11
|
+
`SIGN_UP_DISABLED`, `SOCIAL_ACCOUNT_TAKEN`, `FLOW_MISMATCH`) are in the
|
|
12
|
+
[core's troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md).
|
|
13
|
+
|
|
14
|
+
## Index
|
|
15
|
+
|
|
16
|
+
- Wiring: [`"<name>" must be a non-empty string`](#where-name-must-be-a-non-empty-string), [`"<name>" must be an https URL`](#where-name-must-be-an-https-url), [`"redirectUri" must be an https URL (http only on localhost)`](#where-redirecturi-must-be-an-https-url-http-only-on-localhost), [`"scopes" must be an array of scope names with no spaces`](#where-scopes-must-be-an-array-of-scope-names-with-no-spaces), [`"fetch" must be a function`](#where-fetch-must-be-a-function), [`oauth2Provider: "identity" must be a function`](#oauth2provider-identity-must-be-a-function), [`oauth2Provider: "clientAuthentication" must be 'post' or 'basic'`](#oauth2provider-clientauthentication-must-be-post-or-basic), [`oidcStepUp: "acrValues" must be a non-empty array of values with no spaces`](#oidcstepup-acrvalues-must-be-a-non-empty-array-of-values-with-no-spaces), [`oidcStepUp: "maxAge" must be a non-negative integer (seconds)`](#oidcstepup-maxage-must-be-a-non-negative-integer-seconds), [`"pushedAuthorization" must be 'auto' or 'always'`](#where-pushedauthorization-must-be-auto-or-always), [`"dpop" must be true or …`](#where-dpop-must-be-true-or--algorithm-es256--eddsa-), [`microsoft: "tenant" must be common, organizations, …`](#microsoft-tenant-must-be-common-organizations-consumers-a-tenant-id-or-a-domain)
|
|
17
|
+
- Flow: [`<step>: the visitor refused the authorization`](#step-the-visitor-refused-the-authorization), [`the authorization response: the identity provider refused …`](#the-authorization-response-the-identity-provider-refused-or-answered-something-unusable), [`the token request: …`](#the-token-request-the-identity-provider-refused-or-answered-something-unusable), [`the token response: …`](#the-token-response-the-identity-provider-refused-or-answered-something-unusable), [`the ID token: …`](#the-id-token-the-identity-provider-refused-or-answered-something-unusable), [`the account request: …` / `GitHub /user…`](#the-account-request--github-user--github-useremails-the-identity-provider-refused-or-answered-something-unusable), [`discovery: …` / `authorization URL: …`](#discovery--authorization-url-the-identity-provider-refused-or-answered-something-unusable), [`the pushed authorization request: …`](#the-pushed-authorization-request-the-identity-provider-refused-or-answered-something-unusable), [`the token response: …` with `use_dpop_nonce`](#the-token-response--with-use_dpop_nonce-in-the-cause), [`the token response: …` with a Bearer token](#the-token-response--with-a-bearer-token-while-dpop-is-on), [`this runtime cannot generate a "EdDSA" DPoP key`](#this-runtime-cannot-generate-a-eddsa-dpop-key), [`<step>: the identity provider could not be reached`](#step-the-identity-provider-could-not-be-reached)
|
|
18
|
+
- OIDC connections: [the record's `TypeError`s](#checkconnection-the-record-must-be-an-object), [`"claims" must be an object`](#checkconnection-claims-must-be-an-object), [the options'](#oidcconnections-the-options-must-be-an-object), [the stored connection is refused](#oidcconnections-the-stored-connection-id-is-malformed-and-is-refused), [discovery](#discovery-the-identity-provider-refused-or-answered-something-unusable-connections), [the ID token `check`](#the-id-token-the-identity-provider-refused-or-answered-something-unusable-with-check-in-the-cause-connections), [e-mail not vouched for](#email_unverified-or-email_not_verified_for_link-after-an-oidc-connection-sign-in)
|
|
19
|
+
- At the provider's page: [`redirect_uri_mismatch`](#redirect_uri_mismatch-or-the-providers-own-words)
|
|
20
|
+
- After the sign-in: [`EMAIL_UNVERIFIED` after a Microsoft sign-up](#email_unverified-after-a-microsoft-sign-up), [`EMAIL_UNVERIFIED` after a GitHub sign-up](#email_unverified-after-a-github-sign-up), [every Microsoft user signs up again](#every-microsoft-user-is-a-new-account-after-a-new-app-registration)
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Wiring
|
|
25
|
+
|
|
26
|
+
### `<where>: "<name>" must be a non-empty string`
|
|
27
|
+
|
|
28
|
+
`TypeError`, thrown by `google()`, `microsoft()`, `oidcStepUp()`, `oidcProvider()` or `oauth2Provider()`.
|
|
29
|
+
|
|
30
|
+
**When:** at wiring, for `clientId`, `clientSecret`, `redirectUri`, `hostedDomain`, `tenant`, or a missing endpoint.
|
|
31
|
+
**Why:** the option is absent, empty or blank, usually because an environment variable is unset. `<where>` is the function name; `github()` is built on `oauth2Provider`, so its message begins `oauth2Provider:`.
|
|
32
|
+
**Fix:** read the variables when the server starts and fail there:
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { google } from '@softistx/janus-social';
|
|
36
|
+
|
|
37
|
+
const need = (name: string): string => {
|
|
38
|
+
const value = process.env[name];
|
|
39
|
+
if (value === undefined || value === '') throw new Error(`${name} is not set`);
|
|
40
|
+
return value;
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
export const provider = google({
|
|
44
|
+
clientId: need('GOOGLE_CLIENT_ID'),
|
|
45
|
+
clientSecret: need('GOOGLE_CLIENT_SECRET'),
|
|
46
|
+
redirectUri: need('GOOGLE_REDIRECT_URI'),
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### `<where>: "<name>" must be an https URL`
|
|
51
|
+
|
|
52
|
+
`TypeError`, for `issuer` (`oidcProvider`, `oidcStepUp`), `authorizationEndpoint` and `tokenEndpoint` (`oauth2Provider`).
|
|
53
|
+
|
|
54
|
+
**When:** at wiring.
|
|
55
|
+
**Why:** the value is not an absolute URL, or its scheme is `http`. Endpoints that carry a secret are `https` only; there is no option to allow insecure requests.
|
|
56
|
+
**Fix:** give the `https` URL. For a local identity provider, put a TLS-terminating proxy in front of it.
|
|
57
|
+
|
|
58
|
+
### `oidcStepUp: "acrValues" must be a non-empty array of values with no spaces`
|
|
59
|
+
|
|
60
|
+
`TypeError`, thrown by `oidcStepUp()`.
|
|
61
|
+
|
|
62
|
+
**When:** at wiring.
|
|
63
|
+
**Why:** `acrValues` is an empty array, not an array, or holds an empty value or one with a space (the values are sent space-joined, so a space would split one into two).
|
|
64
|
+
**Fix:** leave it out for no requirement, or list the values:
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
oidcStepUp({ ...options, acrValues: ['urn:example:mfa'] }); // yours: the values the tenant defines
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### `oidcStepUp: "maxAge" must be a non-negative integer (seconds)`
|
|
71
|
+
|
|
72
|
+
`TypeError`, thrown by `oidcStepUp()`.
|
|
73
|
+
|
|
74
|
+
**When:** at wiring.
|
|
75
|
+
**Why:** `maxAge` is negative, fractional, `NaN`, or not a number (`'300'`).
|
|
76
|
+
**Fix:** pass whole seconds, such as `maxAge: 300`; `0` asks for a fresh authentication every time.
|
|
77
|
+
|
|
78
|
+
### `<where>: "redirectUri" must be an https URL (http only on localhost)`
|
|
79
|
+
|
|
80
|
+
`TypeError`.
|
|
81
|
+
|
|
82
|
+
**When:** at wiring.
|
|
83
|
+
**Why:** the redirect URI is not an absolute URL, or is `http` on a host that is not `localhost`, `127.0.0.1` or `[::1]`.
|
|
84
|
+
**Fix:**
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
const redirectUri = process.env.NODE_ENV === 'production'
|
|
88
|
+
? 'https://app.example.com/auth/google/callback' // yours
|
|
89
|
+
: 'http://localhost:3000/auth/google/callback';
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### `<where>: "scopes" must be an array of scope names with no spaces`
|
|
93
|
+
|
|
94
|
+
`TypeError`, for `oidcProvider` and `oauth2Provider`.
|
|
95
|
+
|
|
96
|
+
**When:** at wiring.
|
|
97
|
+
**Why:** `scopes` is a string (`'profile email'`), or an item is empty or holds a space.
|
|
98
|
+
**Fix:** one scope per item: `scopes: ['profile', 'email']`.
|
|
99
|
+
|
|
100
|
+
### `<where>: "timeout" must be a positive number`
|
|
101
|
+
|
|
102
|
+
`TypeError`.
|
|
103
|
+
|
|
104
|
+
**When:** at wiring.
|
|
105
|
+
**Why:** `timeout` is zero, negative, `NaN` or not a number.
|
|
106
|
+
**Fix:** pass milliseconds, such as `timeout: 5000`, or omit it for 10 seconds.
|
|
107
|
+
|
|
108
|
+
### `<where>: "fetch" must be a function`
|
|
109
|
+
|
|
110
|
+
`TypeError`.
|
|
111
|
+
|
|
112
|
+
**When:** at wiring.
|
|
113
|
+
**Why:** the `fetch` option is something else (an object, a mocking helper not yet called).
|
|
114
|
+
**Fix:** omit it, or pass `fetch` or a function `(input, init) => Promise<Response>`.
|
|
115
|
+
|
|
116
|
+
### `oauth2Provider: "identity" must be a function`
|
|
117
|
+
|
|
118
|
+
`TypeError`.
|
|
119
|
+
|
|
120
|
+
**When:** at wiring.
|
|
121
|
+
**Why:** `oauth2Provider` has no ID token to read the account from; `identity` is how it reads it.
|
|
122
|
+
**Fix:** give it: see [your own provider](guide/custom-providers.md#plain-oauth-20-oauth2provider).
|
|
123
|
+
|
|
124
|
+
### `oauth2Provider: "clientAuthentication" must be 'post' or 'basic'`
|
|
125
|
+
|
|
126
|
+
`TypeError`.
|
|
127
|
+
|
|
128
|
+
**When:** at wiring.
|
|
129
|
+
**Why:** only the two client-secret methods are supported (no `private_key_jwt`).
|
|
130
|
+
**Fix:** `clientAuthentication: 'basic'`, or leave it out for `'post'`.
|
|
131
|
+
|
|
132
|
+
### `microsoft: "tenant" must be common, organizations, consumers, a tenant id or a domain`
|
|
133
|
+
|
|
134
|
+
`TypeError`.
|
|
135
|
+
|
|
136
|
+
**When:** at wiring.
|
|
137
|
+
**Why:** the value is none of those four, for instance a full URL or a name with a slash.
|
|
138
|
+
**Fix:** `tenant: 'organizations'`, or the Directory (tenant) ID from the app registration. See [Microsoft](guide/microsoft.md#tenants).
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
### `<where>: "pushedAuthorization" must be 'auto' or 'always'`
|
|
143
|
+
|
|
144
|
+
`TypeError`, at wiring.
|
|
145
|
+
|
|
146
|
+
**Why:** the option is neither `'auto'` nor `'always'`.
|
|
147
|
+
**Fix:** use one of the two, or leave it out for `'auto'`.
|
|
148
|
+
|
|
149
|
+
### `<where>: "dpop" must be true or { algorithm: 'ES256' | 'EdDSA' }`
|
|
150
|
+
|
|
151
|
+
`TypeError`, at wiring.
|
|
152
|
+
|
|
153
|
+
**Why:** `dpop` is `false`, or an object whose `algorithm` is not `ES256` or `EdDSA`.
|
|
154
|
+
**Fix:** pass `true` (ES256), `{ algorithm: 'EdDSA' }`, or leave it out.
|
|
155
|
+
|
|
156
|
+
## The flow
|
|
157
|
+
|
|
158
|
+
`PROVIDER_ERROR` messages read `<step>: <what happened>`. The message never has
|
|
159
|
+
a URL, a token or what the provider wrote; the provider's own words are in the
|
|
160
|
+
error's `cause`. Log it, and answer the visitor a neutral "try again" (never the
|
|
161
|
+
`reason`):
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
import { SocialError } from '@softistx/janus';
|
|
165
|
+
|
|
166
|
+
declare const logger: { warn(entry: object): void };
|
|
167
|
+
|
|
168
|
+
export function log(error: unknown): void {
|
|
169
|
+
if (error instanceof SocialError && error.code === 'PROVIDER_ERROR') {
|
|
170
|
+
logger.warn({ provider: error.provider, reason: error.reason, message: error.message, cause: error.cause });
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
The three sentences are `the visitor refused the authorization` (`reason`
|
|
176
|
+
`denied`), `the identity provider refused or answered something unusable`
|
|
177
|
+
(`refused`) and `the identity provider could not be reached` (`unreachable`).
|
|
178
|
+
|
|
179
|
+
### `<step>: the visitor refused the authorization`
|
|
180
|
+
|
|
181
|
+
`PROVIDER_ERROR`, `reason: 'denied'`, at "the authorization response".
|
|
182
|
+
|
|
183
|
+
**When:** the visitor pressed Cancel or Deny at the provider, which came back with `error=access_denied`.
|
|
184
|
+
**Why:** not a fault. Any other `error` in the callback (`invalid_scope`, `server_error`, `unauthorized_client`) is `refused`.
|
|
185
|
+
**Fix:** send the visitor back to your sign-in page with a message; do not retry by itself.
|
|
186
|
+
|
|
187
|
+
### `the authorization response: the identity provider refused or answered something unusable`
|
|
188
|
+
|
|
189
|
+
`PROVIDER_ERROR`, `reason: 'refused'`.
|
|
190
|
+
|
|
191
|
+
**When:** the callback is handled.
|
|
192
|
+
**Why:** the callback carries an `error` other than `access_denied`; or has no `code`; or its `iss` (when the provider sends one) is not the provider's. A `state` that is not this flow's is refused by the core first (`FLOW_MISMATCH`).
|
|
193
|
+
**Fix:** read the `cause`: oauth4webapi names the parameter. Check the provider's console for what it reported.
|
|
194
|
+
|
|
195
|
+
### `the token request: the identity provider refused or answered something unusable`
|
|
196
|
+
|
|
197
|
+
`PROVIDER_ERROR`, `reason: 'refused'`.
|
|
198
|
+
|
|
199
|
+
**When:** the code is traded at the token endpoint.
|
|
200
|
+
**Why:** the provider's answer could not be used as a token response at all (for instance an unsupported operation or an authentication challenge). A rejected code or secret is usually reported one step later, as "the token response".
|
|
201
|
+
**Fix:** read the `cause`, then check `clientId`, `clientSecret` and `clientAuthentication`.
|
|
202
|
+
|
|
203
|
+
### `the token response: the identity provider refused or answered something unusable`
|
|
204
|
+
|
|
205
|
+
`PROVIDER_ERROR`, `reason: 'refused'`.
|
|
206
|
+
|
|
207
|
+
**When:** the code was traded and the answer was checked.
|
|
208
|
+
**Why:** the common causes, in the `cause`:
|
|
209
|
+
|
|
210
|
+
- **`invalid_client`**: a wrong or expired client secret. Microsoft: you pasted the secret's *Secret ID*, not its *Value*. GitHub: a secret for another app.
|
|
211
|
+
- **`invalid_grant`**: the code was used twice, expired, or `redirectUri` is not byte for byte the one of the authorization request (`redirect_uri_mismatch` can also appear here).
|
|
212
|
+
- **An ID token that is expired, issued in the future, or for another audience**: clock skew on `exp` when the server's clock is off by more than a few minutes. Run NTP; the package has no tolerance option.
|
|
213
|
+
- **A wrong `nonce`** or an issuer that is not the provider's: the response is for another flow, or the provider is not the one in `issuer`.
|
|
214
|
+
- **No access token** in the response, whatever its HTTP status (GitHub answers some errors with a 200).
|
|
215
|
+
|
|
216
|
+
**Fix:** correct the registration or the clock; start the flow again.
|
|
217
|
+
|
|
218
|
+
### `the ID token: the identity provider refused or answered something unusable`
|
|
219
|
+
|
|
220
|
+
`PROVIDER_ERROR`, `reason: 'refused'`.
|
|
221
|
+
|
|
222
|
+
**When:** the token response was fine, the account is read from the ID token.
|
|
223
|
+
**Why:**
|
|
224
|
+
|
|
225
|
+
- **Google `hostedDomain`**: the `hd` claim is not the domain you asked for (a personal Gmail account, or another Workspace).
|
|
226
|
+
- **Microsoft**: the token has no usable `tid`, or the account's tenant is not the one `tenant` allows (`consumers` admits only personal accounts; `organizations` refuses them; a tenant id admits only that organization). It means the wrong kind of account tried to sign in, or `tenant` is wrong.
|
|
227
|
+
- **`acrValues` / `maxAge` of `oidcStepUp`**: no longer here. A fixed step-up the ID token does not prove is [`SOCIAL_STEP_UP_UNMET`](#social_step_up_unmet-from-oidcstepup) since 0.5.0.
|
|
228
|
+
- **No `sub`**: the ID token does not name an account.
|
|
229
|
+
- **No ID token** at all, from an OpenID Connect provider (the `openid` scope was not granted).
|
|
230
|
+
|
|
231
|
+
**Fix:** sign in with an account the provider is configured for; check `tenant` and `hostedDomain`. See [Google](guide/google.md#one-workspace-domain), [OIDC step-up](guide/oidc-step-up.md#step-up) and [Microsoft](guide/microsoft.md#tenants).
|
|
232
|
+
|
|
233
|
+
### `SOCIAL_STEP_UP_UNMET` from `oidcStepUp`
|
|
234
|
+
|
|
235
|
+
`SocialError`, code `SOCIAL_STEP_UP_UNMET` (403), message `the ID token: the identity provider did not prove the step-up this provider requires`. Before 0.5.0 this was `PROVIDER_ERROR` with `reason: 'refused'`.
|
|
236
|
+
|
|
237
|
+
**When:** the ID token is read, on a provider with `acrValues` or `maxAge`.
|
|
238
|
+
**Why:**
|
|
239
|
+
|
|
240
|
+
- **`acrValues`**: the ID token's `acr` is absent or not one of the values you listed (the visitor signed in with a weaker method, or the tenant does not return `acr`).
|
|
241
|
+
- **`maxAge`**: the ID token's `auth_time` is absent, or outside `now - maxAge - 60 s` to `now + 60 s` (the tenant reused an old session, does not return `auth_time`, or the clocks differ by more than the tolerance). `maxAge: 0` means roughly the last minute.
|
|
242
|
+
|
|
243
|
+
**Fix:** configure the tenant to return `acr` and `auth_time`, or drop the option; check the server's clock. A flow's own `stepUp` request that the core finds unproven is the same code, from the core.
|
|
244
|
+
|
|
245
|
+
### A step-up flow through `google()` or `microsoft()`: `TypeError` at `start`
|
|
246
|
+
|
|
247
|
+
**When:** `social.start({ provider: 'google', stepUp: … })`.
|
|
248
|
+
**Why:** `google()` and `microsoft()` have `supportsStepUp: false`: Google ignores `acr_values` and Microsoft answers its own `acrs` values, so the request could not be proven. The core refuses before any token, so a provider that ignored the request never looks as if it had stepped up.
|
|
249
|
+
**Fix:** use `oidcProvider` or `oidcStepUp` for a tenant that honours `acr_values`.
|
|
250
|
+
|
|
251
|
+
### A step-up flow with no `acr_values` in common with `oidcStepUp`
|
|
252
|
+
|
|
253
|
+
`PROVIDER_ERROR`, `reason: 'refused'`, raised at `start`.
|
|
254
|
+
|
|
255
|
+
**Why:** the flow's `acrValues` and the provider's fixed `acrValues` share no value, so no sign-in could satisfy both. The values are not in the message.
|
|
256
|
+
**Fix:** ask for a value the provider lists, or change the provider's `acrValues`.
|
|
257
|
+
|
|
258
|
+
### `the account request` / `GitHub /user` / `GitHub /user/emails`: the identity provider refused or answered something unusable
|
|
259
|
+
|
|
260
|
+
`PROVIDER_ERROR`, `reason: 'refused'`.
|
|
261
|
+
|
|
262
|
+
**When:** after the token exchange, the account is read with the access token.
|
|
263
|
+
**Why:** for GitHub, `/user` or `/user/emails` did not answer 2xx (a revoked token; for a GitHub App, the **Email addresses** account permission is missing), or `/user` had no numeric `id`. For `oauth2Provider`, your `identity` threw.
|
|
264
|
+
**Fix:** for a GitHub App set **Permissions > Account permissions > Email addresses** to read-only. For `identity`, read the `cause`.
|
|
265
|
+
|
|
266
|
+
### `discovery` / `authorization URL`: the identity provider refused or answered something unusable
|
|
267
|
+
|
|
268
|
+
`PROVIDER_ERROR`, `reason: 'refused'`, at `start` (the authorization URL) or the first sign-in (discovery).
|
|
269
|
+
|
|
270
|
+
**When:** `social.start`, for `google()` and `oidcProvider()`.
|
|
271
|
+
**Why:** the issuer's `/.well-known/openid-configuration` answered something that is not a discovery document, or its `issuer` is not the one you gave (a trailing slash, a different host), or it has no `authorization_endpoint`.
|
|
272
|
+
**Fix:** open `<issuer>/.well-known/openid-configuration` and give `issuer` exactly the `issuer` it states. A failed discovery is not kept: the next sign-in asks again.
|
|
273
|
+
|
|
274
|
+
### `the pushed authorization request: the identity provider refused or answered something unusable`
|
|
275
|
+
|
|
276
|
+
`PROVIDER_ERROR`, `reason: 'refused'`.
|
|
277
|
+
|
|
278
|
+
**When:** the sign-in starts (`authorizationUrl`), for a provider that pushes.
|
|
279
|
+
**Why:** the server requires a push, or you set `pushedAuthorization: 'always'`, and either its discovery lists no `pushed_authorization_request_endpoint`, or the endpoint refused the request (the `cause` carries the OAuth `error`, such as `invalid_client` for a wrong secret or `invalid_request` for a parameter it dislikes), or its answer has no `request_uri`.
|
|
280
|
+
**Fix:** read the `cause`, check `clientId` and `clientSecret` against the server's registration, and that the discovery document lists the endpoint. A server that needs `dpop_jkt` at PAR is not supported.
|
|
281
|
+
|
|
282
|
+
```ts
|
|
283
|
+
oidcProvider({ issuer, clientId, clientSecret, redirectUri, pushedAuthorization: 'auto' });
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
### `the token response: …` with `use_dpop_nonce` in the cause
|
|
287
|
+
|
|
288
|
+
`PROVIDER_ERROR`, `reason: 'refused'`.
|
|
289
|
+
|
|
290
|
+
**When:** `dpop` is on and the code is traded.
|
|
291
|
+
**Why:** the server asked for its nonce twice. The package retries once with the nonce of the first refusal; a server that rotates its nonce on every call, or rejects the proof for another reason, ends here.
|
|
292
|
+
**Fix:** check the `cause`'s `error`; look at the server's log for the proof's `htu` and `htm` (the token endpoint's URL and `POST`).
|
|
293
|
+
|
|
294
|
+
### `the token response: …` with a Bearer token while `dpop` is on
|
|
295
|
+
|
|
296
|
+
`PROVIDER_ERROR`, `reason: 'refused'`.
|
|
297
|
+
|
|
298
|
+
**When:** `dpop` is on and the code is traded.
|
|
299
|
+
**Why:** the server answered `token_type: Bearer` to a DPoP request: it ignored the proof, so the tokens are not bound to the key. The sign-in is refused rather than silently downgraded.
|
|
300
|
+
**Fix:** check that the server supports DPoP for this client and token endpoint (its `dpop_signing_alg_values_supported`), or remove `dpop`.
|
|
301
|
+
|
|
302
|
+
### `this runtime cannot generate a "EdDSA" DPoP key`
|
|
303
|
+
|
|
304
|
+
Through the core, `complete` fails as `PROVIDER_ERROR` (`complete: the provider "<name>" failed`, reason `refused`) with this `TypeError` as its `cause`. Only a direct `provider.exchange()` throws the bare `TypeError`.
|
|
305
|
+
|
|
306
|
+
**When:** `dpop: { algorithm: 'EdDSA' }` (or `ES256`) and the code is traded.
|
|
307
|
+
**Why:** the runtime's WebCrypto has no key generation for that algorithm (Ed25519 on an older engine). The `cause` is the engine's `NotSupportedError`.
|
|
308
|
+
**Fix:** run on a runtime with Ed25519, or use `dpop: true` (ES256).
|
|
309
|
+
|
|
310
|
+
### `<step>: the identity provider could not be reached`
|
|
311
|
+
|
|
312
|
+
`PROVIDER_ERROR`, `reason: 'unreachable'`.
|
|
313
|
+
|
|
314
|
+
**When:** any step that makes a request.
|
|
315
|
+
**Why:** a network error or a timeout reached `fetch` (the request timeout, `timeout`, is 10 seconds by default): DNS, an egress firewall, or a `fetch` you passed that rejects. A refusal with a response is `refused`, not this.
|
|
316
|
+
**Fix:** from the server, request the provider's URL by hand. An egress allow-list needs `accounts.google.com`, `oauth2.googleapis.com`, `github.com`, `api.github.com` or `login.microsoftonline.com`, by provider.
|
|
317
|
+
|
|
318
|
+
## OIDC connections
|
|
319
|
+
|
|
320
|
+
Records are checked by `checkConnection` (and by `createMemoryConnections`, which calls it); a record with several problems throws **one** `TypeError` with one line per problem, so read every line. Messages name a field and never a value. `"scopes"`, `"pushedAuthorization"`, `"dpop"`, `"acrValues"` and `"maxAge"` of a record read as in the [wiring entries](#where-scopes-must-be-an-array-of-scope-names-with-no-spaces) above, with `checkConnection:` in front. The `oidcConnections(...)` options are checked at construction.
|
|
321
|
+
|
|
322
|
+
### `checkConnection: the record must be an object`
|
|
323
|
+
|
|
324
|
+
`TypeError`.
|
|
325
|
+
|
|
326
|
+
**When:** `checkConnection` got something that is not an object (a `null` row, an array, a string).
|
|
327
|
+
**Why:** your table answered an empty or mistyped row.
|
|
328
|
+
**Fix:** pass the parsed record; do not pass a JSON string.
|
|
329
|
+
|
|
330
|
+
### `checkConnection: "id" must match /^[a-z][a-z0-9-]{0,31}$/`
|
|
331
|
+
|
|
332
|
+
`TypeError`.
|
|
333
|
+
|
|
334
|
+
**When:** `checkConnection`, or `resolve` (the stored record is refused).
|
|
335
|
+
**Why:** `id` is the provider name the sign-in URL and the links carry: lowercase letters, digits and `-`, starting with a letter, at most 32 characters.
|
|
336
|
+
**Fix:** rename it before any account is linked; never rename it afterwards.
|
|
337
|
+
|
|
338
|
+
### `checkConnection: "<key>" is not a known field`
|
|
339
|
+
|
|
340
|
+
`TypeError`.
|
|
341
|
+
|
|
342
|
+
**When:** `checkConnection`, for a top-level key (`"foo"`) or one of `client` (`"client.foo"`).
|
|
343
|
+
**Why:** an unknown key is refused so that a typo does not silently disable a setting (`emailtrust`, `domain`, `idTokenAlg`).
|
|
344
|
+
**Fix:** fix the spelling; the keys are `id`, `issuer`, `client`, `domains`, `revision`, `emailTrust`, `scopes`, `claims`, `stepUp`, `pushedAuthorization`, `dpop`.
|
|
345
|
+
|
|
346
|
+
### `checkConnection: "issuer" must be an https URL`
|
|
347
|
+
|
|
348
|
+
`TypeError`.
|
|
349
|
+
|
|
350
|
+
**When:** the issuer is missing, not a URL, or not `https`.
|
|
351
|
+
**Why:** discovery is read from it, and `http` is never allowed.
|
|
352
|
+
**Fix:** write the issuer as the provider's discovery document states it.
|
|
353
|
+
|
|
354
|
+
### `checkConnection: "issuer" must have no query, fragment or credentials`
|
|
355
|
+
|
|
356
|
+
`TypeError`.
|
|
357
|
+
|
|
358
|
+
**When:** the issuer carries `?…`, `#…` or `user:pass@`.
|
|
359
|
+
**Why:** the issuer is compared byte for byte with the one the discovery document names.
|
|
360
|
+
**Fix:** use the bare issuer URL.
|
|
361
|
+
|
|
362
|
+
### `checkConnection: "issuer" must be written with a lowercase https scheme and host`
|
|
363
|
+
|
|
364
|
+
`TypeError`.
|
|
365
|
+
|
|
366
|
+
**When:** `HTTPS://…` or an upper-case host.
|
|
367
|
+
**Why:** the stored text is what discovery must repeat, and the provider writes it in lowercase.
|
|
368
|
+
**Fix:** lowercase the scheme and host; keep the path as the provider states it.
|
|
369
|
+
|
|
370
|
+
### `checkConnection: "issuer" must have no empty, "." or ".." path segment`
|
|
371
|
+
|
|
372
|
+
`TypeError`.
|
|
373
|
+
|
|
374
|
+
**When:** `https://x.example//tenant`, `/./` or `/../` in the path.
|
|
375
|
+
**Why:** a path the URL parser would rewrite would never equal the issuer the document names.
|
|
376
|
+
**Fix:** remove the segment; a single trailing slash is allowed only if the provider's issuer has it.
|
|
377
|
+
|
|
378
|
+
### `checkConnection: "client" must be an object`
|
|
379
|
+
|
|
380
|
+
`TypeError`.
|
|
381
|
+
|
|
382
|
+
**When:** `client` is absent or not an object.
|
|
383
|
+
**Why:** the record has no client registration.
|
|
384
|
+
**Fix:** give `client: { id, secret }`.
|
|
385
|
+
|
|
386
|
+
### `checkConnection: "client.id" must be a non-empty string`
|
|
387
|
+
|
|
388
|
+
`TypeError`.
|
|
389
|
+
|
|
390
|
+
**When:** `client.id` (or `client.secret`, with that name in the message) is absent or blank.
|
|
391
|
+
**Why:** a value was not set, usually a secret read from an unset variable.
|
|
392
|
+
**Fix:** set it; the secret is never printed.
|
|
393
|
+
|
|
394
|
+
### `checkConnection: "client.authentication" must be 'post' or 'basic'`
|
|
395
|
+
|
|
396
|
+
`TypeError`.
|
|
397
|
+
|
|
398
|
+
**When:** the field holds another value.
|
|
399
|
+
**Why:** only those two methods are supported.
|
|
400
|
+
**Fix:** use `'post'` or `'basic'`, or leave it out to follow the server's list.
|
|
401
|
+
|
|
402
|
+
### `checkConnection: "client.idTokenSignedResponseAlg" must be one of RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA (never none or HS*)`
|
|
403
|
+
|
|
404
|
+
`TypeError`.
|
|
405
|
+
|
|
406
|
+
**When:** the pinned algorithm is `none`, `HS256`… or a typo.
|
|
407
|
+
**Why:** the ID token's signature is verified with the issuer's public keys, so symmetric and unsigned tokens are refused.
|
|
408
|
+
**Fix:** pin an asymmetric algorithm the provider uses, or leave it out.
|
|
409
|
+
|
|
410
|
+
### `checkConnection: "domains" must be an array of e-mail domains`
|
|
411
|
+
|
|
412
|
+
`TypeError`.
|
|
413
|
+
|
|
414
|
+
**When:** `domains` is absent or not an array.
|
|
415
|
+
**Why:** the domains are what make an address trusted and what home-realm discovery reads.
|
|
416
|
+
**Fix:** give an array of strings.
|
|
417
|
+
|
|
418
|
+
### `checkConnection: "domains" holds a value that is not a domain name`
|
|
419
|
+
|
|
420
|
+
`TypeError`.
|
|
421
|
+
|
|
422
|
+
**When:** an entry is empty, has an empty or over-long label, an `_`, an IP literal, or an address (`ada@acme.example`).
|
|
423
|
+
**Why:** only a domain name can own an address.
|
|
424
|
+
**Fix:** write the bare domain (`acme.example`); Unicode names are converted to punycode.
|
|
425
|
+
|
|
426
|
+
### `checkConnection: "domains" must not be empty unless emailTrust is 'claim'`
|
|
427
|
+
|
|
428
|
+
`TypeError`.
|
|
429
|
+
|
|
430
|
+
**When:** no domain with `'claimAndDomain'` or `'domain'`.
|
|
431
|
+
**Why:** the trust policy needs a domain an address can belong to.
|
|
432
|
+
**Fix:** add the customer's domain (proved by them), or choose `'claim'` knowing [its risk](#checkconnection-emailtrust-must-be-claimanddomain-domain-or-claim).
|
|
433
|
+
|
|
434
|
+
### `checkConnection: "emailTrust" must be 'claimAndDomain', 'domain' or 'claim'`
|
|
435
|
+
|
|
436
|
+
`TypeError`.
|
|
437
|
+
|
|
438
|
+
**When:** another word.
|
|
439
|
+
**Why:** only three policies exist.
|
|
440
|
+
**Fix:** see [e-mail trust](guide/oidc-connections.md#e-mail-trust). `'claim'` lets a tenant claim any address.
|
|
441
|
+
|
|
442
|
+
### `checkConnection: "claims" must be an object`
|
|
443
|
+
|
|
444
|
+
`TypeError`.
|
|
445
|
+
|
|
446
|
+
**When:** `claims` is present and is not an object (a string, an array).
|
|
447
|
+
**Why:** the field is mistyped.
|
|
448
|
+
**Fix:** give `{ email?, emailVerified?, name?, picture? }`, or leave it out.
|
|
449
|
+
|
|
450
|
+
### `checkConnection: "claims.<key>" is not a claim that can be mapped`
|
|
451
|
+
|
|
452
|
+
`TypeError`.
|
|
453
|
+
|
|
454
|
+
**When:** `claims` has a key other than `email`, `emailVerified`, `name`, `picture`.
|
|
455
|
+
**Why:** `accountId` is always `sub`; nothing else is mapped.
|
|
456
|
+
**Fix:** remove it.
|
|
457
|
+
|
|
458
|
+
### `checkConnection: "claims.<key>" must not name a protocol claim (...)`
|
|
459
|
+
|
|
460
|
+
`TypeError`.
|
|
461
|
+
|
|
462
|
+
**When:** `claims.email`, `claims.name` and the like name one of `sub`, `iss`, `aud`, `azp`, `nonce`, `at_hash`, `acr`, `amr` or `auth_time`.
|
|
463
|
+
**Why:** those claims describe the token, not the visitor; mapping one to the e-mail would let a token's own fields speak for the person.
|
|
464
|
+
**Fix:** map a claim the provider fills with the person's data (`email`, `mail`, `preferred_username`).
|
|
465
|
+
|
|
466
|
+
### `checkConnection: "stepUp" must be an object`
|
|
467
|
+
|
|
468
|
+
`TypeError`.
|
|
469
|
+
|
|
470
|
+
**When:** `stepUp` is not an object (its `acrValues` and `maxAge` errors read as [`oidcStepUp`'s](#oidcstepup-acrvalues-must-be-a-non-empty-array-of-values-with-no-spaces) with `checkConnection:` in front).
|
|
471
|
+
**Why:** the field is mistyped.
|
|
472
|
+
**Fix:** give `{ acrValues?, maxAge? }`.
|
|
473
|
+
|
|
474
|
+
### `checkConnection: "revision" must be a non-empty string or a non-negative integer when given`
|
|
475
|
+
|
|
476
|
+
`TypeError`.
|
|
477
|
+
|
|
478
|
+
**When:** `revision` is present and is empty, negative, fractional or of another type. An absent `revision` is fine.
|
|
479
|
+
**Why:** it is your own bookkeeping, and `janus-social` does not read it; a malformed one is still refused so the record stays clean.
|
|
480
|
+
**Fix:** write a counter or a version string, or leave it out.
|
|
481
|
+
|
|
482
|
+
### `createMemoryConnections: duplicate id "<id>"`
|
|
483
|
+
|
|
484
|
+
`TypeError`.
|
|
485
|
+
|
|
486
|
+
**When:** `createMemoryConnections(records)`.
|
|
487
|
+
**Why:** two records share an `id`.
|
|
488
|
+
**Fix:** give each connection its own id.
|
|
489
|
+
|
|
490
|
+
### `createMemoryConnections: the domain "<domain>" belongs to two connections`
|
|
491
|
+
|
|
492
|
+
`TypeError`.
|
|
493
|
+
|
|
494
|
+
**When:** `createMemoryConnections(records)`.
|
|
495
|
+
**Why:** two records list the same domain, so home-realm discovery could not answer one. Your own table needs the [same refusal](guide/oidc-connections.md#checking-a-record-before-it-is-stored) on write.
|
|
496
|
+
**Fix:** keep each domain on one connection.
|
|
497
|
+
|
|
498
|
+
### `oidcConnections: the options must be an object`
|
|
499
|
+
|
|
500
|
+
`TypeError`, at construction.
|
|
501
|
+
|
|
502
|
+
**When:** `oidcConnections(options)`.
|
|
503
|
+
**Why:** `oidcConnections()` was called with nothing or a non-object.
|
|
504
|
+
**Fix:** `oidcConnections({ source, redirectUri })`.
|
|
505
|
+
|
|
506
|
+
### `oidcConnections: "source" must have findConnection and findConnectionByDomain`
|
|
507
|
+
|
|
508
|
+
`TypeError`, at construction.
|
|
509
|
+
|
|
510
|
+
**When:** `oidcConnections(options)`.
|
|
511
|
+
**Why:** the `source` is absent or lacks one of the two methods.
|
|
512
|
+
**Fix:** implement both: `findConnection(id)` and `findConnectionByDomain(domain)`, each answering a record or `null`.
|
|
513
|
+
|
|
514
|
+
### `oidcConnections: "allowUrl" must be a function`
|
|
515
|
+
|
|
516
|
+
`TypeError`, at construction.
|
|
517
|
+
|
|
518
|
+
**When:** `oidcConnections(options)`.
|
|
519
|
+
**Why:** `allowUrl` is not a function.
|
|
520
|
+
**Fix:** `(url: URL) => boolean`; it can only narrow the URL policy.
|
|
521
|
+
|
|
522
|
+
### `oidcConnections: "cache" must be an object`
|
|
523
|
+
|
|
524
|
+
`TypeError`, at construction.
|
|
525
|
+
|
|
526
|
+
**When:** `oidcConnections(options)`.
|
|
527
|
+
**Why:** `cache` is not an object.
|
|
528
|
+
**Fix:** `{ max?, idleMs? }`.
|
|
529
|
+
|
|
530
|
+
### `oidcConnections: "cache.max" must be a positive integer`
|
|
531
|
+
|
|
532
|
+
`TypeError`, at construction.
|
|
533
|
+
|
|
534
|
+
**When:** `oidcConnections(options)`.
|
|
535
|
+
**Why:** `cache.max` (or `cache.idleMs`, named in the message) is zero, negative or fractional.
|
|
536
|
+
**Fix:** a whole number of issuers, or of milliseconds.
|
|
537
|
+
|
|
538
|
+
### `oidcConnections: "clock" must have a now() method`
|
|
539
|
+
|
|
540
|
+
`TypeError`, at construction.
|
|
541
|
+
|
|
542
|
+
**When:** `oidcConnections(options)`.
|
|
543
|
+
**Why:** `clock` has no `now()`.
|
|
544
|
+
**Fix:** pass a `Clock` such as `fixedClock()`, or leave it out. It drives the discovery cache only.
|
|
545
|
+
|
|
546
|
+
`oidcConnections` also reports `"redirectUri"`, `"fetch"` and `"timeout"` with the [wiring messages above](#where-name-must-be-an-https-url), `<where>` being `oidcConnections`.
|
|
547
|
+
|
|
548
|
+
### `oidcConnections: the stored connection "<id>" is malformed and is refused`
|
|
549
|
+
|
|
550
|
+
A process warning (code `JANUS_SOCIAL_CONNECTION_REFUSED`), emitted once per id, next to a `PROVIDER_ERROR`.
|
|
551
|
+
|
|
552
|
+
**When:** `connections.resolve(id)` read a record from your source.
|
|
553
|
+
**Why:** the record fails `checkConnection` (a hand-edited row, a column added in a migration, an old record from before a rule), or its `id` is not the name asked for. The warning names the id, never a value. It repeats only after the record resolved fine once.
|
|
554
|
+
**Fix:** run `checkConnection` on the stored row and read the `TypeError`; repair the row. Show the warning with `process.on('warning', (w) => { if (w.code === 'JANUS_SOCIAL_CONNECTION_REFUSED') log(w.message); })`. Validate on your write path so a bad record never reaches the table.
|
|
555
|
+
|
|
556
|
+
### `the connection: the identity provider refused or answered something unusable`
|
|
557
|
+
|
|
558
|
+
`PROVIDER_ERROR`, `reason: 'refused'`, from `resolve`.
|
|
559
|
+
|
|
560
|
+
**When:** `social.start` or `social.complete` for a connection id.
|
|
561
|
+
**Why:** the warning above: the stored record is malformed.
|
|
562
|
+
**Fix:** as above. A record your source does not have is not this: that is `SOCIAL_PROVIDER_UNKNOWN`, and a failure of your source propagates as itself.
|
|
563
|
+
|
|
564
|
+
### `discovery: the identity provider refused or answered something unusable` (connections)
|
|
565
|
+
|
|
566
|
+
`PROVIDER_ERROR`, `reason: 'refused'`.
|
|
567
|
+
|
|
568
|
+
**When:** the first sign-in through a connection, and again once an hour.
|
|
569
|
+
**Why:** besides the causes [above](#discovery--authorization-url-the-identity-provider-refused-or-answered-something-unusable): the document's `issuer` is not byte for byte the record's `issuer` (Entra's `common` endpoint publishes `{tenantid}`); a required member is missing; an `_endpoint` or `_uri` member (`jwks_uri`, `op_policy_uri`, `op_tos_uri`…) fails the URL policy (`http`, a private address, credentials); or `id_token_signing_alg_values_supported` lists `none`. The cause names a guard code when the request itself was refused: `url`, `address`, `redirect`, `content-type` or `oversize`; `dns` is [`unreachable`](#step-the-identity-provider-could-not-be-reached).
|
|
570
|
+
**Fix:** open `<issuer>/.well-known/openid-configuration` from the server and compare. A tenant-specific issuer fixes the Entra case. An internal identity provider is refused on purpose: put it behind a public name, or terminate it elsewhere.
|
|
571
|
+
|
|
572
|
+
### `the ID token: the identity provider refused or answered something unusable` with `check` in the cause (connections)
|
|
573
|
+
|
|
574
|
+
`PROVIDER_ERROR`, `reason: 'refused'`, the `cause` is `{ check: '<name>' }`.
|
|
575
|
+
|
|
576
|
+
**When:** `social.complete` through a connection, after the token response.
|
|
577
|
+
**Why:** `check` says which rule the ID token broke, never its content:
|
|
578
|
+
|
|
579
|
+
- **`alg`**: the header's algorithm is `none`, `HS*`, missing, or not the one the record pins (or not in `RS256`, `PS256`, `ES256`, `EdDSA`).
|
|
580
|
+
- **`iss`**: the token's issuer is not the record's. A tenant-specific issuer, or the wrong connection.
|
|
581
|
+
- **`sub`**: absent, empty or over 255 characters.
|
|
582
|
+
- **`azp`**: present and not the client id, or absent while `aud` lists several audiences.
|
|
583
|
+
- **`iat`**: absent, or more than 30 seconds in the future: the server's clock is ahead of the provider's.
|
|
584
|
+
- **`at_hash`**: present and not the hash of the access token.
|
|
585
|
+
- A signature that does not verify, an unknown `kid` (the key set is refetched only if the kept one is 60 s old or more, so a key rotated seconds ago may fail once), a wrong `aud`, `nonce`, `exp` or `nbf`: the cause is oauth4webapi's, with no `check`.
|
|
586
|
+
- A fixed `stepUp` the token does not prove is [`SOCIAL_STEP_UP_UNMET`](#social_step_up_unmet-from-oidcstepup).
|
|
587
|
+
|
|
588
|
+
**Fix:** check `iss` against the record, sync the server's clock (NTP), retry after a rotation, and pin `client.idTokenSignedResponseAlg` to what the provider signs with.
|
|
589
|
+
|
|
590
|
+
### `EMAIL_UNVERIFIED` or `EMAIL_NOT_VERIFIED_FOR_LINK` after an OIDC connection sign-in
|
|
591
|
+
|
|
592
|
+
Core codes.
|
|
593
|
+
|
|
594
|
+
**When:** a sign-in or sign-up through a connection whose provider returned an e-mail.
|
|
595
|
+
**Why:** the e-mail is returned but never vouched for: it is outside the record's `domains`, or the provider sent no `email_verified` under `'claimAndDomain'` (Entra ID sends none), or the ID token has no `email` at all (no userinfo fallback in this version).
|
|
596
|
+
**Fix:** add the customer's domain, use `emailTrust: 'domain'` for providers with no `email_verified`, and make the provider put `email` in the ID token (scope `email`, optional claim at Entra).
|
|
597
|
+
|
|
598
|
+
---
|
|
599
|
+
|
|
600
|
+
## At the provider's page
|
|
601
|
+
|
|
602
|
+
### `redirect_uri_mismatch` (or the provider's own words)
|
|
603
|
+
|
|
604
|
+
**When:** the visitor lands on an error page of Google, GitHub or Microsoft (`AADSTS50011`) instead of the sign-in.
|
|
605
|
+
**Why:** `redirectUri` is not one of the URIs registered with the app, byte for byte: scheme, host, port, path, trailing slash. Typical causes are `http` versus `https`, `www.`, a development port, a trailing `/`.
|
|
606
|
+
**Fix:** register the exact string the code passes, in the provider's console (see [Google](guide/google.md#register-the-app), [GitHub](guide/github.md#register-the-app), [Microsoft](guide/microsoft.md#register-the-app)), and make that path the route that calls `social.complete`.
|
|
607
|
+
|
|
608
|
+
---
|
|
609
|
+
|
|
610
|
+
## After the sign-in
|
|
611
|
+
|
|
612
|
+
### `EMAIL_UNVERIFIED` after a Microsoft sign-up
|
|
613
|
+
|
|
614
|
+
`SocialError`, 403, from `social.complete`.
|
|
615
|
+
|
|
616
|
+
**When:** a stranger signs in with Microsoft and nobody is created.
|
|
617
|
+
**Why:** the e-mail counts only when the ID token's `xms_edov` claim is `true`, and the app registration does not send it. Every Microsoft sign-in is then an unverified e-mail: no sign-up, and no link by e-mail either (`EMAIL_NOT_VERIFIED_FOR_LINK` for an existing user).
|
|
618
|
+
**Fix:** **Token configuration > Add optional claim > ID > `xms_edov`** on the app registration, then sign in again (the claim is in new tokens only). See [Microsoft](guide/microsoft.md#the-e-mail).
|
|
619
|
+
|
|
620
|
+
### `EMAIL_UNVERIFIED` after a GitHub sign-up
|
|
621
|
+
|
|
622
|
+
`SocialError`, 403.
|
|
623
|
+
|
|
624
|
+
**When:** a GitHub user signs up and nobody is created.
|
|
625
|
+
**Why:** GitHub gives the e-mail only when it is the **primary** address and **verified**; this account has none, or its verified address is not the primary one. A GitHub App without the **Email addresses** permission fails earlier, at `GitHub /user/emails`.
|
|
626
|
+
**Fix:** the user verifies their primary address in GitHub's settings, or signs up another way and links GitHub afterwards.
|
|
627
|
+
|
|
628
|
+
### Every Microsoft user is a new account after a new app registration
|
|
629
|
+
|
|
630
|
+
**When:** you registered the app again (a new client id) and users who linked Microsoft before can no longer sign in with it.
|
|
631
|
+
**Why:** the account id is `sub`, which Microsoft makes pairwise per app registration; a new registration gives new ids, so the stored links match nothing.
|
|
632
|
+
**Fix:** keep the app registration. If it has to change, users sign in another way and link Microsoft again (`social.link`).
|