Consent screens

When a person sees the consent screen, exactly what it shows, what each choice does to your tokens, and how to build an application that copes.

On this page

A third-party application that asks to sign a person in is asking for access to part of their account. The consent screen is where the person decides. You do not draw it and you cannot change it, but you decide what it asks, and your application has to work with every answer.

When it appears#

Third-party clients only. A first-party client, one that TDACorp ships, never shows it.
The first time, and again whenever you ask for a scope the person has not already granted. Identity remembers the grant per person and per client. If everything you ask for is covered, the person goes straight through.
Whenever you force it with prompt=consent, for a third-party client. With prompt=none it is never shown, and a request that would need it fails with consent_required.

It comes after sign-in and after the choice of organization, if the person has more than one. The organizations offered are only those your client may enter: its own, or one where your product is installed. If your client requires an organization and the person has none, sign-in shows a step titled Create your workspace first, with a Create my workspace button that makes a personal workspace on their confirmation; a request that names an organization never gets that step. If the organization requires single sign-on (the sso_enforcement flag, which defaults OFF), sign-in shows Sign in with your organization and a Continue with button for the organization's connection, and the consent screen follows once that sign-in is done.

What it shows#

The window is titled Allow access. The heading is Allow followed by your client's name and to access your account?, with the line It will be able to see what you allow below. A notice under it, This application is not verified by TDACorp., tells the person that nobody at TDACorp vouches for your application. Then comes the list under This application is asking for, and two buttons, Allow and Deny.

The screen is built to show a logo, a Verified application badge and links to a privacy policy (Privacy policy) and terms (Terms of service) when a client has them. Today none of those is filled in for a client: the screen shows its name, taken from the registration, and the not-verified notice above. A client identified by a client ID metadata document (available only while the oauth_cimd flag is on, and it defaults OFF) also shows It is identified only by its web address: followed by the address's host. Choose the name carefully and make it the name people know your product by. See Get a client registered.

The scope list#

Each scope you asked for is a line. openid is fixed and marked Required. Every other scope is a checkbox that starts ticked, and the person can untick it. The line shows the title below, and nothing more.

Scope	What the line says
`openid`	Confirm who you are
`profile`	Your name and preferences
`email`	Your email address
`offline_access`	Stay signed in
`tdaid.tenant`	Your organization
A product scope such as `eidos`	Your eidos access

A scope identity does not recognise starts unticked, and its line is the raw scope string. Do not rely on one. Ask only for registered scopes, and only for what you need: a person who sees a list of things they do not understand clicks Deny.

Because the line is short, choose scopes whose meaning is clear from the title alone, and explain in your own product why you ask.

What each choice does#

Allow with every box ticked: your authorization code, and the tokens you redeem it for, carry every scope you asked for.

Allow with some boxes unticked: the grant is what is ticked, plus openid, added to any grant the person gave this client before. The code and the tokens carry those scopes only. Your token response says which in its scope field. The grant is stored. A later request shows the screen again unless every scope it asks for is already granted, so a request that includes the scope the person unticked asks again.

Deny: identity redirects to your redirect address with error=access_denied, your state and iss, and the description the user denied the request. No code is issued.

Build for every answer#

Read scope from the token response, not from what you asked for. It is the truth. The SDK returns it as tokens.scope.
Treat each optional scope as optional. If email is missing, your application must still work. Ask the person for the address inside your own product if you need it.
Handle access_denied as an ordinary outcome. Send the person back to a page that explains what they can do without signing in. Do not immediately start the flow again: they just said no.
Ask later for more, not up front. When a feature needs a scope you did not ask for at sign-in, start a new authorization asking for it. The person is shown the screen again with the new request. Their earlier grants are kept and added to, never replaced.
Do not assume the grant is permanent. The person can remove it at any time.

The person can take it back#

Every grant is listed under Connected apps in the person's account, with Revoke access for each. Revoking removes the grant and revokes your refresh tokens for that person. If your client has a back-channel logout address, it is told. The next sign-in shows the consent screen again. See Connected applications for the person's side.

A refresh token therefore stops working for a reason that is not a bug. Handle invalid_grant on refresh by sending the person through sign-in again. See Refresh tokens.