Users and sign-in on Athenode Pro

An account on Athenode Pro is one person's sign-in to the server, with a server role and the project roles it holds. Athenode Pro is the Athenode server a team runs itself, with accounts, project roles and a licence. Its accounts exist on that server only and are separate from Athenode accounts at platform.athenode.com: they share no password, and signing in to one does not sign you in to the other.

An account is either built in, with an email address and a password, or a single sign-on account, created the first time a person signs in through your identity provider. Administrators manage the accounts on the Users page and the groups on the Groups page, both in the Administration group of the sidebar outside a project, and the sign-in settings in the Security and Single sign-on sections of Settings. Each person manages their own password, two-factor sign-in, personal access tokens and sessions on the Account page, from the user menu. Personal access tokens, for jobs without a browser such as CI, are described in Connect to Athenode Pro. Administrators also see each account's tokens and revoke them on the Users page.

Every enabled account takes one seat of the organisation's Pro tier, administrators included: Pro Solo has 1 seat, Pro Team 8 and Pro Enterprise no limit. Pending invitations and disabled accounts take none. The Users page shows the count as "Seats used:" followed by the seats taken and the seats of the licence. When every seat is taken, creating an invitation, accepting one, enabling an account and a first sign-in with single sign-on are refused. A person who accepts an invitation or signs in with single sign-on then reads "No seat is free for a new account on this server. Ask an administrator." To make room, disable an account, or have the organisation change to a higher tier, as Billing for Athenode Pro describes. The Pro licence covers seats after a renewal with fewer of them.

The first administrator

The first administrator is the account created on the server's setup page with the one-time setup token that Pro prints at its start. Create the first administrator gives the steps. After the setup, the setup page shows "Already set up", and every further built-in account joins through an invitation. The server always keeps one enabled administrator: the last one cannot be disabled or made a member.

The server roles administrator and member, and the project roles owner, editor and viewer, are listed with everything they allow on roles and permissions.

Send invitation and reset links by email

Set up SMTP so that invitation links and password reset links reach people by email. Without it, the Users page shows each link for you to copy and hand over. You need the administrator role.

1. Open Settings and its Security section.
2. Under SMTP, enter the Host and the Port of your mail server.
3. Choose the Encryption: None, STARTTLS (port 587) or TLS (port 465).
4. Enter the Username and Password of the mail account, and the Sender address.
5. Select Save. Pro confirms "SMTP settings saved".
6. Select Send a test email. Pro sends it to your own address and shows "Test email sent to" followed by the address.

The stored password cannot be read back. To keep it while you change another field, leave Password empty. When sending a link fails, the Users page shows the link with the error of the mail server, and you hand it over.

Invite someone to the server

An invitation is a one-time link with which a person creates a built-in account. You need the administrator role and a free seat.

1. Open Users.
2. Under Invite someone, enter the person's Email.
3. Choose the Role: Member or Administrator.
4. Select Create the invitation.

With SMTP set up, Pro emails the link and says "The invitation link was emailed." Otherwise it shows the link with Copy the link and the time until which it works. Hand it to the person over a channel you trust. The link works once and for 7 days.

An email address that already belongs to an account of the server is refused. The invitation appears under Pending invitations with its role and its expiry, until it is accepted or expires. A pending invitation takes no seat, and the seat is checked again when the person accepts.

The invited person opens the link, sees "You were invited as" followed by their address, enters Your name and a Password of at least 12 characters, and selects Create the account. They are signed in. An invitation that was used, revoked or expired shows "This invitation link is invalid, expired or used already. Ask an administrator for a new one."

A new account has no project role. Owners of a project grant it one on the project's Members page, as roles and permissions describes, or it creates projects of its own.

Revoke an invitation

1. Under Pending invitations, select Revoke next to the address.
2. Confirm with Revoke.

The link stops working. You can invite the same address again.

Change an account's role, disable or enable it

The Users page lists every account of the server with its Name, Email, Role and Status. The status column marks accounts with two-factor sign-in as "2FA" and single sign-on accounts as "SSO". You need the administrator role.

