Redirect & State flow

ⓘEconomy+

Overview

How redirect_uri and state work in DocCheck login — concise, consistent, and secure.

Redirect (redirect_uri)

• After login, DocCheck redirects to the configured callback URL.
• Dynamic target pages are not controlled via redirect_uri but via state.
• HTTPS only. Do not pass personal data in the redirect_uri.

State

Use cases for state:

• Pass application status/parameters through the login (e.g., section/step).
• Choose a target after return (map a short key → internal URL).
• CSRF protection: compare a value set by the client before and after login.

Properties and format:

• Appended unchanged to the callback URL as a query parameter and returned by API endpoints in JSON.
• URL-encode; avoid problematic characters. Rule of thumb: A–Z a–z 0–9 - . _ ~ (percent-encode everything else) and keep to about 255 chars.
• Do not include full URLs or personal data in state.

Flow (short)

1. App generates state (random for CSRF + optional short key for targeting).
2. The login button passes state to DocCheck.
3. DocCheck appends state to your callback URL; APIs return state in their payload.
4. The app validates state (CSRF) and optionally resolves target mapping.

Examples

Login button with redirectUri and state:

<dc-login-button size="large" language="en" loginClientId="[CLIENT_ID]"
  redirectUri="https://yourserver.com/callback" state="section_orange"></dc-login-button>

Simple target mapping after a fixed callback (no dynamic redirect_uri):

$target = $_GET['state'] ?? '';
switch ($target) {
  case 'section_orange': header('Location: https://yourserver.com/orange'); break;
  case 'section_red':    header('Location: https://yourserver.com/red');    break;
  default: /* no redirect, default view */ ;
}

More examples: Passing data via state (tbd)

Security and best practices

• Always validate state (CSRF). Store before login, compare after return.
• Map only known keys to allowed targets (no open redirects).
• redirect_uri should only point to whitelisted HTTPS targets and be correctly encoded.
• Do not include personal data in state or redirect_uri.