OpenID Connect scopes

Besides the authorization scopes that are formed by resources and permissions (as explained in Resources and permissions), Goiabada supports typical OpenID Connect scopes.

Available OIDC scopes

OIDC scope	Description
openid	Will include an id_token in the token response, with the subject identifier (sub claim)
profile	Access to claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at
email	Access to claims: email, email_verified
address	Access to the address claim
phone	Access to claims: phone_number and phone_number_verified
groups	Access to the list of groups the user belongs to
attributes	Access to the attributes assigned to the user by an admin, stored as key-value pairs
offline_access	Access to a refresh token of the type Offline, allowing the client to obtain a new access token without requiring immediate user interaction

Example usage

When making an authorization request, include the scopes you need:

GET /auth/authorize?
  client_id=my-app&
  redirect_uri=https://my-app.com/callback&
  response_type=code&
  scope=openid profile email groups&
  code_challenge=...&
  code_challenge_method=S256

The claims corresponding to the requested scopes are always available via the /userinfo endpoint. By default, they are also included in the ID token, but this can be configured globally or per-client (see OIDC claims in tokens below).

Scope to claims mapping

When you request a scope, the following claims become available:

Scope	Claims in UserInfo response / ID token (if enabled)
openid	sub (always included)
profile	name, given_name, middle_name, family_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at
email	email, email_verified
address	address (structured object with formatted, street_address, locality, region, postal_code, country)
phone	phone_number, phone_number_verified
groups	groups (array of group identifiers)
attributes	attributes (key-value map of custom attributes)

OIDC claims in tokens

ID token vs UserInfo endpoint

According to the OpenID Connect specification (OIDC Core 5.4), scope-related claims (from profile, email, phone, address scopes) MAY be included in ID tokens but SHOULD be retrieved from the /userinfo endpoint for strict conformance.

Goiabada gives you control over this behavior:

• Default: Claims are included in ID tokens (matches industry practice - Auth0, Microsoft, Keycloak)
• Strict OIDC conformance: Disable claims in ID tokens, forcing applications to use /userinfo
• Hybrid approach: Configure per-client based on application requirements

Configuration

Global setting - Navigate to Settings → Tokens in the admin console:

• Include OIDC claims in ID tokens: Controls default behavior for all clients
• Default: Enabled (matches industry standards)

Per-client override - In the client’s Tokens settings:

• Include OIDC claims in ID tokens: Three options
  • default - Use the global setting
  • on - Always include claims in ID tokens for this client
  • off - Never include claims in ID tokens for this client (use /userinfo only)

When to disable

Consider disabling OIDC claims in ID tokens when:

• Strict OIDC conformance required - Regulatory or security requirements mandate standard-compliant behavior
• Token size concerns - ID tokens are included in every redirect, smaller tokens improve performance
• Claim freshness important - Force applications to fetch current data from /userinfo instead of cached token claims
• Security policy - Separation of authentication (ID token) from user data (UserInfo endpoint)

Important notes

Note

• Core OpenID claims (sub, iss, aud, exp, iat, auth_time, nonce, acr, amr) are always included in ID tokens regardless of this setting
• The groups and attributes scopes are Goiabada-specific extensions and follow their own inclusion rules
• Claims are always available via the /userinfo endpoint regardless of this setting