What your users see
Your page asks for their email
Your sign-in page has one field. The user types their email (or a WebID) and continues.
webid.email, in your colours
The browser goes to webid.email. Its sign-in page says “Sign in to Your App”, styled from your theme, with “powered by webid.email” in small print. The email is already filled in (
login_hint). The user proves it is theirs with a code sent to that address, with Google, or with a password if they set one on webid.email. A new email gets an account from its first code, already verified.One-time consent
The first time this account signs in to your app, webid.email asks “Sign in to Your App” and says “Your App will receive your email and name.” The answer is remembered for that account and app.
Back in your app, signed in
webid.email sends the browser to your callback; your app checks the answer and starts its own session.
Next time the browser is still signed in to webid.email (until the user signs out there), so a sign-in goes there and straight back, with no page in between. Your app can also ask for a silent sign-in (prompt=none): it returns signed in, or with an answer saying the user is needed, never with a page.
With @_linked/auth
In a Linked app, @_linked/auth (3.15 or later) is the relying party: it serves your Client ID Document, finds the user’s issuer, runs the code flow with PKCE and DPoP, checks the ID token and the WebID, and signs the user in to your app.
1. Configure
Set two statics on Auth in your backend module, at load time: auth reads them in its own setupBeforeControllers, which runs before your provider’s.
// src/backend.ts, at module load: auth reads both in its own setupBeforeControllers
import { Auth } from '@_linked/auth/utils/auth';
// Your Client ID Document, served at {SITE_ROOT}/.well-known/linked-client.jsonld
Auth.signinClient = {
clientName: 'Your App',
logoUri: 'https://your.app/logo.svg',
policyUri: 'https://your.app/privacy',
theme: {
layout: 'two-column',
colors: { primary: '#116d8d', background: '#ffffff', panel: '#0a2e3a' },
font: 'Roboto',
scheme: 'light',
brand: { name: 'Your App', logoUri: 'https://your.app/logo.svg' },
panelArt: 'https://your.app/signin-art.svg',
},
};
// Sign-in through webid.email, with every default; adds {SITE_ROOT}/auth/oidc/callback
Auth.oidcSignin = {};Auth.signinClient:clientName(required),logoUri,clientUri(defaultSITE_ROOT),policyUri,tosUri,redirectUris(extra ones, for native apps) andtheme. URLs arehttps:(http:only onlocalhost); anything else stops the server at startup.- The theme is declarative, so none of your code runs where people type credentials:
layout(cardortwo-column),colors(primary,accent,background,panel,text; hex, numericrgb()/hsl()or a named colour),font(one ofSIGNIN_THEME_FONTS:system-ui, Inter, Roboto, Open Sans, Lato, Montserrat, Source Sans 3, Nunito, Poppins, Work Sans, Merriweather, Lora, Playfair Display, all hosted by webid.email),scheme(lightordark),brand(name,logoUri) andpanelArt(an image or animated SVG). webid.email fetches the logo and art itself and refuses an SVG over 50 KB gzipped or another image over 150 KB. An invalid value is logged at startup and left out; the rest is served. Auth.oidcSignin: every field is optional,{}signs in through webid.email.defaultIssuer(defaulthttps://webid.email),allowLocalhost(for a local issuer),requireEmail,timeoutMs(5000),clientId(default: your document’s URL),discovery(cache and skip-list options),onEmailMismatchandonResult(below).- Cookies are named from your
APP_PREFIX(your-app_accessToken, …), with nothing to set, so your app and another Linked app on the same host (two apps on differentlocalhostports) keep separate sessions. The browser bundle needs the same prefix:
// vite.config.ts
import { resolveCookiePrefix } from '@_linked/auth/utils/cookieNames';
import { createViteConfig } from '@_linked/cli/vite-config';
export default createViteConfig({
define: {
'process.env.AUTH_COOKIE_PREFIX': JSON.stringify(resolveCookiePrefix(process.env)),
},
});Auth.cookiePrefix or AUTH_COOKIE_PREFIX override the prefix; leave both unset.
2. The Client ID Document
With Auth.signinClient set, auth serves your document at {SITE_ROOT}/.well-known/linked-client.jsonld (application/ld+json, cached for ten minutes). Its URL is your client_id. For the configuration above and SITE_ROOT=https://your.app:
{
"@context": ["https://www.w3.org/ns/solid/oidc-context.jsonld"],
"client_id": "https://your.app/.well-known/linked-client.jsonld",
"client_name": "Your App",
"redirect_uris": ["https://your.app/auth/oidc/callback"],
"client_uri": "https://your.app",
"logo_uri": "https://your.app/logo.svg",
"policy_uri": "https://your.app/privacy",
"grant_types": ["authorization_code"],
"response_types": ["code"],
"scope": "openid webid email",
"token_endpoint_auth_method": "none",
"https://linked.cm/ns/signin#theme": {
"layout": "two-column",
"scheme": "light",
"font": "Roboto",
"colors": { "primary": "#116d8d", "background": "#ffffff", "panel": "#0a2e3a" },
"brand": { "name": "Your App", "logoUri": "https://your.app/logo.svg" },
"panelArt": "https://your.app/signin-art.svg"
}
}It declares a public client (no secret), and the theme sits under one key other issuers ignore. webid.email fetches it on the first sign-in and keeps it as its Cache-Control says, so a change reaches the sign-in page within ten minutes.
3. The email step
Your sign-in page calls auth’s startOidcSignin and sends the browser to the url it answers:
// src/pages/Signin.tsx, the page at /signin
import React, { useState } from 'react';
import { useSearchParams } from 'react-router-dom';
import { Server } from '@_linked/server-utils/utils/Server';
/** Callback errors that only mean "the user has to sign in": show the form, no message. */
const NEEDS_THE_USER = ['login_required', 'interaction_required'];
export default function Signin() {
const [params] = useSearchParams();
const callbackError = params.get('oidc_error'); // set by auth's callback on a failure
const [input, setInput] = useState('');
const [error, setError] = useState(
callbackError && !NEEDS_THE_USER.includes(callbackError) ? `Sign-in failed: ${callbackError}` : '',
);
async function start(options: { providerHint?: string } = {}) {
setError('');
const answer = await Server.call('@_linked/auth', 'startOidcSignin', {
input: input.trim(), // an email or a WebID; may be empty with a providerHint
returnTo: '/',
...options,
});
if (typeof answer?.url === 'string') window.location.assign(answer.url);
else setError(answer?.error ?? 'Could not start the sign-in.');
}
return (
<main>
<h1>Sign in</h1>
<form
onSubmit={(event) => {
event.preventDefault();
void start();
}}
>
<label htmlFor="signin-input">Email or WebID</label>
<input
id="signin-input"
inputMode="email"
autoComplete="email"
required
value={input}
onChange={(event) => setInput(event.target.value)}
/>
<button type="submit">Continue</button>
</form>
<button type="button" onClick={() => void start({ providerHint: 'google' })}>
Continue with Google
</button>
{error && <p role="alert">{error}</p>}
</main>
);
}startOidcSignin({input?, prompt?, providerHint?, returnTo?}) answers {url}, or {error, action} with action one of not_configured, invalid_input, issuer_not_found, invalid_issuer, issuer_unreachable, no_session or rate_limited.
inputis an email or a WebID. Discovery finds the issuer: a WebID’s profile names it (solid:oidcIssuer); for an email, the domain’s WebFinger answer may name one, and otherwise (and straight away for gmail.com, outlook.com, icloud.com and the like) it is the default issuer, webid.email, with the email sent aslogin_hint: webid.email’s page then shows that email and never asks for it again.returnTois a path on your site to land on after signing in.- The request is the code flow with PKCE (
S256),state,nonce, a DPoP key bound withdpop_jkt, and the scopeopenid webid email. The pending sign-in waits in the browser’s server-side session for ten minutes.
4. The callback
Auth serves GET {SITE_ROOT}/auth/oidc/callback. It takes the pending sign-in by state (once, this browser only), exchanges the code with a DPoP proof, checks the ID token (signature, iss, aud, exp, iat, nonce; webid and auth_time required), checks that the issuer may speak for the WebID (below), finds or creates the person at the WebID and its account, and starts your app’s session. Then it redirects to what onResult(outcome) answers, by default the start’s returnTo (or /) on success and /signin?oidc_error=<error> on a failure. No email goes into a URL.
import { Auth } from '@_linked/auth/utils/auth';
Auth.oidcSignin = {
defaultIssuer: 'https://webid.email', // the default: emails whose domain names no issuer
allowLocalhost: false, // true only for an issuer on http://localhost
requireEmail: true, // refuse issuers that send no email claim
timeoutMs: 5000, // per request to an issuer or a profile
// The user typed A and signed in as B: refuse when A has an account here and B has none
onEmailMismatch: async ({ hinted, returned, hasAccount }) =>
(await hasAccount(hinted)) && !(await hasAccount(returned)) ? 'refuse' : 'signin',
// Where the browser goes after the callback; undefined keeps the default
onResult: (outcome) => (outcome.ok && outcome.isNewAccount ? '/welcome' : undefined),
};outcomeis{ok: true, webId, issuer, email?, emailProven, isNewAccount, returnTo?, mismatch?}or{ok: false, error, returnTo?, mismatch?}.onEmailMismatchruns when the user typed one email and the token carries another (they chose another account on webid.email).'signin', the default, signs in as the returned email;'refuse'ends withemail_mismatch. Either wayoutcome.mismatchis{hinted, returned}.hasAccount(email)looks up your accounts inside the callback only.
| error | Meaning |
|---|---|
login_required, interaction_required | A silent sign-in that needs the user |
access_denied | The user or webid.email said no |
issuer_unreachable | The issuer’s metadata, keys or token endpoint could not be reached |
issuer_refused | The WebID’s profile does not name the issuer |
invalid_token | A check on the ID token failed |
missing_claim | No webid or auth_time, or no email with requireEmail |
invalid_state | No pending sign-in for this browser, e.g. a callback older than ten minutes or opened twice |
email_mismatch | onEmailMismatch refused |
rate_limited | Too many callbacks from this address |
failed | Anything else |
5. emailProven
Any issuer can put any email in a token for its own WebIDs, so auth trusts the token’s email only when it proves the WebID. Then it is stored on the account and marked verified; otherwise it is only reported in outcome.email. Proven means email_verified is true and one of:
- the WebID is the one
Auth.webIdFor(email)derives from that email; - the token comes from your default issuer (webid.email unless you set
defaultIssuer) and the WebID is on that issuer’s origin: webid.email vouches for the emails of its own WebIDs. This is what makes webid.email’s emails count in production, where your app cannot derive its WebIDs; - with
NODE_ENVdevelopmentortestonly, any issuer’s verified email (a warning is logged each time).
Use the email for anything that matters, such as matching an invitation sent to an address, only when emailProven is true.
6. The session you get
Your app’s own @_linked/auth session, the same as after any other method: an access-token cookie (15 minutes, refreshed by the client), a rotating refresh token, at most 7 days idle and 60 days in all. webid.email’s tokens are checked and thrown away. On the client useAuth().user is the person whose id is the WebID; on the server it is request.linkedAuth.
import { useAuth } from '@_linked/auth/hooks/useAuth';
export function Me() {
const auth = useAuth();
if (auth.validating) return null;
if (!auth.user) return <a href="/signin">Sign in</a>;
// user.id is the WebID; userAccount.email is set only when the email proved that WebID
return <p>Signed in as {auth.user.id}</p>;
}Signing out of your app (useAuth().signout()) ends your session only. webid.email has no end-session endpoint: the user stays signed in there, so the next sign-in to your app is one redirect, until they sign out on webid.email.
7. Silent sign-in
prompt: 'none' asks webid.email to answer without showing a page. It comes back signed in, or to /signin?oidc_error= with:
login_required: no webid.email session in this browser, or thelogin_hintnames another account than the signed-in one;interaction_required: the account has not agreed to your app yet (webid.email answersconsent_required, which auth reports under this name), or the app is a native app.
Both mean “show the sign-in form”, without a message. Try once per visit and never again after an answer, or the page loops:
// src/hooks/useSilentSignin.ts
import { useEffect } from 'react';
import { useSearchParams } from 'react-router-dom';
import { Server } from '@_linked/server-utils/utils/Server';
const LAST_EMAIL = 'lastSigninEmail';
/** Call with the email when a sign-in starts, and with null when the user signs out here. */
export function rememberEmail(email: string | null) {
try {
if (email) localStorage.setItem(LAST_EMAIL, email);
else localStorage.removeItem(LAST_EMAIL);
} catch {
// storage blocked: no silent sign-in, nothing else changes
}
}
/** On the sign-in page: one attempt without a page, never after the callback answered. */
export function useSilentSignin() {
const [params] = useSearchParams();
useEffect(() => {
let email: string | null = null;
try {
email = localStorage.getItem(LAST_EMAIL);
} catch {
return;
}
if (!email || params.get('oidc_error')) return; // login_required, interaction_required, …
void Server.call('@_linked/auth', 'startOidcSignin', { input: email, prompt: 'none', returnTo: '/' }).then(
(answer) => {
if (typeof answer?.url === 'string') window.location.assign(answer.url);
},
);
}, []); // once, for the URL the page opened with
}Forget the email when the user signs out of your app, so signing out does not sign them straight back in.
8. Continue with Google
providerHint: 'google' is sent as provider_hint=google, and webid.email goes straight to Google (the first time, after a short note that Google will name webid.email). input may be empty: the sign-in starts at webid.email and Google decides the email. With an email, it goes along as login_hint, and when Google’s account has another email webid.email asks the user which one they meant before anything is issued. Google never becomes a sign-in method of your app: webid.email owns the Google client, and your app receives a WebID as always.
9. Native apps
A Capacitor build signs in the same way, following RFC 8252: startNativeOidcSignin opens webid.email in the system browser, never a WebView, and the issuer returns through a link your app claims (a Universal Link or App Link listed in Auth.signinClient.redirectUris). The pending sign-in is sealed by your server and held on the device, and completeOidcSignin finishes it with the tokens in the response body. See Native apps (Capacitor) in auth’s readme for the setup, the associated-domain files and the values you supply.
10. The complete minimal example
In a Linked app made with @_linked/cli, after npm install @_linked/auth and with <AppRoutes /> wrapped in <ProvideAuth> (from @_linked/auth/hooks/useAuth, in src/App.tsx), three pieces:
- The backend (
src/backend.ts):Auth.signinClientandAuth.oidcSignin = {}as in Configure. - The Vite config: the cookie prefix, as in Configure.
- The sign-in page at
/signin: the page in The email step.
With SITE_ROOT on https:, that is all: a user types an email, signs in on webid.email, agrees once, and lands on / signed in, useAuth().user.id their WebID. Create Now is the worked example of a whole app (src/backend/auth/webIdSignin.ts and src/pages/Signin.tsx in its repository): saved profiles, one silent sign-in on open, Google, and an email-mismatch choice.
Without @_linked/auth: plain Solid-OIDC
webid.email is a standard OpenID Connect provider with the Solid-OIDC profile. Any OIDC library that does the authorization code flow with PKCE and DPoP can use it.
The issuer
https://webid.email, exactly, without a trailing slash. Discovery is at https://webid.email/.well-known/openid-configuration:
authorization_endpoint | https://webid.email/oidc/auth |
|---|---|
token_endpoint | https://webid.email/oidc/token |
jwks_uri | https://webid.email/oidc/jwks (RS256 and ES256 keys) |
scopes_supported | openid, webid, email |
code_challenge_methods_supported | S256 (required) |
token_endpoint_auth_methods_supported | none: public clients only |
dpop_signing_alg_values_supported | ES256, Ed25519, EdDSA |
authorization_response_iss_parameter_supported | true: the callback carries iss |
There is no userinfo, dynamic registration or end-session endpoint.
Your client
Your client_id is the https: URL of a Client ID Document you serve, as application/ld+json or application/json (the example above is one). webid.email fetches it at the first authorization request and checks:
@contextincludeshttps://www.w3.org/ns/solid/oidc-context.jsonld, andclient_idequals the document’s own URL (no fragment, no user info);redirect_uris: the request’sredirect_urimust be one of them, exactly;http:only onlocalhost; a custom scheme marks a native app;- a public client:
token_endpoint_auth_methodisnone(or absent) and there is noclient_secret;grant_typesandresponse_types, when given, includeauthorization_codeandcode; - optional:
client_name(shown as “Sign in to …”),logo_uri,client_uri,policy_uri,tos_uri, and the theme underhttps://linked.cm/ns/signin#theme.
It is fetched without redirects, at most 64 KB within 5 seconds, from a public address, and kept as its Cache-Control says (at least 30 seconds, at most a day, five minutes without one).
The authorization request
The code flow with PKCE. Add login_hint with the email you know, prompt=none for a silent answer (login_required, consent_required, or interaction_required for a native app), prompt=login or max_age to ask for a fresh sign-in, and provider_hint=google to go straight to Google.
GET https://webid.email/oidc/auth
?response_type=code
&client_id=https%3A%2F%2Fyour.app%2Fclient.jsonld
&redirect_uri=https%3A%2F%2Fyour.app%2Fcallback
&scope=openid%20webid%20email
&state=…&nonce=…
&code_challenge=…&code_challenge_method=S256
&login_hint=ada%40example.comThe token request
It must carry a DPoP proof; without one it is refused (invalid_grant). The access token is opaque and bound to your DPoP key; a login-only client has no use for it. A browser-side client may call the token endpoint directly: CORS is answered for the origins of the client’s own redirect_uris.
POST https://webid.email/oidc/token
Content-Type: application/x-www-form-urlencoded
DPoP: <a DPoP proof JWT for POST https://webid.email/oidc/token>
grant_type=authorization_code&code=…&redirect_uri=…&client_id=…&code_verifier=…The ID token
Signed with RS256 or ES256, it carries the WebID twice, as sub and webid, the verified email, and when the user signed in to webid.email (auth_time). Only a verified email gets a token.
{
"iss": "https://webid.email",
"aud": "https://your.app/client.jsonld",
"sub": "https://webid.email/id/86806d33ba30c4df2b39599fa8babd31#me",
"webid": "https://webid.email/id/86806d33ba30c4df2b39599fa8babd31#me",
"email": "[email protected]",
"email_verified": true,
"auth_time": 1792095077,
"nonce": "Un-AXNbJTG8qxWbdKC1Qc1WThL4TUejsG_jqcDlMsrY",
"iat": 1792095077,
"exp": 1792098677
}The issuer check
Check iss against the issuer you sent the user to, then that this issuer may speak for the WebID: its profile must name iss as a solid:oidcIssuer. When iss is the root of the WebID’s own origin, as https://webid.email is for https://webid.email/id/…, the issuer vouches for it and you may skip the fetch. A webid.email profile is public and never shows the email:
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix solid: <http://www.w3.org/ns/solid/terms#>.
<https://webid.email/id/86806d33ba30c4df2b39599fa8babd31#me> a foaf:Person;
solid:oidcIssuer <https://webid.email>.On openid-client
On Node, with openid-client 6, as webid.email’s own end-to-end tests sign in:
import * as client from 'openid-client';
const ISSUER = 'https://webid.email';
const CLIENT_ID = 'https://your.app/client.jsonld'; // the URL of your Client ID Document
const REDIRECT_URI = 'https://your.app/callback'; // listed in its redirect_uris
const config = await client.discovery(new URL(ISSUER), CLIENT_ID, { token_endpoint_auth_method: 'none' }, client.None());
/** Step 1: the URL to send the browser to. Keep `pending` server-side, by `state`. */
export async function startSignin(email: string) {
const pending = {
codeVerifier: client.randomPKCECodeVerifier(),
nonce: client.randomNonce(),
state: client.randomState(),
};
const url = client.buildAuthorizationUrl(config, {
redirect_uri: REDIRECT_URI,
scope: 'openid webid email',
code_challenge: await client.calculatePKCECodeChallenge(pending.codeVerifier),
code_challenge_method: 'S256',
nonce: pending.nonce,
state: pending.state,
login_hint: email,
});
return { url: url.href, pending };
}
/** Step 2, on the callback: the code for tokens with a DPoP proof, then the WebID. */
export async function finishSignin(callbackUrl: URL, pending: { codeVerifier: string; nonce: string; state: string }) {
const tokens = await client.authorizationCodeGrant(
config,
callbackUrl,
{ pkceCodeVerifier: pending.codeVerifier, expectedNonce: pending.nonce, expectedState: pending.state, idTokenExpected: true },
undefined,
{ DPoP: client.getDPoPHandle(config, await client.randomDPoPKeyPair('ES256')) },
);
const claims = tokens.claims();
const webId = typeof claims?.webid === 'string' ? claims.webid : undefined;
// openid-client checked iss, aud, exp, nonce and the signature. The issuer check: a WebID on
// webid.email's own origin is webid.email's to vouch for; any other WebID's profile must name
// the issuer as its solid:oidcIssuer.
if (!claims || !webId || new URL(webId).origin !== ISSUER) throw new Error('not a webid.email WebID');
return { webId, email: claims.email_verified === true ? claims.email : undefined, authTime: claims.auth_time };
}Local development
Development clients on the deployed webid.email
You develop against the deployed https://webid.email. It cannot fetch a Client ID Document from your localhost, so it keeps a short list of development clients instead (today Create Now on http://localhost:4040). A listed client is labelled as one on the sign-in page and signs in only the developer accounts webid.email lists; everyone else gets access_denied. To be listed, ask the webid.email maintainers, naming your client’s origin (http://localhost:<port>) and your developers’ emails. A staging deployment of your app on https: needs no listing: webid.email fetches its document like any other.
Run your app with SITE_ROOT=http://localhost:<port>, the origin that was listed. Your app cannot compute WebIDs itself: the secret they are derived from never leaves webid.email, so rely on emailProven instead.
Switch with one variable
Which sign-in your app uses is your app’s choice, made in its own backend. Create Now does it with WEBID_MODE: production signs in through the deployed webid.email, bypass signs in without any issuer, for working offline. Changing the mode is a restart. Cookie names do not depend on it, so nothing else changes.
// src/backend.ts, at module load
import { Auth } from '@_linked/auth/utils/auth';
Auth.signinClient = { clientName: 'Your App' };
if (process.env.WEBID_MODE === 'production') {
// The deployed webid.email; your localhost client must be a listed development client
Auth.oidcSignin = { defaultIssuer: 'https://webid.email' };
}
// Any other mode is your app's own, e.g. Create Now's bypass, which signs in without an issuerCodes arrive by email
A sign-in from a development client is a real sign-in. The code is mailed to the developer’s address, as for any user, so use an account whose inbox you can read (or Google, or a password set on that account). There is no log to read the code from.
FAQ
- Is it one email, one WebID?
- Yes. The WebID is derived from the email (trimmed and lowercased), so the same email is the same WebID in every app and on every device. Another email is another WebID. The WebID does not contain the email, and the email cannot be worked out from it.
- What happens on an email mismatch?
- Two places can see one. On webid.email: an app hinted A and the user continued with a Google account whose email is B. Nothing is issued until the user chooses: try Google again, sign in as A another way, or continue as B. In your app: the user typed A and the token carries B (they continued as B, or signed in as another account).
onEmailMismatchdecides: by default the user is signed in as B andoutcome.mismatchsays so;'refuse'ends withemail_mismatch. Create Now refuses whenever A already has an account there, and then lets the user choose between A and B. - What does webid.email store?
- The email and whether it is verified, how the user signs in (a password hash if they set one, the Google account id if they use Google), their sessions, and which apps they agreed to and when. Sign-in codes, sign-ins in progress and rate-limit counters expire within minutes to hours. The WebID is computed, not stored. Your app receives the WebID and the email (
webid,email,email_verified,auth_time), and the name if the user gave webid.email one (name,given_name,family_name), only after the user agreed for your app. The privacy policy has the details. - How does a user take back consent?
- Not one app at a time yet: listing and removing the apps an account agreed to is planned. Today the account page lets the user download their data, which lists those apps, and delete the account, which deletes every consent with it; anything else goes to [email protected]. Signing out of webid.email stops silent sign-ins in that browser but keeps the consents. Your app’s own session ends when the user signs out of your app.
- Do I register my app anywhere?
- No. Your Client ID Document is your registration; change it and webid.email follows within its cache time.