Publish legal documents
This guide puts your organization’s privacy notice and terms of use in Goiabada, as legal documents you write in the admin console and publish as numbered versions.
Publish a document
Section titled “Publish a document”-
In the admin console, open Admin, Legal documents, and click New legal document.
-
Choose the document’s kind: Users must accept for terms of use, or For information for a privacy notice. See Kinds of document.
-
Give it a title. The console suggests a short name from the title as you type it; change it if you like. Click Create document.
-
The document opens on its draft. Write its text under Text, in Markdown. The Preview beside it shows the text as the document’s page will, and follows as you type. Click Save draft whenever you like.
-
When the draft is ready, click Publish version 1, and confirm. The saved draft becomes version 1, and the Versions tab lists it.
To change a published document, edit its draft and publish again: the next version is number 2, and so on.
Kinds of document
Section titled “Kinds of document”| Kind | For | Users |
|---|---|---|
| Users must accept | Terms of use | Accept each published version. |
| For information | A privacy notice | Read it. It’s shown and linked, and never accepted. |
A privacy notice tells people what you do with their data. It isn’t something they agree to, so Goiabada never asks them to accept one.
A document’s kind is fixed when you create it, so a version always means the same thing to the users who saw it. To change the kind, retire the document and create a new one.
Writing the text
Section titled “Writing the text”A document is written in Markdown (CommonMark) with tables: headings, paragraphs, lists, links, emphasis, quotations, code and tables. Its title holds at most 200 characters, and its text at most 100,000.
What the text can’t do, so it never runs code or calls another site from a reader’s browser:
- HTML in the text isn’t shown.
- A link to a
javascript:,vbscript:orfile:address, or to adata:address that isn’t an image, keeps its text and loses its address. - An image is never loaded. It’s shown as a link to the image, named by its alternative text.
A document has one text, in whatever language you write it. If you serve people in several languages, put each language’s text in the same document.
Versions
Section titled “Versions”A published version never changes.
Short names
Section titled “Short names”A document’s short name is its public address: lowercase letters, digits and hyphens, starting and ending with a letter or a digit, at most 64 characters. No two documents share one.
You can change it on the draft until the document is first published. From then on it’s fixed, so links to the document keep working.
The public page
Section titled “The public page”Once published, a document has a page on the auth server, which anyone can read without signing in:
| Address | Shows |
|---|---|
/legal/<short-name> |
The version in effect, with its number and the date it was published. |
/legal/<short-name>/versions/<n> |
Version <n>, as it was published. An earlier version says it’s no longer in effect, and links the current one. |
For example, a privacy notice with the short name privacy on https://auth.example.com is at https://auth.example.com/legal/privacy. Link to it from your website, your emails and your apps.
Each page lists every version, so users can read exactly what they accepted. A draft is never public. A document that was never published, or is retired, has no page: its addresses answer “Page not found”.
Where documents show
Section titled “Where documents show”Besides its public page, a document in effect shows to users here, and nowhere until it’s published:
| Where | Documents shown |
|---|---|
| The registration form, beside the fields it asks for | Those for all apps, plus the client’s own when the user came from that client’s sign-in page. |
| The acceptance page, at sign-in | The Users must accept documents the user hasn’t accepted. See Accepting documents at sign-in. |
| Account, Legal documents, in the admin console | The versions the user accepted. See What users accepted. |
Accepting documents at sign-in
Section titled “Accepting documents at sign-in”When a user signs in to a client, after their password and any second factor, and before the consent screen, the auth server checks the Users must accept documents in effect for that client. If the user hasn’t accepted the current version of one, they see a page listing each such document by its title, linked to its public page, with a box to tick.
- Accept with every box ticked records, for each document, the user, the version shown and the time. The sign-in then goes on to the consent screen or back to the client.
- Decline sends the client the error
access_denied. Nothing is stored, and the user stays signed in, so the next sign-in asks again.
A user is asked at every sign-in, single sign-on included, until they accept. A document accepted once counts on every client it applies to. Each new version is asked again, at the user’s next sign-in to a client it covers.
Where the page can’t be shown:
| Request | While a document is owed |
|---|---|
A sign-in with prompt=none |
Answered interaction_required. |
| The password grant | Refused with invalid_grant, until the user accepts in the browser. |
| A refresh token | Keeps working. An offline refresh token keeps refreshing for up to its lifetime without the new version accepted. |
| The client credentials grant | Unaffected: there’s no user. |
The admin console’s own sign-in never asks, so users can always reach their Account pages. The audit log records each acceptance as accepted_legal_document, and each decline as declined_legal_documents.
What users accepted
Section titled “What users accepted”Each user sees the documents they accepted under Account, Legal documents: each document’s title, the version they accepted and when, linked to that version’s public page. A retired document shows No longer in effect instead of a link.
On a user’s page in the admin console, the Legal documents tab lists the same. Click View text to read the exact version the user accepted, a retired document’s included.
Which clients a document applies to
Section titled “Which clients a document applies to”A document applies to every client until you choose otherwise. On its Applies to tab, pick one:
| Choice | The document applies to |
|---|---|
| All apps | Every client, including clients you add later. |
| Selected apps | Only the clients you tick in the list below it. |
Click Save to keep your choice. It takes effect at once and publishes no new version, so users who accepted the current version aren’t asked again. A user who never accepted it is asked at their next sign-in to a client it now covers.
Retiring a document
Section titled “Retiring a document”A published document can’t be deleted, since that would destroy the record of which version users accepted. Retire it instead: on its page, click Retire and confirm.
To bring it back, click Restore.
Deleting a document
Section titled “Deleting a document”A document that was never published can be deleted, since nobody has seen it. On its page, or on the list, click Delete, type its short name, and click Delete document. Its draft goes with it.