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) and otp (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.
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. 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 “Consent required” 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. See Consent required for the full rule. Users can revoke a consent under “Manage consents” in their account.
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).
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.
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.
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.
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 Register 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.
Signing-key rotation
Section titled “Signing-key rotation”What Rotate key under Admin, 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.