# Sign-in and OAuth

Source: https://frameleaf.app/docs/admin/sign-in-and-oauth/

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](https://frameleaf.app/docs/cloud/account/#sign-in-with-frameleaf-on-your-server).

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](https://frameleaf.app/docs/using/account-settings/#passkeys).

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

:::tip[Locked out?]
You can always turn password login back on from the server:

```bash
docker exec frameleaf_server frameleaf-admin enable-password-login
```

`disable-password-login`, `enable-oauth-login` and `disable-oauth-login` work the same way. See [Server commands](https://frameleaf.app/docs/admin/server-commands/). The same steps are at the foot of **Sign-in methods**, under **If nobody can sign in**, with **Show the commands**.
:::

Passwords are at least 8 characters.

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

## 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](https://frameleaf.app/docs/using/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](https://frameleaf.app/docs/admin/users/#two-step-sign-in).

Two-step sign-in protects signing in with a server password, on the web and in the apps. A [passkey](https://frameleaf.app/docs/using/account-settings/#passkeys) 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](https://frameleaf.app/docs/cloud/account/#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

**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](https://frameleaf.app/docs/using/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](https://frameleaf.app/docs/admin/server-commands/#sign-in-options).

**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

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

### 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

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

- **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](https://frameleaf.app/docs/using/notifications/#new-sign-in-emails).

:::note[Behind a reverse proxy]
Frameleaf counts tries by the visitor's address. A reverse proxy on your home network is trusted to pass that address on. If your proxy is somewhere else, for example on a Tailscale address, set `FRAMELEAF_TRUSTED_PROXIES` to its address, or every visitor shares the proxy's count. See [Environment variables](https://frameleaf.app/docs/admin/environment-variables/).
:::

## Set up your own provider

### 1. Create a client at your provider

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

### 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**.

:::note[Provider won't accept an app address?]
Some providers only accept `http` or `https` redirect URIs. Use the [mobile redirect override](#mobile-redirect-override) instead.
:::

### 2. Turn on your provider in Frameleaf

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](https://frameleaf.app/docs/admin/users/#storage-labels) | `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](#mobile-redirect-override) | 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](https://frameleaf.app/docs/admin/users/#space-for-new-people), unless the provider sends a space claim.

:::caution[Changing provider]
Under **Advanced**, select **Disconnect everyone…** before you move to a different provider, so people can connect to the new one. Their accounts and photos stay.
:::

## 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

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

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

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.

:::note[Frameleaf app support]
The iPhone, Android and Desktop apps sign in with your provider too. Each shows a button with the text you set in **Words on the sign-in button**, and opens the provider's sign-in page; a server that offers only its provider works. When those words are left empty, the Android app says **Sign in with your organisation** and the iPhone app says **Sign In with This Server's Provider**. See [iPhone app](https://frameleaf.app/docs/apps/iphone/), [Android app](https://frameleaf.app/docs/apps/android/) and [Desktop app](https://frameleaf.app/docs/apps/desktop/).
:::

## Examples

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

### 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

This client also passes an optional `frameleaf_quota` claim from an LDAP attribute called `frameleafquota`:

```yaml
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

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` |

### Google

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` |
