DocCheck Login Dokumentation
⌘ K

# PKCE (RFC 7636)

PKCE (Proof Key for Code Exchange) erweitert den OAuth2 Authorization Code Flow. Der Client sendet zuerst einen code_challenge und beweist beim Token Request mit dem passenden code_verifier, dass derselbe Flow fortgesetzt wird.

PKCE ist besonders sinnvoll für Public Clients, die kein client_secret sicher speichern können, zum Beispiel Mobile Apps oder Single Page Applications im Browser. Auch bei Confidential Clients kann PKCE als zusätzlicher Schutz des Authorization Codes verwendet werden.

PKCE Flow

# Basic-Beispiel

Der Authorization Request enthält den code_challenge. scope und state sind in diesem Basic-Beispiel nicht enthalten und werden nur ergänzt, wenn sie für den jeweiligen Client verwendet werden.

https://auth.doccheck.com/en/authorize?
  response_type=code&
  client_id=[login_client_id]&
  redirect_uri=[redirect_uri]&
  code_challenge=dmXzPRkt6o9MMUkToNpkSE4Gg2UGvtDcDPtbAuRTU74&
  code_challenge_method=S256

Der Token Request wird als application/x-www-form-urlencoded Body gesendet. Der code_verifier gehört in den Body, nicht nur in die URL-Parameter.

POST https://auth.doccheck.com/token
Content-Type: application/x-www-form-urlencoded

client_id=[login_client_id]
client_secret=[client_secret]
grant_type=authorization_code
code=[authorization_code]
redirect_uri=[redirect_uri]
code_verifier=N7gM2zYtJq9_PvW5aSx3.Lk8-rFc4uHn0Qe6TbZ1mAo

# Beispielwerte

Nur Beispiel

Dieses Wertepaar dient nur zur Dokumentation. Erzeugen Sie für jeden Authorization Request einen neuen kryptografisch zufälligen code_verifier.

code_verifier = N7gM2zYtJq9_PvW5aSx3.Lk8-rFc4uHn0Qe6TbZ1mAo
code_challenge = dmXzPRkt6o9MMUkToNpkSE4Gg2UGvtDcDPtbAuRTU74
code_challenge_method = S256

Der code_challenge wird so berechnet:

BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Verwenden Sie keinen SHA-256-Hex-String wie f67e2a0aff59af6cb8f02dcacf31eb1227b6e0fa6165e52971aee37439cb9117.

# Wichtig

  • code_verifier: 43 bis 128 Zeichen; erlaubt sind A-Z, a-z, 0-9, -, ., _, ~.
  • redirect_uri muss im Authorization Request und Token Request exakt identisch sein.
  • Confidential Clients können ein client_secret sicher speichern; PKCE ersetzt dieses Secret nicht automatisch.
  • Public Clients können kein client_secret sicher schützen; für sie ist PKCE besonders wichtig.

# Einstellungen in DocCheck Access

In DocCheck Access kann ein Login-Client als vertrauenswürdig konfiguriert werden. Das bedeutet: Der Client verwendet ein client_secret, das nur auf einem sicheren Backend gespeichert und nicht öffentlich im Browser oder in einer App weitergegeben werden darf.

Vertrauenswürdig aktiviert

Mit CORS für Hostnamen erlauben wird festgelegt, welche Browser-Origin DocCheck API-Endpunkte direkt aus JavaScript aufrufen darf. Tragen Sie hier nur Schema, Host und optional Port ein, zum Beispiel https://example.com oder https://localhost:8080.

Vertrauenswürdig und CORS für Hostnamen erlauben

# Typischer Fehler

invalid_grant
Failed to verify `code_verifier`

Häufige Ursachen: Hex-Encoding statt Base64URL, falscher code_verifier, geänderter code_verifier oder code_verifier nicht im form-url-encoded Body des Token Requests.

Referenz: RFC 7636 (opens new window), insbesondere Abschnitte 4.1 bis 4.6 und Appendix A.

ON THIS PAGE
Basic-Beispiel
Beispielwerte
Wichtig
Einstellungen in DocCheck Access
Typischer Fehler