Sign-in for other sites (OpenID Connect)

Section: Panel → Integrations → Sign-in for other sites. It is off by default: until you turn it on, the provider addresses answer “not found”, and the pages have no links or buttons.

What opens when you turn it on

• People with an account on your site can sign in to the connected sites by pressing “Allow” on the consent page (it shows the name of the site and the address where the person will return).
• The other site gets not a password but a signed confirmation “this is them” and (only with the person’s consent) the name, nickname, language, picture and the confirmed email.
• Each other site knows the person under its own number: two sites cannot match one person by this number.
• A person withdraws the permission at any time in their account (“Connected sites”); you can withdraw everything from a particular site at once.

Before turning it on, add a paragraph to the privacy policy saying that when a person signs in through your site, the connected sites receive the name, nickname, language, picture and confirmed email — only with the person’s consent.

Conditions for turning it on

• The site address in the settings is https://… (on a test stand http://127.0.0.1 is allowed).
• The site key (app.key) exists — it encrypts the signing key.
• The openssl extension works on the hosting.
• You need the right “change settings” and the password once more.

Changing app.key or moving the database to a site with another key resets the signing key: it is created anew, and the connected sites fetch the new set of keys by themselves.

How to connect your site

1. In the section press “Add a client”, enter a name and the exact return addresses (one per line): https://shop.example/auth/callback. No wildcards (*), no addresses with # or http://. The type: “with a secret” (a server application) or “public” (a single-page application, no secret — PKCE protects it).
2. Copy client_id and client_secret — the secret is shown once; if you lose it, press “New secret”.
3. In the settings of the other site (any OpenID Connect library) give the provider address — the address of your site. The library finds everything else by itself at https://your-site/.well-known/openid-configuration.
4. Scopes: openid (required), profile (name, nickname, language, picture), email (the confirmed email).

If there is no library, the flow is this (authorization code + PKCE):

1. The site creates a random code_verifier and computes code_challenge = BASE64URL(SHA256(code_verifier)).
2. It sends the person to …/oauth/authorize?client_id=…&redirect_uri=…&response_type=code&scope=openid%20profile%20email&state=…&code_challenge=…&code_challenge_method=S256&nonce=…. All the parameters are needed; state and PKCE S256 are required, plain is not supported.
3. After consent the person returns to redirect_uri with code, state and iss. The site checks state and iss.
4. The server of the site exchanges the code: POST …/oauth/token (grant_type=authorization_code, code, redirect_uri, code_verifier; the secret — in the header Authorization: Basic or in the field client_secret). The code lives 60 seconds and is used once; presenting it again withdraws everything issued by it.
5. The answer holds id_token (RS256) and access_token (10 minutes). The id_token is checked with the keys from /.well-known/jwks.json: iss, aud (your client_id), exp, nonce, the signature. The permanent number of the person on your site is sub.
6. The profile data: GET …/oauth/userinfo with the header Authorization: Bearer <access_token> (a token in the address is not accepted).
7. To withdraw a token: POST …/oauth/revoke (token, the client secret).

There are no refresh tokens (refresh_token) in the first release: after 10 minutes the site sends the person to sign in again (if the permission is valid, the person sees no question).

What is forbidden on purpose

• Accounts with panel access and the owner do not sign in through other sites until you tick “Allow accounts with panel access” for that particular site; and they need a fresh sign-in (within 10 minutes) — or the password once more. If such an account has the second check on, the password does not replace it: the site gets the answer login_required, and the person signs in again and repeats.
• The authorization and consent pages cannot be put in a frame; prompt=none does not work in a frame.
• Consent is required for all sites; it lasts 12 months; a new scope needs new consent.
• http:// addresses never work on a live site (the “development” flag works only on a test stand).
• A blocked or deleted person, a password change, a change of the second check, withdrawn consent, a site turned off — the tokens stop working at once.

If something goes wrong

• “Cannot sign in”: the client is unknown or off, the return address did not match letter for letter, there is no state — look at the section “Sign-in for other sites” and the settings of the other site.
• Error answers come to the return address as error=… (invalid_request, invalid_scope, access_denied, login_required, consent_required, unsupported_response_type); /oauth/token gives invalid_client, invalid_grant, unsupported_grant_type without details.
• The security journal: oauth.consent_granted, oauth.consent_denied, oauth.consent_revoked, oauth.code_replayed (a repeated code is a reason to check the client site), oauth.confirm_failed. The panel journal: creating, changing and turning off clients, changing the secret and the key, “Withdraw from everyone”. All owners get a letter about each such action.
• Changing the signing key (“Rotate the signing key” in the section) is safe: the old key stays in the set for two more hours, until the issued tokens expire.