Authorize
Send the browser to the authorization endpoint with a pushed request reference, and handle the code or error that comes back.
On this page
The authorization endpoint is where the person signs in and agrees to share. It is a browser endpoint: your application redirects the person to it, identity shows its own pages, and identity redirects back to you with a one-time code.
Request#
GET the authorization_endpoint from discovery, which is /authorize, with exactly two query parameters.
| Parameter | Value |
|---|---|
client_id | Your client identifier. It must be the client that pushed the request. When the oauth_cimd flag is on (it defaults OFF), this may be an https URL that names your client metadata document. |
request_uri | The request_uri from the pushed authorization request. |
https://identity.tdacorp.in/authorize?client_id=tdaid_c_example&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3AQm9ndXNFeGFtcGxlAny other parameter is refused with invalid_request, and so is a repeated one. Scope, redirect address, state and the rest were fixed when you pushed, so nobody can alter them by editing the link.
What the person sees#
Identity looks at the person's session and decides.
| Situation | What happens |
|---|---|
| A live session satisfies the request | No page. Identity redirects back at once with a code. |
No session, or prompt=login or prompt=create was pushed | The sign-in page. |
max_age was pushed and the last sign-in is older | The sign-in page again. When acr_values also asks for aal2 or more, only the second factor step. |
acr_values asks for a stronger level than the session has | A step-up page asks for a stronger method. |
The client needs a workspace and the person has none (and prompt=none was not pushed) | The sign-in's workspace step, where the person creates their own. |
The tenant requires single sign-on (the sso_enforcement flag, default OFF) and the person has not entered through one of its connections | The sign-in step offers that tenant's connections. Under prompt=none, identity redirects back with interaction_required. |
| A third-party client asks for something not yet agreed | The consent page. A first-party client skips it. |
prompt=none was pushed and any of the above would be needed | No page. Identity redirects back with login_required or consent_required. |
The sign-in and consent pages are described in Your account and Scopes and consent. Their addresses and their form fields are private; do not link to them.
A session that was started through one organization's single sign-on connection is not used for an organization that connection is not linked to: the person gets the sign-in page, or login_required under prompt=none. When you push no organization and the client does not require one, but its app is not installed in the person's current organization, the code is issued with no organization (no tid) instead of being refused.
The language of those pages comes from the person's saved language first, then from the ui_locales you pushed, then from their browser. You set ui_locales when you push the request, not on this address, and a link that carries it is refused like any other extra parameter. See Languages.
Response#
Identity redirects to your registered redirect_uri, in the response_mode you pushed. With query the values are in the query string. With form_post identity returns a small page that posts them to your address.
Success#
| Member | Meaning |
|---|---|
code | A single-use authorization code. It lives at most 60 seconds. |
state | Exactly what you pushed. |
iss | The issuer, per RFC 9207. |
https://app.example.com/api/auth/callback?code=Zm9vYmFy&state=Yzk3...&iss=https%3A%2F%2Fidentity.tdacorp.inError#
When identity can safely return an error to your redirect address, the redirect carries these members instead.
| Member | Meaning |
|---|---|
error | An OAuth code from the table below. |
error_description | Text for your logs, not for a person. |
state | Exactly what you pushed. |
iss | The issuer. |
Errors#
error | Delivered how | When |
|---|---|---|
login_required | Redirect | prompt=none and the person would need to sign in or step up. |
consent_required | Redirect | prompt=none and the request needs consent not yet given. |
access_denied | Redirect | The person declined, the account is not an active member of the requested organization, the client's app is not installed in it, or a client that needs an organization had none under prompt=none. |
invalid_target | Redirect | A resource you pushed is not installed in the chosen organization. |
invalid_request, invalid_request_uri | Direct | The link carries another parameter, the reference is unknown, expired or already used, client_id does not match the reference, or the client's registration changed in the last minute. |
unauthorized_client, invalid_scope | Direct | The client was suspended, lost the code grant, or lost a scope after the push. |
A direct error is not sent to your redirect address, because identity cannot yet trust it. A browser sees a page on identity's own site; a non-browser caller receives a 400 JSON body. Your code will not see these as redirects: log them on your side and show the person a general failure.
The reference is spent by being presented. If the sign-in fails and you want to try again, push a new request.
What your callback must check#
Do these in order before you spend the code. The SDK does them in handleCallback.
- The stored transaction exists, belongs to this issuer and client, and has not expired.
issis present and equals the issuer the flow started at. A missingissis a failure, not a pass.stateequals the value you stored for this browser. If not, stop.- If
erroris present, report it. Do not try to use acode. - Only then take
codeand exchange it at the token endpoint with the stored PKCE verifier.
Security notes#
- Keep the transaction sealed. It holds the PKCE verifier and the nonce. If a person can edit it, the checks that read it mean nothing.
- Never put a code in a log or a URL you keep. It lives at most 60 seconds and works once, but a leaked live code with a leaked verifier is a signed-in session.
- A code is bound to your client and your redirect address. The token request must repeat the same
redirect_uri. - Do not skip
iss. It stops a malicious server from passing you a code meant for another issuer.