• To change the server role, choose Member or Administrator in the account's Role list. The change applies at once.
• To disable an account, select Disable and confirm. The person can no longer sign in, their sessions end at once, their AI tools lose access to the server and their personal access tokens are deleted. Their project roles and everything they made stay, and the account frees its seat.
• To enable a disabled account, select Enable. It needs a free seat.

Accounts are never deleted: disable an account that should no longer have access. You cannot disable your own account. Disabling the last enabled administrator, or the last owner of a project, is refused. For a project, grant the owner role to someone else first.

See and revoke the access tokens of an account

A personal access token lets a job without a browser, such as a CI pipeline, act as the account that created it, with that account's project roles. When a token may have leaked or a job no longer needs it, an administrator revokes it without disabling the account. You need the administrator role.

1. Open Users.
2. Select Access tokens in the person's row. Under "Access tokens of" followed by the person's name, Pro lists each of their tokens.
3. Select Revoke in the token's row.
4. Confirm with Revoke.

The list shows each token with its name, then "Created" with the date, "last used" with the date or "not yet", and "expires" with the date or "Never". A token past its expiry date is marked Expired and stops working. An account without tokens shows "No access tokens yet." Select Close to hide the list.

After you confirm, Pro shows the token's name and "is revoked." Every request with the token is refused from then on, and a CI job that sends it stops. The person keeps the account, its sessions and its other tokens. Revoking cannot be undone. Pro never shows the token itself on this page: only the person sees it, once, when they create it on their Account page, and only they can create a new one. To cut off an account entirely, disable it instead, which deletes all its tokens.

Passwords of built-in accounts

A password has at least 12 characters and at most 1,024. Single sign-on accounts have no password on the server: their identity provider handles it.

Change your password

1. Open the user menu and select Account.
2. Under Password, enter the Current password and the New password.
3. Select Change password.

Pro shows "Password changed; your other sessions ended." You stay signed in in this browser.

Reset a person's password

A person who forgot their password asks an administrator for a reset link, as the sign-in page tells them. You need the administrator role.

1. Open Users.
2. Select Reset link in the person's row.

With SMTP set up, Pro emails the link. Otherwise it shows the link to copy and hand over. The link works once and for 1 hour. The person opens it, enters a New password and selects Set the password. Every session of the account ends, and they sign in with the new password. A used or expired link shows "This reset link is invalid, expired or used already. Ask an administrator for a new one."

Two-factor sign-in

Two-factor sign-in asks for a code of an authenticator app (TOTP) after the password at every sign-in. Each built-in account turns it on for itself, and an administrator can make it mandatory for every built-in account. Single sign-on accounts never use it: their identity provider handles the second factor.

Two-factor sign-in is a Pro Team and up feature. On Pro Solo, the Account page says "This server's license does not include two-factor sign-in.", and no code is asked at sign-in, also from an account that turned it on before a downgrade. Its authenticator stays set up and is asked for again after an upgrade, as Pro tiers describes.

Turn on two-factor sign-in

1. Open the user menu and select Account.
2. Under Two-factor sign-in, select Set up two-factor sign-in.
3. Add the account to your authenticator app. Pro shows the Secret to type in and an otpauth:// link to open on a device that has the app. It shows no QR code.
4. Enter the 6-digit code that the app shows in Code.
5. Select Turn on.
6. Save the 10 recovery codes that Pro shows, with Copy or Download, then select Continue.

Each recovery code works once, in place of a code of the app. Pro shows the codes this one time only. The Account page then shows "Two-factor sign-in is on" with the number of recovery codes left.

At the next sign-in, after the email address and the password, Pro asks for the 6-digit code of the app or a recovery code. Enter it and select Verify. A code of the app works once.

Renew the recovery codes or turn two-factor sign-in off

On the Account page, under Two-factor sign-in, enter A current code (or a recovery code), then select one of these:

• New recovery codes: Pro shows 10 new codes, and the old ones stop working.
• Turn off: two-factor sign-in is off for your account. On a server where it is mandatory, Turn off is not offered.

