Sign in with OpenID Connect
Leyla can put a “Continue with …” button on its sign-in page for each identity provider you run, such as Authentik, Authelia, Keycloak, Kanidm, Zitadel or Pocket ID, or use, such as Google or Microsoft. Passwords keep working whatever the provider does, so the first administrator can always get in.
Add a provider
Create a client at your provider
Leyla uses the authorization code flow with PKCE. Make a confidential client and note its client ID and secret. A public client with no secret works too.
Register the redirect address
Register this at the provider, once for every address people reach Leyla by: the public one, and the home-network one if people use it.
https://<the address people use>/api/v1/auth/oidc/callbackThe Leyla apps sign in through the same address, so there is nothing more to register for them.
Fill in the provider in Leyla
Open Administration › Settings › Sign-in › Sign-in providers › Add a provider and fill in the fields below.
Press Check
Check asks the provider, without signing anyone in: its discovery document, its keys, whether it takes PKCE, whether it accepts the redirect address you are on, and whether it takes the client ID and secret. Run it after every change at the provider.
The fields
| Field | What to put |
|---|---|
| Name on the button | What people see: “Continue with {name}”. |
| Issuer | The provider’s issuer, exactly as its /.well-known/openid-configuration says it. A trailing / does not matter. |
| Client ID, Client secret | From the provider. The secret is never shown again. |
| Scopes | openid profile email, the default. |
| Claim with the account name | preferred_username, the default, or email when your Leyla account names are email addresses. Pick a claim people cannot change themselves at the provider. |
| Someone with no account here | Is turned away, the default: the identity signs in only to the account of its name, or to the account it is linked to. Gets an account: a name with no account gets one, and it is not an administrator. |
| Claim with the groups | groups, the default. It is read only when one of the next two fields is filled. |
| Groups that may sign in | One group name per line. Empty, the default, means anyone the provider signs in. |
| Administrator group | A group whose members are Leyla administrators. Empty, the default, means the provider has no say. |
| Signing out of Leyla signs out at the provider too | On by default. See Signing out. |
Who may sign in, and who is an administrator
Who may sign in is decided at the provider, by binding the application to a group there. If you fill in Groups that may sign in, Leyla checks too: someone whose groups claim names none of those groups is turned away before any account is linked or made, and so is someone whose token has no groups claim at all.
Tip Group names are compared exactly, so write them as the provider sends them. Keycloak sends paths such as /leyla-family unless its mapper’s “Full group path” is off.
Fill in Administrator group and its members are Leyla administrators from their next sign-in. Someone who leaves the group stops being an administrator at their next sign-in, if this provider made their account.
An account that was already here keeps the role it has: the first administrator, an imported account, or one linked by name. A provider can never lock the household’s own administrator out, and the server’s last administrator is never demoted.
Signing out
Signing out of Leyla signs out at the provider too, where the provider offers an end-session endpoint. The browser goes to the provider and comes back to Leyla’s sign-in page. Register both of these at the provider as post-logout redirect addresses, once per address people use:
https://<the address people use>/signin # the web
https://<the address people use>/auth/oidc?app=1&result=signed_out # the appsWith neither registered, the provider stops on its own page. A provider that checks them exactly, such as Authentik, refuses a sign-out whose return address it does not have, and its session stays.
Turn the switch off for a provider and signing out ends the Leyla session only. On a shared browser, the next “Continue with …” then signs the same person in without asking.
What Leyla keeps
The session is Leyla’s own, exactly as a password sign-in gets one: 30 days, sliding. It needs no refresh token, and a provider’s short token lifetimes do not sign anyone out of Leyla.
On the session Leyla keeps which provider signed it in and the ID token from that sign-in, only so that signing out can hand it back to the provider. It keeps no access token and no refresh token. The ID token is cleared when the session ends, when you turn the provider’s sign-out off, and when you remove the provider.
Authentik, step by step
These settings were walked end to end against Authentik 2026.8.4.
Create the provider
Under Applications › Providers › Create, choose OAuth2/OpenID Provider.
Setting Value Authorization flow default-provider-authorization-implicit-consentClient type Confidential. Copy the Client ID and Client Secret into Leyla. Redirect URIs Strict, one line per address: https://leyla.example.com/api/v1/auth/oidc/callback. Add the two sign-out addresses above with the type Logout.Invalidation flow default-invalidation-flow, named “Logout”. The flow Authentik picks for a new provider leaves its own session signed in.Signing Key authentik Self-signed Certificate, or any RSA or EC keyScopes The default mappings: openid, email and profile Subject mode Any. Do not change it once people have signed in. Create the application
Under Applications › Applications › Create, give it a name, the slug
leylaand the provider above. To let only some people in, bind the application to a group, such asleyla-family.Fill in Leyla
- Issuer
https://auth.example.com/application/o/leyla/- Scopes
openid profile email- Claim with the account name
preferred_username. Authentik sendsemail_verified: falseby default, and an unverified address names nobody.
Groups, if you want them
Authentik’s default profile mapping already puts every group the person is in into
groups. Putleyla-familyin “Groups that may sign in” andleyla-adminsin “Administrator group”, and nothing more is needed.
In a blueprint A blueprint must list grant_types: [authorization_code]. Without it every sign-in ends, after the password, with OIDC_PROVIDER_REFUSED, and Check cannot see it.
When it does not work
| Leyla says | Usually |
|---|---|
OIDC_PROVIDER_UNREACHABLE | Leyla cannot reach the issuer address, or the provider answered with an error. Leyla must reach the provider at the same address the browser does. |
OIDC_ISSUER_MISMATCH | The issuer typed in Leyla is not the one in the discovery document. Check the slug, and http against https. |
OIDC_PROVIDER_REFUSED | The provider sent the browser back with an error. Leyla’s log has its error and error_description. |
OIDC_EXCHANGE_FAILED | The provider refused the code exchange: a wrong client secret, or a redirect address that differs. Check says which. |
OIDC_NO_ACCOUNT | “Is turned away” is set and no Leyla account has that name. Make the account, or let the provider make accounts. |
OIDC_NOT_IN_GROUP | The person is in none of “Groups that may sign in”, or the token has no groups claim. Check the group names, the claim name, and that the scope carrying the claim is in Leyla’s Scopes. |
| The provider says the redirect URI is invalid | The address you opened Leyla at is not in the provider’s redirect addresses. |
Something missing or wrong here? Tell us.