Skip to Content

OpenID Connect (Authorization Code + PKCE)

Przepływ OIDC Authorization Code z PKCE od początku do końca, na czystym HTTP i curl, abyś rozumiał każdy krok, zanim sięgniesz po bibliotekę.

Ten przewodnik przeprowadza przez przepływ Authorization Code z PKCE, używając wyłącznie HTTP, dzięki czemu widzisz dokładnie, co każdy krok wysyła i odbiera. Przewodniki dla Node i React robią to samo za pomocą biblioteki; ten przeczytaj najpierw.

Upewnij się, że masz zarejestrowaną aplikację i redirect URI, jak opisano w sekcji Zanim zaczniesz.

Przepływ na jednym obrazku

  1. Twoja aplikacja przekierowuje przeglądarkę do punktu końcowego autoryzacji wraz z PKCE challenge.
  2. Użytkownik się loguje; platforma przekierowuje z powrotem na Twój redirect URI z jednorazowym parametrem code.
  3. Twoja aplikacja wymienia code (wraz z PKCE verifier) na punkcie końcowym tokenu na ID token i access token.
  4. Twoja aplikacja weryfikuje ID token i opcjonalnie wywołuje punkt końcowy UserInfo.

1. Utwórz PKCE verifier i challenge

Wygeneruj losowy code verifier, a następnie wyprowadź z niego code challenge SHA-256:

# code verifier: 43-128 chars of unreserved characters
CODE_VERIFIER=$(openssl rand -base64 60 | tr -d '\n=+/' | cut -c1-64)

# code challenge: base64url(SHA256(verifier))
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -binary -sha256 | openssl base64 | tr '+/' '-_' | tr -d '=\n')

echo "verifier:  $CODE_VERIFIER"
echo "challenge: $CODE_CHALLENGE"
import { createHash, randomBytes } from 'node:crypto';

const codeVerifier = randomBytes(48).toString('base64url'); // 64 chars
const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');

console.log('verifier: ', codeVerifier);
console.log('challenge:', codeChallenge);
import base64, hashlib, secrets

code_verifier = secrets.token_urlsafe(48)  # 64 chars
digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()

print("verifier: ", code_verifier)
print("challenge:", code_challenge)
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.util.Base64;

var random = new byte[48];
new SecureRandom().nextBytes(random);
var encoder = Base64.getUrlEncoder().withoutPadding();

var codeVerifier = encoder.encodeToString(random); // 64 chars
var codeChallenge = encoder.encodeToString(
    MessageDigest.getInstance("SHA-256").digest(codeVerifier.getBytes(StandardCharsets.US_ASCII)));

System.out.println("verifier:  " + codeVerifier);
System.out.println("challenge: " + codeChallenge);
using System.Security.Cryptography;
using System.Text;