Make two-factor sign-in mandatory

You need the administrator role.

1. Open Settings and its Security section.
2. Turn on Two-factor sign-in is mandatory for every account.

The change applies at once. A built-in account without two-factor sign-in then reaches only the page that sets it up, with "Two-factor sign-in is mandatory on this server. Set it up to continue.", until it is set up. The variable ATHENODE_REQUIRE_2FA sets the value a new server starts with, as Configure Athenode Pro describes.

Reset a person's two-factor sign-in

When a person lost their authenticator app and their recovery codes, an administrator turns their two-factor sign-in off.

1. Open Users.
2. Select Reset 2FA in the person's row and confirm.

Two-factor sign-in of the account is off, its recovery codes stop working and its sessions end. The person signs in with the password and sets it up again, which a server with mandatory two-factor sign-in asks for at once.

Sessions and lockout

A session in the browser ends after 12 hours without use, and 7 days after the sign-in in any case. The person then signs in again.

To end every session of your account except the one in this browser, for example after using a shared computer, open Account and select Sign out other sessions under Sessions. Pro shows "Every other session of your account ended."

Sessions also end when the account is disabled, when its password is reset, when an administrator resets its two-factor sign-in, and, except for the current one, when the person changes their password. An open page of an ended session goes to the sign-in page.

Repeated failures lock further attempts out for 15 minutes, with "Too many failed sign-in attempts. Try again later." Pro counts the failures of the last 15 minutes:

Attempt	Locked out after
Password, at sign-in or when a signed-in person changes it	5 failures for one account, or 20 from one address
Two-factor code, at sign-in or when a person turns two-factor sign-in off or renews the recovery codes	5 failures for one account, or 20 from one address
Recovery code	5 failures for one account, or 20 from one address
Setup token	5 failures from one address
Invitation and reset links	10 failures from one address

The address is the one your reverse proxy passes when it is listed among the trusted proxies, as Configure Athenode Pro describes. A restart of the server ends every lockout.

Recover an account on the server machine

When no administrator can sign in, or SMTP is not set up and a link is needed, recover a built-in account from a terminal on the server machine. The command needs no SMTP and no master key, and the server can keep running.

athenode-pro recover --email ann@example.com

Option	Description
--email <address>	(required) The email address of the account to recover.
--reset-link	Prints a one-time password reset link, valid for 1 hour. This is what the command does when you pass neither option.
--reset-2fa	Turns two-factor sign-in off for the account, with its recovery codes, and ends its sessions. Combine it with --reset-link to do both.
--move-to-password	Moves a single sign-on account to a password for good, ends its sessions and tokens, and prints a one-time link with which the person sets a password.

Run it as the user that runs Pro, with the same database and public URL as start, from the environment, the config.json of the data folder or --public-url. A running server ends the sessions within 15 seconds. The command refuses single sign-on accounts without --move-to-password: recover those at your identity provider, or move them to a password, as Move a single sign-on account to a password describes. An unknown address ends with "no account with the email address" followed by the address.

Sign in with single sign-on

Single sign-on lets people sign in to Pro through one OpenID Connect provider of your organisation, such as Keycloak, Google, Okta or Entra ID, next to the built-in accounts. You need the administrator role, and the server's public URL must be the address people open.

Pro tiers describes what stops after a downgrade below Pro Enterprise.

1. At your identity provider, create a client for Pro and register the redirect URI https://athenode.example.com/api/pro/auth/oidc/callback, with your public URL in place of https://athenode.example.com. The Single sign-on section shows the exact address under Redirect URI (register it at the provider).
2. In Pro, open Settings and its Single sign-on section.
3. Enter the Issuer URL of the provider, an https address such as https://idp.example.com/realms/team.
4. Enter the Client ID and the Client secret of the client.
5. Optional: change the Groups claim, the claim that lists a person's groups. It is groups by default.
6. Turn on Sign-in with single sign-on is on.
7. Select Save. Pro confirms "Single sign-on settings saved".

