Sign-in and access

People sign in to Oleafly Server through providers you configure, so the server never handles passwords. You decide who gets in with access rules. Admins manage the rest from the admin console in Oleafly.

Sign-in providers

Configure at least one provider. The server won’t start without one, and its log names the settings to add. The first admin signs in with it, because sign-in by email link stays off until an admin turns it on. Each provider sends people back to a callback address on your server:

https://collab.example.org/auth/callback/<provider>

If OLEAFLY_PUBLIC_URL has a path, so does the callback address, for example https://www.cs.example.edu/oleafly/auth/callback/github.

GitHub

1. On GitHub, select your profile picture, then Settings › Developer settings › OAuth apps, and select New OAuth App. For an app owned by an organization, use Developer settings in the organization’s settings instead.
2. Fill in Application name (for example Smith Lab Oleafly), Homepage URL (https://collab.example.org) and Authorization callback URL (https://collab.example.org/auth/callback/github). Leave Enable Device Flow off.
3. Select Register application. Copy the Client ID, then select Generate a new client secret and copy the secret.
4. Set OLEAFLY_GITHUB_CLIENT_ID and OLEAFLY_GITHUB_CLIENT_SECRET, and restart the server.

The server asks GitHub only for the person’s profile and email addresses (read:user and user:email). OLEAFLY_GITHUB_LABEL changes the text on the sign-in button.

For GitHub Enterprise Server, register the app there and also set OLEAFLY_GITHUB_URL to its address, such as https://github.example.edu. Set OLEAFLY_GITHUB_API_URL only if your API address is unusual.

OpenID Connect

OpenID Connect covers GitLab, Google, Microsoft Entra ID, Keycloak, Authentik, Okta and most university single sign-on systems. If your university only offers SAML, put Keycloak or Dex in between.

1. Pick a short name made of letters and digits, such as GITLAB. It becomes part of the variable names, and in lower case it becomes part of the callback address. In the Compose .env, rename the UNIVERSITY lines or add a second block.

2. Register an application with your provider. Choose a confidential or web application, set the redirect URI to https://collab.example.org/auth/callback/gitlab, and allow the scopes openid, email and profile.

3. Add the provider’s details:

   OLEAFLY_OIDC_GITLAB_ISSUER=https://gitlab.com
   OLEAFLY_OIDC_GITLAB_CLIENT_ID=example-client-id
   OLEAFLY_OIDC_GITLAB_CLIENT_SECRET=example-client-secret
   OLEAFLY_OIDC_GITLAB_LABEL=GitLab

4. Restart the server.

The label is the text on the sign-in button, such as University login. The issuer is the address under which the provider publishes /.well-known/openid-configuration. Some common ones:

Provider	Issuer
GitLab.com	https://gitlab.com
Self-managed GitLab	Your GitLab address, such as https://gitlab.example.edu
Google	https://accounts.google.com
Microsoft Entra ID	https://login.microsoftonline.com/ followed by your tenant ID and /v2.0
Keycloak	https://sso.example.edu/realms/ followed by the realm name

Verified email addresses

Allowed-list entries and domain rules only match verified email addresses. The server counts an address as verified only when the provider says so: GitHub marks it verified, or the OpenID Connect claim email_verified is true.

Some institutional providers leave that claim out. If yours does, and it only hands out addresses your institution controls, set OLEAFLY_OIDC_<NAME>_TRUST_EMAIL=true. Never set it for a provider where people can type in any email address they like. Anyone could then sign in as someone on your allowed list.

Certificates your university signs

If your university signs its own certificates, for its proxy or its sign-in service, the server has to trust that certificate authority. So does every computer that runs Oleafly.

Without Docker, add the certificate to the operating system. On Debian and Ubuntu, copy it into /usr/local/share/ca-certificates/ with a name ending in .crt and run sudo update-ca-certificates.

The Docker image has no package manager, so give it a certificate list that includes yours. Next to docker-compose.yml, on a Debian or Ubuntu machine:

cat /etc/ssl/certs/ca-certificates.crt university-ca.pem > ca-bundle.pem
chmod 644 ca-bundle.pem

Then add the file to the server in docker-compose.override.yml and run docker compose up -d again:

services:
  oleafly-server:
    volumes:
      - ./ca-bundle.pem:/etc/ssl/certs/ca-certificates.crt:ro

Email

Email is optional, and everything else works without it. Without email, you send people the server’s address yourself, and Oleafly lists the projects shared with each person under Shared with you.

To set it up, give the server an SMTP account:

OLEAFLY_SMTP_URL=smtps://oleafly%40example.org:[email protected]:465
OLEAFLY_MAIL_FROM=Smith Lab <[email protected]>

Set both lines or neither. Write special characters in the user name and password in URL form, for example %40 for @.

• smtps:// uses TLS from the start, on port 465 unless you name another port.
• smtp:// uses port 587 unless you name another, then switches to TLS with STARTTLS. If the mail server doesn’t offer STARTTLS, the server won’t send.
• A mail relay on the same machine is the exception: smtp://localhost, smtp://127.0.0.1 and smtp://[::1] send without TLS.
• A relay on the same private network can skip TLS when you add ?tls=none, as in smtp://mailpit:1025?tls=none. The address can’t hold a user name or password then, because they would cross the network unencrypted. Use it only when nobody else can reach that network.

The server checks the mail server’s certificate against the system’s trusted certificates.

What the server sends

There are six kinds of email. Email to someone who already has an account goes only to their verified addresses, and GitHub’s noreply addresses are always skipped.

Email	When it goes out
Added to the server	An admin adds someone to the allowed list by email address. It has the server’s name, an Add to Oleafly link and the server’s address. Adding someone by GitHub user name or through a domain rule sends nothing, because the server has no address for them yet.
Project shared	A project owner adds someone to a project. It has the project title, who shared it, their role and a link that opens the project, plus the project’s web page for when the link doesn’t open the app. Changing a role later sends nothing. Each person can turn these off on the server’s card in Settings → Collaboration.
New device	An account signs in on another device. It has the device name, its system and the time in the server’s time zone, with a reminder to sign that device out if it wasn’t them. A new account’s first device gets no email. Set TZ, for example TZ=Europe/Berlin, to choose the time zone.
Guest invitation	A project owner invites a guest. It has the project title, who invited them, an Add to Oleafly link and the address to sign in with. When approval is on, it goes out once the invitation is approved.
Mention	Someone mentions a member in a comment or reply. It names who mentioned them, the project and the file, the text the comment is on and the comment, with a link that opens the comment in Oleafly. It goes out about a minute after the comment reaches the server, and mentions for the same person within that minute come together in one email. Nobody gets one for their own comments or about a project they can’t open, and editing a comment never sends the same mention twice. Each person can turn these off with Email me when someone mentions me in a comment on the server’s card in Settings → Collaboration.
Sign-in link	Someone asks for one on the server’s sign-in page.

Admins can stop every kind except sign-in links with Email notifications in the server settings. Sign-in links always go out, because people can’t sign in without them.

Test it

In the admin console, open Email. It shows whether email is on and the From address, never the password. An admin can select Send test email to send one to their own verified address. The page then says whether it went out, or what the mail server answered.

When email is off, the page shows the Add to Oleafly link and the server address, so you can send them yourself.

When the mail server is down

Sending never holds up the action behind it. The server keeps emails in a queue in memory and tries again after 30 seconds, 2 minutes, 10 minutes, 30 minutes and 2 hours. Each failed try is a warning in the server log, and the Email page shows the latest failure. If the last try fails too, the server logs an error and drops that email. Emails still waiting when the server restarts are lost.

Sign in by email link

People can also sign in with a link the server emails them, so they don’t need a GitHub or OpenID Connect account. This needs email. Then an admin turns on Sign in by email in the server settings. It’s off by default.

The person selects Continue with Email in Oleafly, enters their address in the browser and selects Email me a link. The link works once, for 15 minutes, on the computer that asked for it. Opening the link shows a page with a Sign in button. Opening it alone doesn’t use the link, so a mail scanner that follows links can’t use it up.

Your access rules still decide who gets in: an allowed-list entry for that email address, a domain rule or a guest invitation. An allowed-list entry by GitHub user name doesn’t match an email link. The page says the same thing whether or not the server lets the address in, so nobody can use it to find out who has an account.

Turning it on also opens existing accounts to email links. A link signs in to the account that already has that address as a verified address. The server keeps every verified address a provider has reported for an account, not just the main one, and it keeps an address even after the person removes it from the provider. GitHub, for example, reports every verified address on the GitHub account. So anyone who can read mail at one of those addresses can sign in to that account by email. Before you turn it on, check that people still control every address on their accounts.

If an address belongs to more than one account, the link signs in to none of them. If the only account with that address is suspended or removed, the link is refused until you let that person back in.

The server sends at most 3 links to one email address and 100 links to one IP address in 15 minutes, so a class of 50 at one address can all sign in. OLEAFLY_EMAIL_LINKS_PER_ADDRESS and OLEAFLY_EMAIL_LINKS_PER_IP change these numbers. All IPv6 addresses in one /64 network count as one address. Turning Sign in by email off stops links that were already sent.

Sign in with a code

When the browser can’t get back to Oleafly after a sign-in, for example on a locked-down computer, people can sign in with a code. It needs no setting and works with every sign-in option the server has.

Oleafly shows your server’s address followed by /auth/device and a code of eight letters. The person opens that address on any phone or computer, types the code, checks the computer name the page shows, and signs in. The sign-in has to finish in the browser where they typed the code, so a sign-in page someone else sends them as a link signs nobody in.

A code works once, stops working after 10 minutes, and only the copy of Oleafly that asked for it can finish the sign-in. Stop, this wasn’t me cancels it. One IP address can ask for 100 codes and type 10 wrong codes in 10 minutes. That’s enough for a class of 50 sharing one address, and OLEAFLY_DEVICE_CODES_PER_IP changes it.

Access rules

Signing in isn’t enough to get in. An access rule has to let the person in. Manage them under Access rules in the admin console:

• Allowed people: add a person by email address, or by GitHub user name, with the role they get. User names work only for GitHub, because other providers let people choose or change theirs. If the server sends email, adding someone by email address sends them the server’s address and an Add to Oleafly link.
• Domains: let everyone with a verified email address at a domain, such as cs.example.edu, sign in with the role you pick.

Once you’ve added people, they can add the server in Oleafly and sign in.

Under People, you can change a person’s role, suspend or reactivate them, remove them and sign out their devices. A suspended person keeps their account but can’t sync until you reactivate it. Their changes stay on their computer.

Someone you remove stays out, even when a domain rule covers their address or a project owner invites them as a guest. To let them back in, add them again by email address or user name. They get their old account back, with every project they had.

Roles and permissions

Each person has one server role, given by admins and maintainers. In each project they’re added to, they also have a project role, given by that project’s owner. Roles lists the project roles: Owner, Editor, Reviewer and Viewer.

No server role opens a project by itself. Project access comes only from the project’s owner.

Action	Admin	Maintainer	Member	Guest
Add the server to Oleafly	Yes	Yes	Yes	Yes
See the member list	Yes	Yes	Yes, unless an admin hides it	No
Share a project	Yes	Yes	Yes	No
Read the security log	Yes	Yes	No	No
Add members to the server	Yes	Yes	No	No
Appoint maintainers	Yes	No	No	No
Change server settings	Yes	No	No	No
Delete a project to free storage	Yes	No	No	No
Sign out someone’s device	Yes	Yes, but not other admins’ or maintainers’	Own devices only	Own devices only
Read stored projects with direct server access	Not in the app	Not in the app	Not in the app	Not in the app

The last row matters most. Projects are not encrypted on the server, so whoever runs the machine can read every stored project, whatever their role. Oleafly gives no role, admin included, a way to do that from the app. When an admin deletes a project to free storage, its owner and members are told, and their own copies stay on their computers.

Guests

A guest is someone from outside your server, such as a co-author at another university, whom a project owner invites to a project. Guests see only the projects they’re invited to.

Turn guests on

Guests are off on a new server. An admin turns them on with Allow guests in the server settings. Approve guests first is on by default, so an admin or maintainer approves each invitation before it works. Turn it off to let invitations work straight away. When an admin or maintainer sends an invitation, it’s approved at once.

If you turn Allow guests off later, owners can’t send new invitations and unused invitations stop working. Guests who already signed in keep their projects until an owner removes them or you remove them under People.

Invitations

Only a project’s owner can invite guests to it, from the project’s Share dialog.

• An invitation is for one address and one project, and it ends after 14 days.
• One person can send up to 20 invitations an hour.
• When approval is on, the invitation waits under Pending guests at the top of People. Admins and maintainers approve, decline or withdraw it there. The owner can withdraw it too.
• If the server sends email and Email notifications is on, the guest gets an invitation email. Otherwise Oleafly gives the owner an Add to Oleafly link to send themselves.
• If the project already has as many people as the server allows, the invitation waits, and works the next time the person signs in after someone has left.

The guest adds the server and signs in with any option that gives the server the invited address as a verified address: GitHub, an OpenID Connect provider or an email link. An unverified address doesn’t count. The first sign-in makes a guest account and opens every project that address was invited to.

What guests can do

Guests can open and compile the projects they were invited to, edit them if their role allows, and sign out their own devices. They can’t see the member directory or anyone’s email address, share projects, invite other people, or join a project through its link. To give a guest another project, that project’s owner invites the same address.

When a guest is removed from their last project, or leaves it, the server ends their access. It removes the account and signs out every device. A new invitation brings the same account back. If you remove a guest under People while they still have projects, a new invitation won’t bring them back.

Removal sticks

When an owner removes someone from a project, guest or not, that person can’t come back through the project’s link, even with link sharing on. Each try shows in the security log. To let them back in, the owner adds them again, or sends a new invitation if they’re a guest. Someone who leaves a project on their own can still rejoin through its link.

Admin console

The admin console is a window for running one server from Oleafly. Admins and maintainers can open it. In Settings → Collaboration, select Open admin console on the server’s card, or at the top of Manage server. Each server gets its own window.

Section	What it shows and does
Overview	Whether the server is healthy, how many people, devices and projects it has, who is online, how much storage it uses, its email and sign-in options, and its settings at a glance. It warns Nobody can sign in when the server has no sign-in option, and The server can’t save files when the data folder can’t be written to.
People	Everyone who has signed in. Change roles, suspend or remove people, and sign out their devices. Guest invitations waiting for approval are at the top.
Access rules	The allowed people list and the domain rules.
Projects	Every project shared on the server, with its owner, how many people it has, its size and its last activity. Search by title or owner, show only shared, archived or uploading projects, and archive or restore a project.
Settings	The server settings.
Email	Whether email is set up, the From address and the last failure. Send a test email from here.
Security log	Sign-ins and refused sign-ins, devices, people, settings, projects and guests. Each entry says who did it, when and from which IP address, with details such as the project, the sign-in option used or why a sign-in was refused.
Connection checks	The same checks as Test connection, run from your computer to the server.

Maintainers can use every section, but they can’t make anyone an admin or maintainer, see or sign out another admin’s or maintainer’s devices, see storage use, archive or restore projects, change server settings or send a test email. Admins can do all of it.

Archiving a project stops sharing it for everyone. People stop syncing it and keep their own copies, and the server deletes it after OLEAFLY_ARCHIVE_DAYS days unless an admin restores it first. Restoring shares it again with the same people. A project that never finished its first upload can’t be restored. Both show in the security log.

The console never opens a project. It shows titles, owners and sizes, and nothing inside them.

Server settings

These apply to everyone on the server. Only admins can change them.

Setting	What it does
Allow guests	Members can invite people from outside the server to projects they own.
Approve guests first	A maintainer or admin approves each guest invitation before it works.
Member directory	Members can look each other up by name when they share a project.
Show email addresses in the directory	Members see each other’s email addresses when they look someone up.
Allow link sharing	Project owners can let any member open a project from its link.
Allow project access logs	Project owners can keep a log of who opened their project.
Allow comments	People in shared projects can comment on text and reply. Turning this off hides comments everywhere and keeps them stored.
Email notifications	Turn this off to stop the server’s emails for everyone, except sign-in links.
Sign in by email	People can sign in with a link sent to their email address. This needs the server’s email settings.