Building User Authentication
Sign-in, sessions, scopes, and gated pages for your app — the complete authentication system on a RUAL cluster.
Every RUAL cluster already has accounts, sign-in, sessions, and token management built in. Your job is to wire your app's pages and APIs to that system — not to build one. This tutorial assembles the full picture.
What the Cluster Handles for You
- User accounts with passwords (and optional 2FA), created by an administrator — see User Access Management.
- The default login, password reset, and security pages, ready at your cluster URL — see Overwrite Default Pages.
- Sessions and
access_tokens (14-day validity, auto-extending), accepted in five locations — see API Guide — Authentication.
Deciding Who Can See What
Every page and API gets its audience from a scope:
| Scope | Who passes | Use for |
|---|---|---|
*public | Anyone, no token | Landing pages, status endpoints, public content |
*loggedin | Any valid access_token | Member areas, app pages, private APIs |
Custom scope (e.g. billing_read) | Users you granted that scope | Role-gated sections (admin, finance, support) |
Set scopes per page block or API block via its lock icon — full mechanics in Remote Access Control. Grant custom scopes to users on their user detail page (custom_scopes) or bundle them in user groups — see User Roles Explained.
The Sign-In Flow
- A visitor hits a page scoped
*loggedinwithout a token → the cluster serves the login page. - They sign in (password, plus 2FA code when enabled) → the cluster issues an
access_tokenand redirects back. - The token travels as a cookie in the browser, or as a header/query param from your own frontend.
- Sign-out invalidates the token immediately; users manage their sessions on the default security page.
Building your own frontend? Call the sign-in API directly (POST /api/v1/auth/signin) and store the token — see the API workflows. For 2FA-enforced clusters, pass the current code from the user's authenticator.
Knowing Who's Calling
Inside any authenticated flow, the user_current block gives you the calling user's document: guid, name, scopes. Typical uses:
- Filter data to the caller (
owner_guid = user.guidin your queries — the denormalized owner pattern from Storages). - Branch on scope: allow admins to a management view, others to their own data.
- Audit: write the actor onto every document you create.
Gating Pages and Sections
- Public marketing pages: scope
*public. - The app shell and member pages: scope
*loggedin— unauthenticated visitors bounce to login automatically. - Admin-only sections: a custom scope granted to admins only.
- Locked yourself out with a custom login page? Recover with
?studio=request— see Overwrite Default Pages.
Hardening Checklist
- Enable 2FA for everyone who can reach Studio or admin scopes.
- Keep
*publicfor content that truly is public — check every page and API block once before launch. - Prefer custom scopes over checking usernames in flows.
- Review the failed-login blocking and rate limits in Remote Access Control.
- Audit access regularly on the User Activity page — see Auditing User Access.