Skip to content

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.

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.

  1. Enter a New password, at least 8 characters, and type it again under Confirm new password.
  2. 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.

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.

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.

Frameleaf slows down anyone guessing passwords, without ever locking the owner out. Two things work together.

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.

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.

  • 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.

Every provider follows the same pattern:

  1. Create a new application or client.
    • Provider type: OpenID Connect or OAuth2
    • Client type: Confidential
    • Application type: Web
    • Grant type: Authorization Code
  2. Add the redirect URIs listed below.
  3. If the provider supports it, set the back-channel logout URL to https://photos.example.com/api/oauth/backchannel-logout.
  4. Copy the client ID and client secret.

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.

  1. Open Settings, then Who can sign in, then Sign-in methods.
  2. Under Ways to sign in, turn on Another sign-in provider.
  3. 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.
  4. Select Check. Frameleaf asks the provider to introduce itself and says Found your provider with its name, or what went wrong.
  5. 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.

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.

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.

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.

If your provider won’t accept an app address such as frameleaf-auth:///oauth-callback:

  1. Under Advanced, turn on Sign-in address for an older app.
  2. Set Mobile redirect URI to your server’s /api/oauth/frameleaf-mobile-redirect address, for example https://photos.example.com/api/oauth/frameleaf-mobile-redirect, and allow that address with your provider. Frameleaf forwards it to frameleaf-auth:///oauth-callback.

Any other override address can’t be matched to this server, and sign-in from the app is refused.

These show the Frameleaf side of a working setup. Replace photos.example.com and the provider address with your own.

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)

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
  1. Create an OpenID Connect client in your realm and set its Client ID, for example frameleaf.
  2. 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 +.
  3. Turn on Client authentication so the client is confidential, and copy the secret from Clients, then your client, then Credentials.
  4. 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