Glossary
This page tells you what each word in the docs means, so you can read any page without guessing.
Each concept has one name, the one the admin console uses, and the docs never swap in a synonym. When a page uses a term for the first time, it explains it in a few words and links here or to the term’s concept page.
Words we use
Section titled “Words we use”Sign in and sign out are the verbs: “sign in to the admin console”, “the user signs out”. Sign-in is the noun: “the sign-in page”, “a sign-in that took too long”.
The docs never say log in, log out, login or logout in prose. Two things keep their own spelling:
- Protocol names, which are spelled as the protocol spells them:
prompt=login,login_hint,/auth/logout. - UI labels, which are quoted exactly as the screen shows them.
Your app is the software you’re building, the one you register in Goiabada as a client. The docs don’t use it for anything else.
Access token
Section titled “Access token”A token a client sends to an API to show what it’s allowed to do. Goiabada issues access tokens as signed JWTs, and an API checks the signature against the auth server’s public keys at /certs. See Tokens.
Authentication Context Class Reference: how strongly the user signed in. Goiabada has three levels, urn:goiabada:level1 (password), urn:goiabada:level2_optional (password, plus a one-time code if the user has two-factor authentication) and urn:goiabada:level2_mandatory (password and a one-time code). See ACR and AMR.
Admin console
Section titled “Admin console”The web app where you manage clients, users, groups, resources, permissions and settings. It’s a client of the auth server and reaches the database only through the auth server.
Administrator
Section titled “Administrator”A user, group or client holding one of the administrative permissions on the authserver resource, such as authserver:manage, and also the admin console’s own client, and any client allowed to request the administrative scopes. Only authserver:manage can make someone an administrator or change one. See Administrators.
Authentication Methods References: which methods the user signed in with. Goiabada uses pwd (password), otp (one-time code) and recovery_code (a recovery code entered instead of a one-time code). See ACR and AMR.
Attribute
Section titled “Attribute”A key and a value you add to a user or a group. A client gets a user’s attributes, and those of the user’s groups, in the user’s claims when it asks for the attributes scope and the attribute is set to be included.
Audit log
Section titled “Audit log”The record of security events: sign-ins, failed passwords, changes an administrator makes, and more. See Audit log.
Auth server
Section titled “Auth server”The server that signs users in and issues tokens. It serves the OAuth2 and OpenID Connect endpoints, the sign-in pages and the API the admin console uses.
Authorization code
Section titled “Authorization code”A short-lived, single-use code the auth server sends to a client after the user signs in. The client exchanges it at /auth/token for tokens. See Add sign-in to a web app.
Back-channel logout URI
Section titled “Back-channel logout URI”An address on your app’s server where the auth server tells your app that a user’s session ended, by POSTing a logout token to it directly rather than through the browser. You register it on the client’s Back-channel logout tab. See Back-channel logout.
The look the sign-in pages and the admin console are drawn in: a name, an appearance (automatic, light or dark), a theme, which is one of eight built-in palettes or a custom palette of your own colors, and a kit of a logo, a favicon, a background image, a font and corners. It can also hold footer links and a support contact, drawn under the card. A client’s pages are drawn in the brand chosen for it, or in the default brand when none is, and the admin console in the brand of the admin console’s own client, whose admin pages take only its colors and logo. See Clients, Brands and themes, Footer links and support contact and Branded emails.
One piece of information inside a token, such as sub (who the user is) or email.
Client
Section titled “Client”An application that asks the auth server for tokens: your app, an API calling another API, or the admin console itself. A client is identified by its client identifier, the client_id it sends. The sign-in pages and the account pages call it an application, since that’s how the person signing in knows it. See Clients.
- A confidential client runs on a server and has a client secret.
- A public client runs where it can’t keep a secret, such as a browser or a phone, so it has none and must always use PKCE.
Consent
Section titled “Consent”A user’s approval for a client to receive what it asked for. The auth server asks for it when the client has “Ask users for consent” turned on, when the client asks for offline_access, or when the request says prompt=consent. It also asks when a client other than the admin console’s asks for authserver:manage-account and the user hasn’t approved that scope for it yet. An earlier approval can skip the screen on later sign-ins, as Consent required describes. Users can revoke a consent under “Consents” in their account.
Demonstrating Proof of Possession (RFC 9449): your app signs a short JWT, a proof, with a private key it holds, and sends it in a DPoP header with each token request. The access token it gets is bound to that key, with token_type DPoP and the key’s thumbprint as cnf.jkt, so a copy of it is useless without the key. See DPoP.
Dynamic client registration (DCR)
Section titled “Dynamic client registration (DCR)”A way for a client to register itself, by calling /connect/register, instead of an administrator creating it in the admin console. It’s off until you turn it on. See Let clients register themselves (DCR).
Email template
Section titled “Email template”What one of the auth server’s emails says: its subject, its body and, for an email with a button, its button label, in each of the six built-in languages. You edit it under Admin, Email, on the Email templates tab. The body is a small set of Markdown with placeholders such as {{name}}, and the email’s brand draws the rest. See Email templates.
What one sign-in gives a client: its refresh token, every refresh token that one is rotated into, and every access token issued with them, which carry its identifier as grant_id. A password grant makes one too. Tokens from the client credentials flow and the implicit flow belong to no grant. Your app ends a grant by sending its refresh token, or an access token of it that hasn’t expired, to /auth/revoke. See Refresh tokens.
A set of users. Permissions and attributes you give a group apply to every user in it. See Users and groups.
ID token
Section titled “ID token”A token that tells a client who the user is and how they signed in. Only clients that ask for the openid scope get one. See Tokens.
Implicit flow
Section titled “Implicit flow”A deprecated flow in which the browser comes back from sign-in with the tokens themselves rather than an authorization code. It’s off by default. See Implicit flow.
Introspection
Section titled “Introspection”An API asking the auth server whether a token is still active, at /auth/introspect. The API calls as a confidential client, and an access token is active to it only when its aud names one of that client’s introspection resources, which you set on the client’s Introspection tab. See Introspection resources.
Legal document
Section titled “Legal document”A privacy notice or terms of use you write in the admin console, under Legal documents, and publish as numbered versions that never change. A document’s kind says what users do with it: they accept each version of one marked Users must accept, and read one marked For information. See Publish legal documents.
Logout token
Section titled “Logout token”A signed JWT the auth server sends to a client’s back-channel logout URI when a session the client was on ends. It names the user (sub) and, unless it’s about every session of the user, the session (sid), so the app can end its own session for them. Its header says typ logout+jwt, which tells it apart from an ID token. See Back-channel logout.
Permission
Section titled “Permission”Something a resource lets you do, such as manage on the authserver resource. You give permissions to users, groups and clients, and a client asks for one as a scope written resource:permission, like authserver:manage. See Resources and permissions.
Proof Key for Code Exchange: a check that ties an authorization code to the client that asked for it, so a stolen code is useless. Public clients must always use it. See PKCE.
Recovery code
Section titled “Recovery code”A single-use code that signs a user in instead of a one-time code from their authenticator app, when they’ve lost it. Each authenticator comes with ten, shown once. See Require two-factor authentication.
Redirect URI
Section titled “Redirect URI”The address the auth server sends the browser back to after sign-in, carrying the authorization code. It must be one of the redirect URIs registered on the client.
Refresh token
Section titled “Refresh token”A token a client exchanges for new tokens without asking the user to sign in again. A client that asks for the offline_access scope gets an offline refresh token, which keeps working after the user’s session expires. See Refresh tokens.
Refresh-token rotation
Section titled “Refresh-token rotation”What happens to a refresh token when it’s used: the auth server retires it and hands back a new one, so each refresh token is good for one refresh. A retired one sent again is a replay, which revokes every live refresh token descended from the same grant, its rotation family. Not to be confused with secret rotation or signing-key rotation. See Refresh tokens.
Resource
Section titled “Resource”Something you protect, usually an API, and the permissions that go with it. Goiabada’s own resource is authserver. See Resources and permissions.
Resource Owner Password Credentials (ROPC)
Section titled “Resource Owner Password Credentials (ROPC)”A deprecated flow, also called the password grant, in which a client sends a user’s email and password to the token endpoint for tokens. It’s off by default. See ROPC.
Safe mode
Section titled “Safe mode”Drawing the pages without a brand’s custom CSS, custom palette and uploaded font, so you can sign in and fix a brand that made them unusable. Nothing saved changes. See Safe mode.
What a client asks for when it requests a token. There are two kinds: OpenID Connect scopes, such as openid, profile and email, which give access to the user’s information, and permission scopes, written resource:permission. See Scopes.
Secret rotation
Section titled “Secret rotation”Replacing one of the secrets your deployment holds with a new one: a server’s session keys, the AES key, the database password or the admin console’s client secret, each without signing anybody out or with the shortest interruption that secret allows. See Rotate secrets.
Self-registration
Section titled “Self-registration”A user creating their own account from the sign-in page’s Create an account link, instead of an administrator creating it. See Self-registration.
Session
Section titled “Session”What lets a user sign in once and use several clients. After the user signs in, the auth server keeps a session for their browser, so the next client they use doesn’t ask for the password again. A session ends when it has been idle too long, when it reaches its maximum lifetime, or when it’s ended: by the user or an administrator, by signing out, or by a change to the user’s credentials. See Sessions and Ending sessions.
Sign-out redirect URI
Section titled “Sign-out redirect URI”An address the auth server may send the browser back to after a sign-out, such as an app’s “You’re signed out” page. It must exactly match one of the sign-out redirect URIs registered on the client, a list kept apart from its redirect URIs. The protocol calls it post_logout_redirect_uri. See Sign-out redirect URIs.
Signing-key rotation
Section titled “Signing-key rotation”What Rotate keys under Admin, Signing keys does: the next signing key starts signing tokens, the current one becomes the previous one, and the old previous one is deleted, so a token it signed no longer verifies. See The key set.
Silent request
Section titled “Silent request”An authorization request with prompt=none, which checks for a session without showing the user anything. It comes back with a code when the session is enough, and with an error, such as login_required, when it isn’t. See prompt.
Single sign-on (SSO)
Section titled “Single sign-on (SSO)”Signing in once and using several clients without signing in again, which the session makes possible. See Single sign-on across clients.
Step-up
Section titled “Step-up”Asking a user who already has a session for more, usually a one-time code, because a client needs a stronger ACR level than the session reached. The session moves up to that level. See ACR and AMR.
Subject
Section titled “Subject”The identifier the auth server gives each user when they’re created. It never changes, and it’s the sub claim in every token about the user. See Users and groups.
Two-factor authentication
Section titled “Two-factor authentication”Signing in with a password and a one-time code from an authenticator app. In the admin console, you set it up under Account, in Two-factor authentication. See Require two-factor authentication.
A person who signs in. A user has a profile, an email address, a password, and optionally two-factor authentication, and can belong to groups. See Users and groups.