Sign-in and OAuth
Single sign-on for Frameleaf: connect Keycloak, Authentik or your own provider Watch on YouTube
Let people sign in the way they already do. Connect the identity provider you run, and everyone uses one familiar account for Frameleaf. People can sign in to your server in three ways, side by side:
- Email and password, the default.
- Your own identity provider through OAuth (OpenID Connect), such as Authentik, Authelia, Keycloak, Okta or Google.
- Sign in with Frameleaf, once your server is linked to Frameleaf Cloud. See Frameleaf Cloud account.
All three are set in Settings, then Who can sign in. Sign-in methods starts with the answer, such as People can sign in two ways, and lists them under Ways to sign in: Password, Frameleaf account and Another sign-in provider.
On top of these, each person can add a passkey to their own account and sign in with Sign in with a passkey. There’s nothing to turn on; passkeys need your server’s https address. See Passkeys.
Password login
Section titled “Password login”Under Ways to sign in, Password turns password sign-in on or off for the whole server. When it’s off, nobody can sign in with a password, including administrators, and the page warns Password sign-in is off: if Frameleaf Cloud or your provider is unreachable, nobody can sign in at home until it’s back. If every way is off, the page says Nobody can sign in. Don’t turn passwords off until an administrator has signed in another way. Changing it doesn’t sign out anyone already signed in.
Passwords are at least 8 characters.
A password for the owner of a linked server
Section titled “A password for the owner of a linked server”Setting a server up in the browser always creates an administrator with a password first. A server set up from the Frameleaf app by linking it to your Frameleaf account is different: its administrator account has no server password at first. Right after you sign in with Frameleaf on the web, the page asks you to Set a password for this library, so you can still sign in when your Frameleaf account is unavailable. The iPhone and Android apps ask for it while you pair, with the same warning on http.
- Enter a New password, at least 8 characters, and type it again under Confirm new password.
- Select Save password and continue. Your other devices are signed out, and you carry on to the page you were opening.
On an http address the page warns first: “This connection uses HTTP. Your password will be sent without encryption. Continue only on a trusted local network.” You can still continue. Sign out instead leaves without setting a password.
Only the Frameleaf account that owns the linked server is asked, and only within 10 minutes of that sign-in.
Two-step sign-in
Section titled “Two-step sign-in”Anyone who signs in with a password can add a 6-digit code from an authenticator app on their phone. Each person turns it on for themselves in Settings, then Your sign-in & privacy, then Two-step sign-in. See Two-step sign-in.
If someone loses their phone and their recovery codes, open them in Users and select Turn off two-step sign-in…. It’s noted in their account history, with your name. See Users.
Two-step sign-in protects signing in with a server password, on the web and in the apps. A passkey sign-in skips the code, because the passkey already proves it’s you. It never asks for a code with Sign in with Frameleaf, which uses your Frameleaf account’s own security (see Sign in), or with your own provider, which uses its own security, including any two-step sign-in you set up there.
Require a passkey or two-step
Section titled “Require a passkey or two-step”Settings, then Who can sign in, then Sign-in methods has Require a passkey or two-step. A sign-in meets it with a passkey by itself, or with any two of password, emailed code and authenticator code. A Sign in with Frameleaf counts when your Frameleaf account signed in that way.
Who must chooses who needs it:
| Choice | What it means |
|---|---|
| Administrators away from home | The default. Away from home, an administrator needs it to use the server’s administrator pages. Everyone else signs in as before |
| Everyone away from home | Everyone signing in away from home needs it |
| Everyone, everywhere | Everyone needs it, at home too. Someone with only a password has to turn on two-step sign-in before they can use anything else |
Everyone not covered by your choice can still sign in with one step.
To choose Everyone, everywhere, password sign-in must be on, and your own account here needs a passkey, or a password with two-step sign-in. Otherwise saving is refused, so the setting can’t lock you out. If it does go wrong, reset-sign-in-policy puts it back to Administrators away from home; see Server commands.
Apply to older apps too (off): older apps, and sessions that were signed in before this setting, keep working as they did until you turn this on.
Wrong passwords and waits
Section titled “Wrong passwords and waits”Frameleaf slows down anyone guessing passwords, without ever locking the owner out. Two things work together.
A growing wait after wrong passwords
Section titled “A growing wait after wrong passwords”After 5 wrong passwords in a row for an account, Frameleaf waits before it checks another password for that account. Each further wrong password doubles the wait:
| Wrong passwords in a row | Wait before the next try |
|---|---|
| 1 to 4 | None |
| 5 | 30 seconds |
| 6 | 1 minute |
| 7 | 2 minutes |
| 8 | 4 minutes |
| 9 | 8 minutes |
| 10 | 16 minutes |
| 11 or more | 30 minutes, the longest wait |
- The wait counts from the last wrong password. Tries during a wait aren’t checked and don’t make it longer.
- The right password clears the count. Wrong passwords are also forgotten an hour after the last one.
- Wrong passwords count per account from the address they came from, and per account from every address, so a guesser can’t get round the wait by changing address.
- Wrong two-step codes have their own wait in the same way, per account and address.
Limits on sign-in tries
Section titled “Limits on sign-in tries”On top of the wait, each address has limits in any 10 minutes:
| What | Limit |
|---|---|
| Password sign-in tries from one address | 30 |
| Wrong passwords for one email from one address | 10. Right passwords don’t count |
| Two-step code tries from one address | 10 |
| Wrong two-step codes in one sign-in, from any address | 5, then the sign-in pauses for 10 minutes |
| Turning two-step sign-in on or off, moving it, or making new codes | 30 per address and 10 per signed-in session |
Going over a limit shows “Too many requests. Try again later.” until the 10 minutes are up.
Why this never locks you out
Section titled “Why this never locks you out”- It’s always a wait, never a lock. The longest is 30 minutes. Nobody has to unlock an account, and the password keeps working.
- Your own address keeps its own count. The limit of 10 wrong passwords counts per email and address, so wrong passwords from somewhere else never use up yours at home.
- Other ways in still work. A password wait holds back only passwords for that account. Devices that are already signed in stay signed in, and passkeys and Sign in with Frameleaf are never held back.
After 20 wrong passwords or codes for an account within an hour, from any address, its owner gets a notice in the app and by email: Someone tried to sign in to your account. See Notifications.
Set up your own provider
Section titled “Set up your own provider”1. Create a client at your provider
Section titled “1. Create a client at your provider”Every provider follows the same pattern:
- Create a new application or client.
- Provider type: OpenID Connect or OAuth2
- Client type: Confidential
- Application type: Web
- Grant type: Authorization Code
- Add the redirect URIs listed below.
- If the provider supports it, set the back-channel logout URL to
https://photos.example.com/api/oauth/backchannel-logout. - Copy the client ID and client secret.
Redirect URIs
Section titled “Redirect URIs”Add these for every address you use to reach the server, such as http://localhost:2283, http://192.168.0.200:2283 and https://photos.example.com:
| Redirect URI | What it’s for |
|---|---|
https://photos.example.com/auth/login |
Signing in on the web |
https://photos.example.com/user-settings |
Linking an existing account to the provider on the web |
frameleaf-auth:///oauth-callback |
Signing in from the Frameleaf app |
Settings, then Who can sign in, then Sign-in methods lists the exact addresses for your server under Addresses to allow at your provider, ready to copy: Signing in on the web, Connecting an account you already have and Signing in on the Frameleaf app.
2. Turn on your provider in Frameleaf
Section titled “2. Turn on your provider in Frameleaf”- Open Settings, then Who can sign in, then Sign-in methods.
- Under Ways to sign in, turn on Another sign-in provider.
- Under Connect your provider, enter the Provider address (Issuer URL) and the Client ID. For OAuth client secret, select Replace credential; it’s stored write-only and only ever shows Stored or Not set.
- Select Check. Frameleaf asks the provider to introduce itself and says Found your provider with its name, or what went wrong.
- Select Save changes.
Most providers need nothing more. The other settings already have values that work with most providers:
| Setting | What it does | Default |
|---|---|---|
| Provider address (Issuer URL) | Your provider’s discovery address. /.well-known/openid-configuration is added automatically if you leave it off |
Required |
| Client ID | From your provider | Required |
| OAuth client secret | From your provider | Required |
| Create accounts automatically | Create an account the first time someone signs in. Off: only people you’ve added can sign in | On |
| Words on the sign-in button | Text on the sign-in button | Sign in with your provider |
Under Advanced:
| Setting | What it does | Default |
|---|---|---|
| How Frameleaf proves itself | How the client authenticates to the provider (token_endpoint_auth_method): Client secret in the request (client_secret_post) or Client secret in the request header (client_secret_basic) |
Client secret in the request |
| Information requested | Scopes to request, separated by spaces | openid email profile |
| Signature on the sign-in token | Algorithm the ID token is signed with (id_token_signed_response_alg), such as RS256 |
RS256 |
| Signature on profile details | Algorithm the userinfo response is signed with (userinfo_signed_response_alg) |
none |
| What the provider asks each time | The prompt sent to the provider, for example select_account, login or consent |
Empty |
| Sign-out address | Another sign-out address at your provider (end_session_endpoint) |
Empty |
| Wait for the provider | Seconds to wait for the provider | 30 |
| Allow a provider without a valid security certificate | Turns off certificate checks for requests to the provider. Only for a provider on your own home network, because it leaves sign-ins open to interception | Off |
| Go straight to the provider | Skip the sign-in page and go straight to the provider | Off |
| Folder name from provider | Claim used for the person’s storage label | preferred_username |
| Administrator from provider | Claim that makes someone an administrator. It should be user or admin |
frameleaf_role |
| Space limit from provider | Claim holding the person’s space in GB | frameleaf_quota |
| Account Management URL | Where people manage their profile at your provider | Empty |
| Sign-in address for an older app | See below | Off |
The folder name, administrator and space claims are read once, when an account is created; later changes at your provider don’t update the account. The claim name only has to match what your provider sends.
New accounts start with Space for new people, set under Users, unless the provider sends a space claim.
Verified email addresses
Section titled “Verified email addresses”An email address from your provider is used to link a sign-in to an existing account, or to create a new account, only when the provider says it’s verified: the email_verified claim must be true. A sign-in with an unverified address, or without the claim, is refused with a message saying why.
Some providers, such as Microsoft Entra ID, don’t send email_verified. With them, people whose accounts aren’t linked yet can’t sign in by email, and automatic registration is refused, until you map an email_verified claim at the provider. Accounts already linked by their provider ID keep signing in as before.
Refused and expired sign-ins
Section titled “Refused and expired sign-ins”A sign-in only finishes in the browser or app that started it, within the provider’s time limit. Otherwise nobody is signed in and the sign-in page shows one of these:
| Message | Why |
|---|---|
| The identity provider did not approve the sign-in | The person declined, or the provider refused |
| This sign-in was started somewhere else or has expired | The callback belongs to a different sign-in |
| This sign-in link has expired or was already used | The code was used already, expired or didn’t match |
Frameleaf shows these messages in place of the provider’s own error text. A callback that opens in another tab of the same browser, for example from an email link, still finishes for 15 minutes.
Auto launch
Section titled “Auto launch”With Go straight to the provider on, the sign-in page goes straight to your provider. To reach the normal sign-in page, use the browser’s back button or open /auth/login?autoLaunch=0. You can also auto launch for a single visit with /auth/login?autoLaunch=1, which is handy when Frameleaf is embedded in another site that already signs people in.
Mobile redirect override
Section titled “Mobile redirect override”If your provider won’t accept an app address such as frameleaf-auth:///oauth-callback:
- Under Advanced, turn on Sign-in address for an older app.
- Set Mobile redirect URI to your server’s
/api/oauth/frameleaf-mobile-redirectaddress, for examplehttps://photos.example.com/api/oauth/frameleaf-mobile-redirect, and allow that address with your provider. Frameleaf forwards it toframeleaf-auth:///oauth-callback.
Any other override address can’t be matched to this server, and sign-in from the app is refused.
Examples
Section titled “Examples”These show the Frameleaf side of a working setup. Replace photos.example.com and the provider address with your own.
Authentik
Section titled “Authentik”In the provider’s Protocol settings, set Client type to Confidential, add your redirect URIs one per line, and copy the client ID and secret.
| Setting | Value |
|---|---|
| Provider address (Issuer URL) | https://authentik.example.com/application/o/frameleaf/ |
| Information requested | openid email profile |
| Signature on the sign-in token | RS256 |
| Folder name from provider | preferred_username |
| Space limit from provider | frameleaf_quota |
| Words on the sign-in button | Sign in with Authentik (optional) |
Authelia
Section titled “Authelia”This client also passes an optional frameleaf_quota claim from an LDAP attribute called frameleafquota:
authentication_backend: ldap: attributes: extra: frameleafquota: name: 'frameleaf_quota' multi_valued: false value_type: 'integer'identity_providers: oidc: claims_policies: frameleaf_policy: custom_claims: frameleaf_quota: attribute: 'frameleaf_quota' scopes: frameleaf_scope: claims: - 'frameleaf_quota' clients: - client_id: 'frameleaf' client_name: 'Frameleaf' client_secret: '<hashed client secret>' public: false require_pkce: true pkce_challenge_method: 'S256' redirect_uris: - 'https://photos.example.com/auth/login' - 'https://photos.example.com/user-settings' - 'frameleaf-auth:///oauth-callback' scopes: ['openid', 'profile', 'email', 'frameleaf_scope'] claims_policy: 'frameleaf_policy' response_types: ['code'] grant_types: ['authorization_code'] id_token_signed_response_alg: 'RS256' userinfo_signed_response_alg: 'RS256' token_endpoint_auth_method: 'client_secret_post'| Setting | Value |
|---|---|
| Provider address (Issuer URL) | https://auth.example.com |
| Client ID | frameleaf |
| How Frameleaf proves itself | Client secret in the request |
| Information requested | openid email profile frameleaf_scope |
| Signature on the sign-in token | RS256 |
| Signature on profile details | RS256 |
| Sign-out address | https://auth.example.com/logout?rd=https://photos.example.com/ |
| Folder name from provider | uid |
| Space limit from provider | frameleaf_quota |
Keycloak
Section titled “Keycloak”- Create an OpenID Connect client in your realm and set its Client ID, for example
frameleaf. - Under Access settings, set Root URL, Home URL and Admin URL to your server address. Add your redirect URIs to Valid redirect URIs, and set Valid post logout redirect URIs and Web origins to
+. - Turn on Client authentication so the client is confidential, and copy the secret from Clients, then your client, then Credentials.
- To manage roles, create a client role mapper with the claim name
frameleaf_role.
| Setting | Value |
|---|---|
| Provider address (Issuer URL) | https://<keycloak-domain>/realms/<your-realm> |
| Client ID | frameleaf |
| Information requested | openid email profile |
| Signature on the sign-in token | RS256 |
| Administrator from provider | frameleaf_role |
| Words on the sign-in button | Sign in with Keycloak |
In the OAuth client’s Authorised redirect URIs, add https://photos.example.com/auth/login, https://photos.example.com/user-settings and https://photos.example.com/api/oauth/frameleaf-mobile-redirect. Google needs the mobile redirect override. Google says changes can take from five minutes to a few hours to apply.
| Setting | Value |
|---|---|
| Provider address (Issuer URL) | https://accounts.google.com |
| Information requested | openid email profile |
| Signature on the sign-in token | RS256 |
| Sign-in address for an older app | On |
| Mobile redirect URI | https://photos.example.com/api/oauth/frameleaf-mobile-redirect |
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.
