App authentication
Choose how your app's users sign in, manage those users and their roles, and add single sign-on, tenants, branding and sign-in email.
App authentication controls how people sign in to the apps on your workspace's Shell site. It's optional: you don't need it to create apps or deploy Coderunners, and it never affects how your team signs in to the Client Portal.
Choose a sign-in mode
| Mode | Your users sign in with | Use it when |
|---|---|---|
| None | Nothing | Your apps are public, or handle access themselves |
| Groundfloor | A sign-in page Groundfloor hosts for your workspace, with users, roles, single sign-on and branding managed here | You want sign-in without running an identity provider |
| External | Your own OpenID Connect provider, such as Okta, Microsoft Entra ID or Auth0 | Your users already have accounts there |
Open App authentication
In the Client Portal, go to Administer → App authentication and pick the workspace.
Choose a mode
On Settings, choose the mode. For External, enter your provider's issuer URL and client ID; register https://<your-shell-site>/* as a redirect address with your provider.
Save
Groundfloor mode takes a moment to set up. When it's ready, the Users, Roles, SSO and Branding tabs appear.
You need the Admin or Owner role in the workspace.
Turn sign-in off, or delete it
Switching from Groundfloor to None or External stops sign-in straight away, but keeps your users, roles and settings: switch back and they return. To remove them for good, turn sign-in off first, then use Delete Groundfloor login and type the workspace's name. Access grants and M2M tokens are kept either way.
Users
With Groundfloor mode, manage your app's users on the Users tab:
| Option | Use it when | Email sent |
|---|---|---|
| Invite user | They should set their own password | Yes, an invitation with a link to set their password. The link works for 72 hours |
| Add user | They should be able to sign in straight away | Yes, with their sign-in address and role (never the password) |
With Add user, choose Generate a temporary password (recommended) or type one yourself. A generated password is shown once, with the sign-in link, so you can share both privately; it isn't stored and can't be shown again. The user must change it the first time they sign in.
Give each user a role, such as viewer, user or admin. You can also disable users, send a password reset, change roles and remove users there.
App users are separate from your team. They never appear on Team and get no access to the Client Portal or your workspace's settings.
You can't invite or add someone who can already sign in to the workspace, with a password or with single sign-on: the Client Portal says so. Send them a password reset instead.
Check that the invitation arrived
The Status column shows Invited until the user sets a password, with a line under it about the email:
| Line | Meaning |
|---|---|
| Invite sent … ago | The mail server accepted the email |
| Email not sent | It wasn't sent. The reason is shown underneath, for example the mail server refused it, or email isn't set up for the workspace |
| Delivery unconfirmed | The mail server didn't answer in time. The email may still arrive |
| No email sent | The invitation was made without an email |
| Delivery not recorded | The user was invited before Groundfloor recorded delivery. Resend to be sure |
| Temporary password set … , not used yet | You gave them a temporary password and they haven't signed in with it yet |
| Invite link active until … | A one-time invite link is waiting to be used |
If the invitation doesn't arrive
While a user is Invited, their row offers three ways in:
- Resend sends the invitation email again. You can resend once a minute, and up to 5 times in a day. Inviting the same person again counts as a resend.
- Temp password replaces the invitation with a generated temporary password that you share privately. It's shown once. The user must change it the first time they sign in. You can also use it again while they still haven't used their temporary password.
- Copy link makes a one-time invite link and copies it. Send it to the user privately: anyone with the link can set this person's password. They open it, choose their own password and then sign in. The link works once and for 24 hours. Making a new link cancels the previous one, and Cancel link cancels it straight away.
Once someone has set their own password, use a password reset instead.
Roles
On the Roles tab, create your own roles alongside the built-in viewer, user and admin. A role decides which apps, data and files a user can reach once you grant it access on Site access. The built-in admin role is granted like any other role: new collections and Files start with an admin grant, and you can change or remove it.
These roles are for your app's users only; they're unrelated to your team's Owner, Admin and Writer roles.
A user's roles travel in their token's realm_access.roles claim, so your app's backend can read them there after checking the token. See Who can reach your Service.
Data access is per collection, not per record
A role's grant on a collection applies to every record in it: anyone whose role can read a collection sees all of its records, write lets them update any of them, and delete lets them delete any of them.
If users must see or change only their own records, don't give their roles any grant on that collection: a user who can read it can query the whole collection with their own token, bypassing your app. Have your app's backend (for example a Coderunner) do it instead. The backend checks the signed-in user's token (see Who can reach your Service), reads and writes the collection with a machine-to-machine (M2M) client, which collection grants don't limit, and returns or changes only that user's records. Match records by the token's sub claim (the user's ID); see Know who the user is. See Who can use a collection. Per-record access for app users is planned.
Single sign-on
On the SSO tab, connect an OpenID Connect or SAML provider so users can sign in with an existing company account, while Groundfloor keeps managing your users. Use Test login before rolling it out. Role names in the provider's tokens must match the roles you grant on Site access.
Tenants
If your app serves several customer companies, turn on Multi-tenant on Settings. A Tenants tab appears, where you create a tenant per customer, add or invite its users and give it its own single sign-on. Sign-in then asks for the email first, then the password or the company's sign-in.
Each user's token carries their tenant in the organization claim. Tenants separate who signs in; your app keeps each tenant's data apart using that claim. Site access, data, files and M2M tokens stay shared across the workspace. See Sign-in and users.
Your own domain
By default your Shell site is https://<workspace-slug>.app.groundfloor.cloud. To use your own domain, enter it on Settings and save, then create the CNAME record shown. Root domains such as example.com need an ALIAS or ANAME record. Once your DNS is live, a certificate is issued automatically, usually within a couple of minutes. Your apps then open at https://<your-domain>/apps/<app-slug>.
Branding
On Branding, set the sign-in page's display name, logo, background and accent colour.
Sign-in email
Invitations, password resets and email verification are sent for you by default, with Groundfloor email. There's nothing to set up: emails come from a Groundfloor no-reply address, with your organization's name as the sender.
To send from your own domain instead, open Branding → Email sending and choose Your own email server. Enter the sender name and sender email, the mail server, the port (25, 465, 587 or 2525), the username and password, and whether to use SSL or STARTTLS. The mail server, port and sender email are required. Use Send test email to check the settings: it sends a short message to your own email address, which must be verified. Then Save.
- If your own server fails, the email isn't sent and the Client Portal tells you so. Groundfloor email isn't used as a fallback.
- If you change the mail server or port, enter the password again.
- Switching back to Groundfloor email removes your saved server settings and password.
Troubleshooting
| Problem | Likely cause | What to do |
|---|---|---|
| No Users, SSO or Tenants tab | The mode isn't Groundfloor, setup hasn't finished, or Multi-tenant is off | Choose Groundfloor and wait; turn on Multi-tenant for Tenants |
| Invitation or password emails aren't sent | Your own email server is failing | Use Send test email under Branding → Email sending, then fix the settings or switch to Groundfloor email |
| A user never got their invitation | The email wasn't sent or was lost | Check the line under Invited, then use Resend, Temp password or Copy link. See If the invitation doesn't arrive |
| "You can resend once a minute and up to 5 times a day" | You've hit the resend limit | Wait, or use Temp password or Copy link |
| Inviting or adding a user is refused because they can already sign in | They already have a password or single sign-on | Send a password reset from their row |
| A user says the invite link is no longer valid | It was used, cancelled, replaced or is more than 24 hours old | Make a new one with Copy link |
| External sign-in fails | The issuer, client ID or redirect address is wrong | Check them against your provider's settings |
| A user can't see a collection | Their role has no grant | Grant it on Site access |
Next steps
- Site access — what each role can reach.
- Sign-in and users — use the signed-in user in a Shell app.
- Workspace auth API — manage sign-in from code.