Skip to content

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.

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.

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.

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.

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.

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.

The record of security events: sign-ins, failed passwords, changes an administrator makes, and more. See Audit log.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Signing in once and using several clients without signing in again, which the session makes possible. See Single sign-on across clients.

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.

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.

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.