The sign-in page then shows Sign in with single sign-on above the email and password fields. The stored client secret cannot be read back. To keep it while you change another field, leave Client secret empty. While single sign-on is off, the sign-in page has no single sign-on button.

Single sign-on accounts

• An account is created as a member the first time a person signs in, when a seat is free. An administrator can make it an administrator on the Users page. It has no project role until an owner grants one, or until a linked group gives it one.
• The account's email address comes from the provider at the first sign-in and does not change later. A provider that sends no email address cannot create an account: "Your identity provider sent no email address, so no account can be created for you."
• When a built-in account or another single sign-on account already has the address, the sign-in is refused and the accounts are not linked: "An account with your email address exists already, and single sign-on is not linked to it." The person signs in with that account's password, or an administrator sorts it out.
• The account has no password, no reset link and no built-in two-factor sign-in, also when two-factor sign-in is mandatory. Its Account page says "Your password and two-factor sign-in are managed by your identity provider, not here."
• A disabled account is refused at sign-in, and signing in never enables it.
• Signing out of Pro does not sign the person out of the identity provider. Disabling a person at the provider takes effect at their next sign-in to Pro, and their open sessions stay valid until then. Disable the account on the Users page to end them at once.

Move a single sign-on account to a password

When the organisation's tier no longer includes single sign-on, or a person should stop using it, an administrator moves the account to a password. The move is for good: the account keeps its password and its groups after a later upgrade, and single sign-on for its email address is refused from then on.

1. Open Users.
2. Select Move to password in the person's row.
3. Confirm in the dialog. The account's sessions and tokens end, and Pro shows a one-time link.
4. Hand the link to the person over a channel you trust. The link is never emailed.

The person opens the link and sets a password, then signs in with their email address and that password. When no administrator can sign in, run the same move on the server machine:

athenode-pro recover --email ann@example.com --move-to-password

Notes per identity provider

Provider	What to know
Keycloak	Add a group membership mapper to the client so that the ID token carries the groups. Keycloak may send full group paths, such as /team, which you then enter as the group's claim value.
Google	Google sends no groups claim, so groups cannot be linked to it. Grant project roles to the accounts or to groups you fill by hand.
Entra ID	Entra ID sends the object IDs of the groups, which you enter as the claim values. For a person in many groups it sends a marker in place of the list. Pro treats that as a sign-in without groups and removes the person from every linked group.

Organise accounts in groups

A group is a set of accounts that can hold project roles for all of them at once. Groups are local to the server. A group can also be linked to one value of the single sign-on groups claim, so that the provider decides who is in it. You need the administrator role.

Groups are a Pro Team and up feature, and linking a group to the groups claim needs Pro Enterprise. On Pro Solo, groups stay stored but are not applied, as Pro tiers describes.

Create a group and choose its members

1. Open Groups.
2. Enter a name in New group, such as "Platform team", and select Create. A name has 1 to 100 characters and is unique on the server.
3. Under Members of the group, tick the accounts.
4. Select Save members.

Owners of a project can then grant the group a role on the project's Members page, and every account in it gets that role. An account in several groups, or with a role of its own, gets the highest of its roles.

To rename a group, enter the new name next to it and select Rename.

Link a group to the groups claim

1. Under Linked groups-claim value of the group, enter the value exactly as the provider sends it, such as /team for Keycloak or a group object ID for Entra ID. A value has at most 500 characters.
2. Select Save.

At each sign-in of a single sign-on account, Pro adds it to every linked group whose value its groups claim holds, and removes it from the other linked groups, also when the claim is missing. Groups without a link are not changed. Changes you make by hand to the single sign-on accounts of a linked group are overwritten at their next sign-in, and built-in accounts in a linked group stay as you set them. To unlink a group, empty the value and select Save.

Delete a group

1. Select Delete next to the group.
2. Confirm with Delete the group.

The accounts in the group keep their accounts and lose the project roles they had through the group. Deleting a group, or removing accounts from it, is refused when it would leave a project without an owner. A sign-in through single sign-on is never refused for that reason: when its group changes leave a project without an owner, an administrator grants the owner role again.