Scopes
This page helps your app ask for the right scopes, and tells you which claims about the user each one gets you.
A scope is something a client asks for when it requests a token. There are two kinds:
- OpenID Connect scopes, such as
openid,profileandemail, which give your app information about the user, as claims. - Permission scopes, written
resource:permission, such asproduct-api:read, which let your app call an API. See Resources and permissions.
Ask for scopes
Section titled “Ask for scopes”-
Decide what your app needs. To know who the user is, ask for
openid. Addprofile,emailor another scope below for each piece of information you’ll use, and a permission scope for each API call. -
Put them in the
scopeparameter of the authorization request, separated by single spaces:GET /auth/authorize?client_id=my-app&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&response_type=code&scope=openid%20profile%20email%20product-api%3Aread&code_challenge=...&code_challenge_method=S256&state=... HTTP/1.1Host: auth.example.com -
Read the
scopein the token response. It’s what was granted, which can be less than you asked for.
Ask only for what you use: the user sees the list on the consent screen, when the client asks for consent.
OpenID Connect scopes and their claims
Section titled “OpenID Connect scopes and their claims”| Scope | Claims |
|---|---|
openid |
sub, the user’s subject. It also gets your app an ID token, and lets it call /userinfo. |
profile |
name, given_name, middle_name, family_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale and updated_at |
email |
email and email_verified |
address |
address, an object with formatted, street_address, locality, region, postal_code and country |
phone |
phone_number and phone_number_verified |
groups |
groups, the identifiers of the user’s groups |
attributes |
attributes, the user’s attributes and those of their groups, as keys and values |
offline_access |
No claim. It gets your app an offline refresh token, which keeps working after the user’s session ends. |
A claim with no value is left out rather than sent empty: a user with no nickname has no nickname. email_verified and phone_number_verified are always sent with their scope, address only when some part of the address is set, and picture only when the user has a profile picture. profile is the auth server’s base URL followed by /account/profile, where the auth server has no page: a user’s own profile is in the admin console, under Account, Profile, so don’t send users to the claim’s URL. locale is the language the user chose.
groups lists only the groups set to be included, and attributes only the attributes set to be included: see Users and groups.
groups and attributes are Goiabada’s own. offline_access is defined by OpenID Connect Core, section 11, and the rest by section 5.4.
Where the claims go
Section titled “Where the claims go”Your app can read the claims in three places.
/userinfoanswers with the claims of every OpenID Connect scope in the access token you call it with. The token must carryopenid.- The ID token carries them when Include OpenID Connect claims in the ID token is on, under Admin, Tokens. It’s on in a new installation.
- The access token carries them when Include OpenID Connect claims in the access token is on, on the same page, and the token carries
openid. It’s off in a new installation.
A client can override either setting on its own Tokens tab. Turn ID token claims off for a client that expects them only from /userinfo, as OpenID Connect describes when an access token is issued, or that needs a small ID token. Turn access token claims on when your API should read the user’s details from the token without calling /userinfo.
Neither setting decides groups and attributes. Each group and attribute has its own two settings instead: Include in access token for the access token, and Include in id token for the ID token and /userinfo.
The claims about the sign-in itself, such as sub, iss, aud, exp, auth_time and acr, are always in the ID token. See Tokens.
Permission scopes
Section titled “Permission scopes”A permission scope names a permission: product-api:read is the permission read on the resource product-api.
- When your app signs a user in, the token carries the permissions the user holds, directly or through a group, out of those it asked for. The rest are left out without an error, unless nothing is left: then the request is refused with
access_denied. - With the client credentials flow, the token carries the permissions the client itself holds. Leave
scopeout to get all of them. - The administrative scopes, such as
authserver:manage, need the client to be allowed to request them. See administrative scopes.
Scopes are case-sensitive and separated by exactly one space, with none at either end. Asking for offline_access alone is refused, since it grants nothing by itself. A scope the auth server doesn’t know, or a permission the client may not have, is refused with invalid_scope: see invalid_scope.