static string B64Url(byte[] bytes) =>
    Convert.ToBase64String(bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_');

var codeVerifier = B64Url(RandomNumberGenerator.GetBytes(48)); // 64 chars
var codeChallenge = B64Url(SHA256.HashData(Encoding.ASCII.GetBytes(codeVerifier)));

Console.WriteLine($"verifier:  {codeVerifier}");
Console.WriteLine($"challenge: {codeChallenge}");
import (
	"crypto/rand"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
)

random := make([]byte, 48)
rand.Read(random)

codeVerifier := base64.RawURLEncoding.EncodeToString(random) // 64 chars
sum := sha256.Sum256([]byte(codeVerifier))
codeChallenge := base64.RawURLEncoding.EncodeToString(sum[:])

fmt.Println("verifier: ", codeVerifier)
fmt.Println("challenge:", codeChallenge)
function b64url(string $bytes): string {
    return rtrim(strtr(base64_encode($bytes), '+/', '-_'), '=');
}

$codeVerifier = b64url(random_bytes(48)); // 64 chars
$codeChallenge = b64url(hash('sha256', $codeVerifier, true));

echo "verifier:  $codeVerifier\n";
echo "challenge: $codeChallenge\n";
use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
use rand::RngCore;
use sha2::{Digest, Sha256};

let mut random = [0u8; 48];
rand::thread_rng().fill_bytes(&mut random);

let code_verifier = URL_SAFE_NO_PAD.encode(random); // 64 chars
let code_challenge = URL_SAFE_NO_PAD.encode(Sha256::digest(code_verifier.as_bytes()));

println!("verifier:  {code_verifier}");
println!("challenge: {code_challenge}");

Zachowaj verifier na potrzeby kroku 3. Wygeneruj też losowy state (a jeśli go sprawdzasz, również nonce), aby zabezpieczyć się przed cross-site request forgery i atakami powtórzeniowymi.

2. Wyślij użytkownika do punktu końcowego autoryzacji

Otwórz ten adres URL w przeglądarce (tutaj złamany dla czytelności):

https://<your-domain>/authorize
  ?response_type=code
  &client_id=<your-client-id>
  &redirect_uri=https://app.example.com/callback
  &scope=openid%20profile%20email%20offline_access
  &state=<random-state>
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256
  • scope musi zawierać openid. Dodaj profile i email dla standardowych claimów oraz offline_access, jeśli chcesz otrzymać refresh token.
  • Po zalogowaniu użytkownika platforma przekierowuje pod adres https://app.example.com/callback?code=<one-time-code>&state=<random-state>.
  • Sprawdź, czy zwrócony state zgadza się z tym, który wysłałeś, zanim przejdziesz dalej.

3. Wymień kod na tokeny

Wyślij kod i PKCE verifier metodą POST do punktu końcowego tokenu.

W przypadku klienta confidential uwierzytelnij się client secretem (tutaj pokazano HTTP Basic):

curl -X POST https://<your-domain>/oauth/token \
  -u '<your-client-id>:<your-client-secret>' \
  -d grant_type=authorization_code \
  -d redirect_uri=https://app.example.com/callback \
  -d code=<one-time-code> \
  -d code_verifier=$CODE_VERIFIER

W przypadku klienta public (bez secretu) wyślij client_id jako pole formularza i oprzyj się na PKCE:

curl -X POST https://<your-domain>/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=<your-client-id> \
  -d redirect_uri=https://app.example.com/callback \
  -d code=<one-time-code> \
  -d code_verifier=$CODE_VERIFIER

Odpowiedź zawiera tokeny:

{
  "access_token": "<jwt>",
  "id_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<token>",
  "scope": "openid profile email offline_access"
}

Pole refresh_token pojawia się tylko wtedy, gdy zażądałeś offline_access, a aplikacja może taki token otrzymać.

4. Zweryfikuj ID token

ID token to JWT, który potwierdza, kto się zalogował. Zweryfikuj go, zanim mu zaufasz:

  • Sprawdź podpis względem kluczy podpisywania platformy pod adresem /.well-known/jwks.
  • Sprawdź, czy iss odpowiada Twojej instancji, aud Twojemu client ID oraz czy token nie wygasł (exp).
  • Jeśli wysłałeś nonce, sprawdź, czy się zgadza.

Claim sub to stabilny identyfikator użytkownika; scope'y profile i email dodają claimy takie jak name i email.

5. Wywołaj UserInfo (opcjonalnie)

Po claimy wykraczające poza ID token wywołaj punkt końcowy UserInfo z access tokenem:

curl https://<your-domain>/userinfo \
  -H 'Authorization: Bearer <access_token>'

6. Wyloguj użytkownika (opcjonalnie)

Aby zakończyć sesję, wyślij użytkownika do punktu końcowego end session:

https://<your-domain>/logout
  ?id_token_hint=<id_token>
  &post_logout_redirect_uri=https://app.example.com/

Najpierw zarejestruj post_logout_redirect_uri przy swojej aplikacji, tak samo jak rejestrujesz redirect URI.

Rozwiązywanie problemów

  • Niezgodność redirect_uri. Wartość redirect_uri w krokach 2 i 3 musi być identyczna w obu miejscach i dokładnie odpowiadać wartości zarejestrowanej przy aplikacji.
  • invalid_grant na punkcie końcowym tokenu. Kod jest jednorazowy i krótko żyjący; poproś o nowy. Ten błąd pojawia się również wtedy, gdy code_verifier nie pasuje do wysłanego code_challenge.
  • invalid_client. Uwierzytelnianie klienta jest nieprawidłowe: klient confidential musi wysłać swój secret; klient public nie może tego robić i musi być zarejestrowany jako klient public (PKCE).

Dalsze kroki

Na tej stronie