prompt

This page helps you control what the user sees when your app sends them to sign in.

prompt is an OpenID Connect parameter of the authorization request. It takes three values:

Value	What the auth server does
none	Shows the user nothing. It answers with a code if the browser’s session is enough, and with an error if it isn’t. This is a silent request.
login	Asks the user to sign in, even when the browser has a session.
consent	Shows the consent screen, even when the user has already approved what your app asks for.

Leave prompt out and the auth server decides: it uses the browser’s session when there’s a valid one, which is single sign-on, and asks the user to sign in when there isn’t.

Check for a session silently

1. Send the authorization request with prompt=none. Add id_token_hint when you know which user to expect:

   GET /auth/authorize?client_id=my-app&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&response_type=code&scope=openid%20profile&prompt=none&code_challenge=...&code_challenge_method=S256&state=... HTTP/1.1
   Host: auth.example.com

2. If the session is enough, the browser comes straight back to your redirect URI with a code, and the user sees no page:

   HTTP/1.1 302 Found
   Location: https://app.example.com/callback?code=...&state=...

   Redeem it at the token endpoint as usual.

3. If it isn’t, the browser comes back with an error instead, such as login_required. Send the user through the same request without prompt=none, so they can sign in. See login_required.

Caution

A client that registered itself gets no error back from a silent request: the auth server never redirects an error to one. Treat a silent request that doesn’t come back as “send the user through an ordinary sign-in”. See The app gets no error back.

Values

Separate values with a single space. login and consent go together: prompt=login consent asks the user to sign in and then shows the consent screen. none goes alone, and none with anything else is refused with invalid_request, as is a value Goiabada doesn’t know.

select_account is defined by OpenID Connect, but the auth server can’t ask a user to choose an account, so it’s refused with account_selection_required. Discovery lists the three values it supports in prompt_values_supported.

The silent checks

With prompt=none, the auth server makes the checks it would otherwise show the user a page for, in this order, and answers with the first that fails:

Check	error	error_description
The browser has a session	login_required	“User authentication is required”
The session is within its idle timeout and maximum lifetime	login_required	“User session has expired”
The user signed in within the request’s max_age, when it has one	login_required	“Session age exceeds max_age”
The user is enabled	access_denied	“The user account is disabled”
The session’s user is the one the id_token_hint names, when there’s a hint	login_required	“The current session user does not match the id_token_hint”
The session reached the request’s ACR level	interaction_required	“Higher authentication level required”
The user has two-factor authentication, when the level is urn:goiabada:level2_mandatory	interaction_required	“Additional authentication setup required”
The user’s two-factor authentication hasn’t changed since the session was last checked for a second factor, when the level is above urn:goiabada:level1	interaction_required	“Authentication configuration has changed”
The user holds at least one of the scopes asked for	access_denied	“The user is not authorized to access any of the requested scopes”
The user has consented to the client, when it requires consent, the request asks for offline_access, or the scope holds authserver:manage-account and the client isn’t the admin console’s	consent_required	“User consent is required”
That consent covers every scope the user would get, or only authserver:manage-account when that alone is why it’s checked	consent_required	“Additional consent is required”

When every check passes, the auth server issues the code and records the session’s activity, so it doesn’t idle out. Just before it does, it checks the user again: when the session’s methods include otp and the user no longer has the authenticator that code came from, the answer is login_required with “User authentication is required”. That’s an authenticator removed while the request was under way, whether or not the user set up another one since. The ID token’s auth_time is when the user last signed in, not the time of the silent request, and its acr is the session’s level when that’s higher than the one asked for.

The auth server redirects each error to your redirect URI with your state, in the request’s response mode. A request with prompt=none that fails validation, such as one with a scope that doesn’t exist, is answered at once too, rather than after a sign-in.

prompt=login

The auth server doesn’t use the browser’s session to skip the sign-in, or to skip any part of it: whoever is at the browser enters a password, and a one-time code too whenever the request’s level needs one, whatever the session already gave. The ID token’s acr, amr and auth_time all describe this sign-in.

What happens to the session that was in the browser depends on who signs in:

• The same user. Their session is kept, as long as it’s still valid, and takes this sign-in’s level, methods and time, which can be lower than what it held. See A session that’s already there. A session that has idled out, reached its maximum lifetime or fallen outside the request’s max_age is replaced by a new one, with nothing revoked.
• Someone else. The other user’s session is ended, as described in A different user signs in on the same browser.

max_age can ask for a sign-in too, but only when the last one is older than the number of seconds it gives. Use prompt=login when you always want a fresh sign-in, and max_age when a recent one is enough. With both, prompt=login wins.

prompt=consent

The auth server shows the consent screen after the sign-in, even when the user has already approved every scope your app asks for. Use it when your app should hear the user’s answer again, for example after it starts asking for more. See Consent required.

Next steps

login_requiredWhy a silent request came back with an error, and what to do.

id_token_hintMake sure a sign-in comes back for the user you expect.

SessionsHow long a session lasts, and what ends it.