Connect your website
Use Presence as an OpenID Connect provider in your existing authentication system.
Setup for Next.js, Node.js, Keycloak and company directories
1. Create a Test application
Open Enterprise → Integrations → Add website. Enter your domain and the exact callback URL supplied by your authentication library. Local development may use an HTTP localhost callback. Save the client secret once; it cannot be displayed again.
2. Configure OpenID Connect
Copy the issuer URL and client ID from the application. Use authorization code flow with PKCE S256, client_secret_basic and the scopes openid profile email. Store the client secret only on your server. Discovery supplies the authorization, token, JWKS, UserInfo, introspection and revocation endpoints.
3. Run the example
Download the runnable Node.js website. It uses the independent openid-client library, validates state, nonce, issuer and audience, and keeps tokens in encrypted HttpOnly cookies.
npm install openid-client@6.8.8 node --env-file=.env oidc-website.mjs
Your local .env:
PRESENCE_ISSUER=copy-from-your-application PRESENCE_CLIENT_ID=copy-from-your-application PRESENCE_CLIENT_SECRET=your-private-client-secret WEBSITE_ORIGIN=http://127.0.0.1:4344 WEBSITE_COOKIE_KEY=32-random-bytes-in-base64url PRESENCE_REPORT_SESSION=true
Register http://127.0.0.1:4344/callback as the callback. Generate the cookie key with node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))". Open the website, choose Sign in with Presence, connect a Key if needed, and approve the request.
4. Map the account safely
Use the pair of issuer and subject (iss, sub) as the identity. Never merge accounts because email addresses match. Linking an existing account requires authentication to that account and explicit confirmation. A Presence sign-in does not grant membership or a role in your application.
5. Handle changes and interruptions
Handle access_denied, expired requests and network interruptions with a way to start again. Access and ID tokens last five minutes. Check token activity on protected requests if Key or application revocation must end access immediately; an ID token alone cannot invalidate your website’s session. The example demonstrates introspection and local logout with token revocation. Refresh tokens and provider-wide single logout are not offered in this release.
6. Prepare Live
Create a separate Live application, register HTTPS callback URLs and add its DNS TXT record. Verify ownership in Presence. Use separate client secrets for Test and Live. Use the exact issuer shown in the application; Preview credentials cannot access production.
7. Verify the whole connection
Enterprise shows four steps: configuration, domain ownership, a website session and an ongoing access check. A Presence approval alone does not prove that your callback worked. The example reports both session creation and subsequent checks automatically when PRESENCE_REPORT_SESSION=true. Check connection refreshes the result. Changing application configuration requires another test.
8. Decide who can sign in
Choose Customers for any verified Presence account, Members for existing organization members, or Only assigned people or groups for a managed workforce. Add people with their verified work email, assign groups, and optionally set an end date. Directory entries do not create accounts or send email. A suspension or expired company end date always overrides an application assignment.
Session reporting for your own server
POST JSON to /api/integration/report on the issuer’s origin using HTTP Basic with your OIDC client ID and secret. Send {"event":"session","accessToken":"…"} only after you create your own authenticated session. Store the returned receipt server-side with that session. On protected requests send {"event":"check","accessToken":"…","receipt":"…"}. Deny access when active is false. On timeout, deny the protected action and offer a retry. The receipt expires after one hour; access tokens expire after five minutes. Never expose tokens, receipts or secrets to your frontend or logs. Reports are authenticated statements from your server, not independent certification.
The example performs standard OIDC introspection on every protected page and reports the result. Integrations that cache introspection accept the associated revocation delay. Already displayed pages and data cannot be recalled; protected requests must be checked. No logout delivery to every browser is claimed.
Diagnose a failed sign-in
Open Activity → Sign-ins and search the support reference. It distinguishes a pending approval, refusal, expired request, access policy denial, callback failure, and revoked access awaiting the website’s acknowledgement. Missing client secrets, wrong PKCE verifiers and unregistered callbacks are rejected. Diagnostics contain no scan images, passkey responses or tokens. Sign-in diagnostics are retained for 30 days.
Privacy and assurance
The website receives an application-specific identifier and requested profile claims. Key images, Key identifiers and organization memberships are not shared. Presence Enterprise requires a Key scan and passkey confirmation. The passkey remains until the native app is available. A scan matches an optical pattern; it does not prove the originality of the physical object. Verify iss, aud, nonce, amr and acr with your OIDC library. Expected assurance is urn:4si:presence:optical-pattern-passkey:v1.