Users and sign-in

The owner

The first account on a site becomes its administrator. Create it on the Set up your site screen at /admin/ (see Install and run) or with gansey user create. While a site has no users, gansey serve logs a reminder and gansey doctor reports it as a problem.

Signing in

People sign in at /admin/ with their email and a password. Passwords must be at least 10 characters, and the error never says whether the email or the password was wrong. A session lasts [auth].session_days days (14 by default) in an HttpOnly cookie, then the person signs in again. Each site and public URL gets its own cookie name, so two Gansey sites on one host do not sign each other out. Expired sessions are cleared every hour.

Instead of a password, anyone can choose Email me a sign-in link instead. The link works once and expires after 15 minutes. The screen answers the same way whether or not the email has an account.

There is no self-service password reset. Someone who forgets their password can still sign in with an emailed link. To give them a new password, run gansey user reset-password, because Your account asks for the current password before it changes one.

Each person can add a second step under Your account → Two-factor sign-in:

Choose Set up two-factor.
Scan the code with any authenticator app, or type the key into it by hand.
Enter the current six-digit code and choose Turn on.
Save the ten recovery codes shown. Each works once in place of an app code.

From then on, signing in with a password asks for a code from the app or a recovery code. The half-finished sign-in expires after 10 minutes. To turn two-factor off, confirm your password on the same card. An emailed sign-in link counts as the second step and signs the person straight in, so anyone who can read an account's email can sign in to it.

Email

With an [email] section (see Configuration), sign-in links and invitations are sent over SMTP. Without one, nothing is sent:

every link is written to the server log;
invitation links are shown in Users & roles for you to pass on yourself;
sign-in links are shown on the sign-in screen, but only in the local and dev environments.

That is fine on a developer machine. On a staging or production site, configure email: without it, people can only sign in with a password. gansey doctor warns when email is not configured.

Roles

A role is a named set of capabilities, kept per site. A user can hold several roles and gets every capability any of them grants. Five preset roles are created on every site:

Capability	Administrator	Editor	Author
`manage_site`: site settings, content types, backups, updates, custom code	yes
`manage_users`: add, edit and remove users	yes
`manage_roles`: create and edit roles	yes
`edit_pages`: edit pages, entries and terms	yes	yes	yes
`publish_pages`: publish and unpublish them	yes	yes
`delete_pages`: delete them	yes	yes
`edit_theme`: edit tokens and site parts	yes	yes
`publish_theme`: publish them	yes	yes
`upload_media`: upload and edit media	yes	yes	yes
`delete_media`: delete media	yes	yes
`manage_modules`: install, switch and configure modules	yes

Viewer and Member grant no capabilities. The admin sends anyone without capabilities to [auth].members_home on the public site, so both suit people who sign in to the public site only, such as customers or club members. They sign in at /sign-in on the site itself; Modules explains how module routes use the member role.

Module screens and dashboard cards open for users with the capability the module names, or edit_pages when it names none. manage_modules opens all of them.

Custom roles

Under Users & roles → Roles, New role takes a name and any mix of the capabilities above. You need manage_roles. You can edit presets as well as your own roles, but only your own roles can be deleted.

Inviting people

Under Users & roles → Users, choose Add user, enter a name and email, pick a role, and choose Create and send invitation. The invitation link works once and lasts 3 days. It signs the person in and asks them to set a password. Send link on any row sends a fresh one. The table also shows each person's roles (select a role to give it or take it away), whether two-factor is on, their last sign-in, and an Active switch. Switching someone off signs them out everywhere. Deleting someone keeps their revisions, attributed to no one. You cannot switch off or delete yourself.

From the command line

The gansey user commands work straight on the database, so they help when nobody can sign in:

gansey user create --email [email protected] --name "Example Editor" --role editor
gansey user reset-password --email [email protected]
gansey user list

create makes the first user an administrator and later users editors, unless --role names a preset or custom role slug. --password sets the password; without it you are prompted, and the prompt does not hide what you type. reset-password sets a new password and signs the person out of every session. list prints each user's id, email, whether they are active, and their roles.

Getting started