Skip to Content

Client Financial-grade API (FAPI 2.0)

Adaptez un client au FAPI 2.0 Security Profile : private key JWT, pushed authorization requests et tokens sender-constrained via DPoP.

Requiresfapi

Remarque : Disponible avec les abonnements Advanced et Pro.

Basculer une application sur le FAPI 2.0 Security Profile change ce que son client doit envoyer. Un client qui fonctionnait auparavant cessera de fonctionner : le profil remplace le client secret par une assertion signée, exige que la requête d'autorisation soit d'abord transmise à un back-channel, et émet des access tokens liés à une clé détenue par le client.

Ce guide ne traite que des différences par rapport au flux Authorization Code avec PKCE. Lisez ce guide d'abord.

Ce qui change

Client standardClient FAPI 2.0
Authentification du clientClient secretPrivate key JWT, signé en PS256
Requête d'autorisationParamètres dans l'URL du navigateurTransmise d'abord, le navigateur reçoit une request_uri
PKCERecommandéExigé, S256
Access tokenBearerDPoP, lié à votre clé
Requêtes de tokenUn appelDeux au premier contact, pour le nonce DPoP

Avant de commencer

  1. Générez une paire de clés pour l'authentification du client. RSA (2048 bits ou plus) ou EC sur la courbe P-256.

  2. Enregistrez la clé publique sur l'application, puis basculez celle-ci sur le profil FAPI 2.0. Voir Financial-grade API security pour l'ordre à respecter.

  3. Générez une seconde paire de clés pour les preuves DPoP. Gardez-la séparée de la clé d'authentification du client, afin que chacune ait une seule fonction.

  4. Lisez le document de discovery. Il liste désormais également pushed_authorization_request_endpoint, et dpop_signing_alg_values_supported indique les algorithmes que les preuves peuvent employer.

    https://<your-domain>/.well-known/openid-configuration

Si l'API appelée par votre application émet des access tokens JWT, réglez également l'algorithme de signature de cette API sur PS256. Voir API.

1. Construire une client assertion

Chaque appel qui portait auparavant le client secret porte désormais un JWT de courte durée, signé avec la clé privée d'authentification de votre client. Les exemples utilisent la bibliothèque JOSE de chaque stack : jose pour Node.js, PyJWT (avec l'extra crypto) pour Python, Nimbus JOSE + JWT pour Java, Microsoft.IdentityModel.JsonWebTokens pour C#, lestrrat-go/jwx pour Go, web-token/jwt-framework pour PHP et josekit pour Rust.

import * as jose from 'jose';

const ISSUER = 'https://<your-domain>';
const CLIENT_ID = '<your-client-id>';

// Your client-authentication private key, plus the key id shown next to the
// registered key in the Admin Console.
const authKey = await jose.importPKCS8(process.env.CLIENT_AUTH_PRIVATE_KEY, 'PS256');
const KID = '<key-id-from-the-console>';

function clientAssertion() {
  return new jose.SignJWT({ jti: crypto.randomUUID() })
    .setProtectedHeader({ alg: 'PS256', kid: KID, typ: 'JWT' })
    .setIssuer(CLIENT_ID)
    .setSubject(CLIENT_ID)
    .setAudience(ISSUER)          // the issuer identifier, not the endpoint URL
    .setIssuedAt()
    .setExpirationTime('2m')
    .sign(authKey);
}
import os
import time
import uuid

import jwt

ISSUER = "https://<your-domain>"
CLIENT_ID = "<your-client-id>"

# Your client-authentication private key, plus the key id shown next to the
# registered key in the Admin Console.
AUTH_KEY = os.environ["CLIENT_AUTH_PRIVATE_KEY"]
KID = "<key-id-from-the-console>"

def client_assertion():
    now = int(time.time())
    return jwt.encode(
        {
            "jti": str(uuid.uuid4()),
            "iss": CLIENT_ID,
            "sub": CLIENT_ID,
            "aud": ISSUER,  # the issuer identifier, not the endpoint URL
            "iat": now,
            "exp": now + 120,
        },
        AUTH_KEY,
        algorithm="PS256",
        headers={"kid": KID},
    )
import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.RSASSASigner;
import com.nimbusds.jose.jwk.JWK;
import com.nimbusds.jwt.JWTClaimsSet;
import com.nimbusds.jwt.SignedJWT;
import java.time.Instant;
import java.util.Date;
import java.util.UUID;

static final String ISSUER = "https://<your-domain>";
static final String CLIENT_ID = "<your-client-id>";

// The key id shown next to the registered key in the Admin Console.
static final String KID = "<key-id-from-the-console>";

static String clientAssertion() throws Exception {
    // Your client-authentication private key
    var authKey = JWK.parseFromPEMEncodedObjects(System.getenv("CLIENT_AUTH_PRIVATE_KEY")).toRSAKey();
    var claims = new JWTClaimsSet.Builder()
        .jwtID(UUID.randomUUID().toString())
        .issuer(CLIENT_ID)
        .subject(CLIENT_ID)
        .audience(ISSUER) // the issuer identifier, not the endpoint URL
        .issueTime(new Date())
        .expirationTime(Date.from(Instant.now().plusSeconds(120)))
        .build();
    var jwt = new SignedJWT(
        new JWSHeader.Builder(JWSAlgorithm.PS256).keyID(KID).type(JOSEObjectType.JWT).build(),
        claims);
    jwt.sign(new RSASSASigner(authKey));
    return jwt.serialize();
}
using System.Security.Cryptography;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;

const string Issuer = "https://<your-domain>";
const string ClientId = "<your-client-id>";

// Your client-authentication private key, plus the key id shown next to the
// registered key in the Admin Console.
var authRsa = RSA.Create();
authRsa.ImportFromPem(Environment.GetEnvironmentVariable("CLIENT_AUTH_PRIVATE_KEY"));
var authKey = new RsaSecurityKey(authRsa) { KeyId = "<key-id-from-the-console>" };

string ClientAssertion() => new JsonWebTokenHandler().CreateToken(new SecurityTokenDescriptor
{
    Issuer = ClientId,
    Audience = Issuer, // the issuer identifier, not the endpoint URL
    Claims = new Dictionary<string, object> { ["sub"] = ClientId, ["jti"] = Guid.NewGuid().ToString() },
    Expires = DateTime.UtcNow.AddMinutes(2),
    SigningCredentials = new SigningCredentials(authKey, SecurityAlgorithms.RsaSsaPssSha256), // PS256
});
import (
	"os"
	"time"

	"github.com/google/uuid"
	"github.com/lestrrat-go/jwx/v2/jwa"
	"github.com/lestrrat-go/jwx/v2/jwk"
	"github.com/lestrrat-go/jwx/v2/jwt"
)

const issuer = "https://<your-domain>"
const clientID = "<your-client-id>"

// Your client-authentication private key, plus the key id shown next to the
// registered key in the Admin Console.
var authKey, _ = jwk.ParseKey([]byte(os.Getenv("CLIENT_AUTH_PRIVATE_KEY")), jwk.WithPEM(true))

const kid = "<key-id-from-the-console>"

func clientAssertion() []byte {
	authKey.Set(jwk.KeyIDKey, kid)
	token, _ := jwt.NewBuilder().
		JwtID(uuid.NewString()).
		Issuer(clientID).
		Subject(clientID).
		Audience([]string{issuer}). // the issuer identifier, not the endpoint URL
		IssuedAt(time.Now()).
		Expiration(time.Now().Add(2*time.Minute)).
		Build()
	signed, _ := jwt.Sign(token, jwt.WithKey(jwa.PS256, authKey))
	return signed
}
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\KeyManagement\JWKFactory;
use Jose\Component\Signature\Algorithm\PS256;
use Jose\Component\Signature\JWSBuilder;
use Jose\Component\Signature\Serializer\CompactSerializer;

const ISSUER = 'https://<your-domain>';
const CLIENT_ID = '<your-client-id>';
const KID = '<key-id-from-the-console>';

// Your client-authentication private key, plus the key id shown next to the
// registered key in the Admin Console.
$authKey = JWKFactory::createFromKey(getenv('CLIENT_AUTH_PRIVATE_KEY'));

function clientAssertion($authKey): string {
    $jws = (new JWSBuilder(new AlgorithmManager([new PS256()])))
        ->create()
        ->withPayload(json_encode([
            'jti' => bin2hex(random_bytes(16)),
            'iss' => CLIENT_ID,
            'sub' => CLIENT_ID,
            'aud' => ISSUER, // the issuer identifier, not the endpoint URL
            'iat' => time(),
            'exp' => time() + 120,
        ]))
        ->addSignature($authKey, ['alg' => 'PS256', 'kid' => KID, 'typ' => 'JWT'])
        ->build();
    return (new CompactSerializer())->serialize($jws);
}
use std::env;
use std::time::{Duration, SystemTime};

use josekit::jws::{JwsHeader, PS256};
use josekit::jwt::{self, JwtPayload};
use uuid::Uuid;

const ISSUER: &str = "https://<your-domain>";
const CLIENT_ID: &str = "<your-client-id>";

// The key id shown next to the registered key in the Admin Console.
const KID: &str = "<key-id-from-the-console>";

fn client_assertion() -> String {
    let mut header = JwsHeader::new();
    header.set_key_id(KID);
    header.set_token_type("JWT");

    let mut payload = JwtPayload::new();
    payload.set_jwt_id(Uuid::new_v4().to_string());
    payload.set_issuer(CLIENT_ID);
    payload.set_subject(CLIENT_ID);
    payload.set_audience(vec![ISSUER]); // the issuer identifier, not the endpoint URL
    payload.set_issued_at(&SystemTime::now());
    payload.set_expires_at(&(SystemTime::now() + Duration::from_secs(120)));

    // Your client-authentication private key
    let signer = PS256.signer_from_pem(env::var("CLIENT_AUTH_PRIVATE_KEY").unwrap()).unwrap();
    jwt::encode_with_signer(&payload, &header, &signer).unwrap()
}

Deux détails décident si cela est accepté :

  • aud doit être l'identifiant de l'issuer. Sans profil, l'URL de l'endpoint est également acceptée ; sous FAPI 2.0, elle ne l'est pas.
  • alg doit être PS256. Le profil fixe l'algorithme de signature des assertions de l'application.

Envoyez-la à chaque requête de token et à chaque pushed authorization request, sous forme de deux champs de formulaire :

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<the JWT>

2. Transmettre la requête d'autorisation

Au lieu de placer les paramètres dans l'URL du navigateur, envoyez-les en POST à l'endpoint de pushed authorization. La réponse est une référence à usage unique.

curl -X POST https://<your-domain>/oauth/par \
  -d client_id=<your-client-id> \
  -d response_type=code \
  -d redirect_uri=https://app.example.com/callback \
  -d scope='openid profile' \
  -d code_challenge=<CODE_CHALLENGE> \
  -d code_challenge_method=S256 \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=<the JWT>

Un appel réussi répond 201 avec :

{
  "request_uri": "urn:ietf:params:oauth:request_uri:...",
  "expires_in": 60
}
  • redirect_uri doit toujours être envoyée, même lorsque l'application n'en a exactement qu'une d'enregistrée. Le profil supprime le raccourci consistant à l'omettre.
  • PKCE est obligatoire ici, avec code_challenge_method=S256. Une requête transmise sans challenge est refusée.
  • La request_uri est à usage unique et expire en moins d'une minute. Transmettez la requête au moment où l'utilisateur est sur le point d'être redirigé, pas à l'avance.

3. Envoyer l'utilisateur vers l'endpoint d'autorisation

L'URL du navigateur ne porte plus que le client id et la référence :

https://<your-domain>/authorize
  ?client_id=<your-client-id>
  &request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3A...

La plateforme renvoie l'utilisateur vers votre redirect URI avec code, state et un paramètre iss nommant l'issuer. Contrôlez iss autant que state avant de continuer ; cela protège contre le rejeu d'une réponse provenant d'un autre issuer.

4. Créer une preuve DPoP

Une preuve DPoP est un JWT signé avec votre clé privée DPoP, qui porte la clé publique dans son en-tête. Elle est liée à une seule requête : la méthode et l'URL y figurent.

const dpopKey = await jose.importPKCS8(process.env.DPOP_PRIVATE_KEY, 'ES256');
const dpopPublicJwk = await jose.exportJWK(await jose.importSPKI(process.env.DPOP_PUBLIC_KEY, 'ES256'));

function dpopProof(method, url, nonce) {
  return new jose.SignJWT({ jti: crypto.randomUUID(), htm: method, htu: url, ...(nonce ? { nonce } : {}) })
    .setProtectedHeader({ alg: 'ES256', typ: 'dpop+jwt', jwk: dpopPublicJwk })
    .setIssuedAt()
    .sign(dpopKey);
}
from cryptography.hazmat.primitives.serialization import load_pem_private_key
from jwt.algorithms import ECAlgorithm

dpop_key = load_pem_private_key(os.environ["DPOP_PRIVATE_KEY"].encode(), password=None)
dpop_public_jwk = ECAlgorithm.to_jwk(dpop_key.public_key(), as_dict=True)

def dpop_proof(method, url, nonce=None):
    claims = {"jti": str(uuid.uuid4()), "htm": method, "htu": url, "iat": int(time.time())}
    if nonce:
        claims["nonce"] = nonce
    return jwt.encode(
        claims, dpop_key,
        algorithm="ES256",
        headers={"typ": "dpop+jwt", "jwk": dpop_public_jwk},
    )
import com.nimbusds.jose.crypto.ECDSASigner;

static String dpopProof(String method, String url, String nonce) throws Exception {
    var dpopKey = JWK.parseFromPEMEncodedObjects(System.getenv("DPOP_PRIVATE_KEY")).toECKey();

    var claims = new JWTClaimsSet.Builder()
        .jwtID(UUID.randomUUID().toString())
        .claim("htm", method)
        .claim("htu", url)
        .issueTime(new Date());
    if (nonce != null) claims.claim("nonce", nonce);

    var jwt = new SignedJWT(
        new JWSHeader.Builder(JWSAlgorithm.ES256)
            .type(new JOSEObjectType("dpop+jwt"))
            .jwk(dpopKey.toPublicJWK())
            .build(),
        claims.build());
    jwt.sign(new ECDSASigner(dpopKey));
    return jwt.serialize();
}
var dpopEc = ECDsa.Create();
dpopEc.ImportFromPem(Environment.GetEnvironmentVariable("DPOP_PRIVATE_KEY"));
var dpopKey = new ECDsaSecurityKey(dpopEc);
var publicJwk = JsonWebKeyConverter.ConvertFromECDsaSecurityKey(
    new ECDsaSecurityKey(ECDsa.Create(dpopEc.ExportParameters(includePrivateParameters: false))));

string DpopProof(string method, string url, string? nonce = null)
{
    var claims = new Dictionary<string, object> { ["jti"] = Guid.NewGuid().ToString(), ["htm"] = method, ["htu"] = url };
    if (nonce is not null) claims["nonce"] = nonce;

    return new JsonWebTokenHandler().CreateToken(new SecurityTokenDescriptor
    {
        TokenType = "dpop+jwt",
        Claims = claims,
        SigningCredentials = new SigningCredentials(dpopKey, SecurityAlgorithms.EcdsaSha256), // ES256
        AdditionalHeaderClaims = new Dictionary<string, object>
        {
            ["jwk"] = new Dictionary<string, string>
            {
                ["kty"] = publicJwk.Kty, ["crv"] = publicJwk.Crv, ["x"] = publicJwk.X, ["y"] = publicJwk.Y,
            },
        },
    });
}
import "github.com/lestrrat-go/jwx/v2/jws"

var dpopKey, _ = jwk.ParseKey([]byte(os.Getenv("DPOP_PRIVATE_KEY")), jwk.WithPEM(true))

func dpopProof(method, url, nonce string) []byte {
	dpopPublicJwk, _ := dpopKey.PublicKey()

	builder := jwt.NewBuilder().
		JwtID(uuid.NewString()).
		Claim("htm", method).
		Claim("htu", url).
		IssuedAt(time.Now())
	if nonce != "" {
		builder = builder.Claim("nonce", nonce)
	}
	token, _ := builder.Build()

	headers := jws.NewHeaders()
	headers.Set("typ", "dpop+jwt")
	headers.Set("jwk", dpopPublicJwk)
	signed, _ := jwt.Sign(token, jwt.WithKey(jwa.ES256, dpopKey, jws.WithProtectedHeaders(headers)))
	return signed
}
use Jose\Component\Signature\Algorithm\ES256;

$dpopKey = JWKFactory::createFromKey(getenv('DPOP_PRIVATE_KEY'));

function dpopProof($dpopKey, string $method, string $url, ?string $nonce = null): string {
    $claims = ['jti' => bin2hex(random_bytes(16)), 'htm' => $method, 'htu' => $url, 'iat' => time()];
    if ($nonce !== null) {
        $claims['nonce'] = $nonce;
    }
    $jws = (new JWSBuilder(new AlgorithmManager([new ES256()])))
        ->create()
        ->withPayload(json_encode($claims))
        ->addSignature($dpopKey, ['alg' => 'ES256', 'typ' => 'dpop+jwt', 'jwk' => $dpopKey->toPublic()])
        ->build();
    return (new CompactSerializer())->serialize($jws);
}
use josekit::jws::ES256;

fn dpop_proof(method: &str, url: &str, nonce: Option<&str>) -> String {
    let pem = env::var("DPOP_PRIVATE_KEY").unwrap();
    let key_pair = ES256.key_pair_from_pem(&pem).unwrap();

    let mut header = JwsHeader::new();
    header.set_token_type("dpop+jwt");
    header.set_jwk(key_pair.to_jwk_public_key());

    let mut payload = JwtPayload::new();
    payload.set_jwt_id(Uuid::new_v4().to_string());
    payload.set_claim("htm", Some(method.into())).unwrap();
    payload.set_claim("htu", Some(url.into())).unwrap();
    payload.set_issued_at(&SystemTime::now());
    if let Some(nonce) = nonce {
        payload.set_claim("nonce", Some(nonce.into())).unwrap();
    }

    let signer = ES256.signer_from_pem(&pem).unwrap();
    jwt::encode_with_signer(&payload, &header, &signer).unwrap()
}

htu est l'URL de l'endpoint sans query ni fragment, et elle doit correspondre à l'URL que vous appelez réellement, schéma et hôte compris.

5. Échanger le code, deux fois

Un nonce serveur est exigé : la première requête de token échoue donc toujours. C'est attendu, ce n'est pas une erreur de configuration de votre côté : la réponse vous remet un nonce à placer dans la preuve suivante.

# First attempt: no nonce yet
curl -i -X POST https://<your-domain>/oauth/token \
  -H 'DPoP: <proof without nonce>' \
  -d grant_type=authorization_code \
  -d code=<one-time-code> \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=<CODE_VERIFIER> \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=<the JWT>

La réponse est un 400 avec {"error":"use_dpop_nonce"} et un en-tête de réponse DPoP-Nonce. Lisez cet en-tête, construisez une nouvelle preuve qui le contient dans le claim nonce, et répétez la requête à l'identique :

let res = await tokenRequest(dpopProof('POST', tokenUrl));
if (!res.ok) {
  const nonce = res.headers.get('dpop-nonce');
  res = await tokenRequest(dpopProof('POST', tokenUrl, nonce));
}
res = token_request(dpop_proof("POST", token_url))
if not res.ok:
    nonce = res.headers.get("dpop-nonce")
    res = token_request(dpop_proof("POST", token_url, nonce))
var res = tokenRequest(dpopProof("POST", tokenUrl, null));
if (res.statusCode() != 200) {
    var nonce = res.headers().firstValue("DPoP-Nonce").orElseThrow();
    res = tokenRequest(dpopProof("POST", tokenUrl, nonce));
}
var res = await TokenRequest(DpopProof("POST", tokenUrl));
if (!res.IsSuccessStatusCode && res.Headers.TryGetValues("DPoP-Nonce", out var nonces))
{
    res = await TokenRequest(DpopProof("POST", tokenUrl, nonces.First()));
}
res, _ := tokenRequest(dpopProof("POST", tokenURL, ""))
if res.StatusCode != http.StatusOK {
	nonce := res.Header.Get("DPoP-Nonce")
	res, _ = tokenRequest(dpopProof("POST", tokenURL, nonce))
}
$res = tokenRequest(dpopProof($dpopKey, 'POST', $tokenUrl));
if ($res->getStatusCode() !== 200) {
    $nonce = $res->getHeaderLine('DPoP-Nonce');
    $res = tokenRequest(dpopProof($dpopKey, 'POST', $tokenUrl, $nonce));
}
let mut res = token_request(dpop_proof("POST", token_url, None)).await?;
if !res.status().is_success() {
    let nonce = res.headers().get("dpop-nonce").and_then(|v| v.to_str().ok()).map(String::from);
    res = token_request(dpop_proof("POST", token_url, nonce.as_deref())).await?;
}

Les nonces sont réutilisés pendant un certain temps : mettez donc en cache le dernier reçu et commencez avec lui à la requête suivante. Traitez use_dpop_nonce à tout moment : lorsqu'un nonce expire, le même échange se reproduit.

Une réponse réussie diffère d'une réponse standard sur un seul point, important :

{
  "token_type": "DPoP",
  "access_token": "...",
  "id_token": "...",
  "expires_in": 3600
}

6. Appeler les API avec le token

token_type vaut DPoP et non Bearer, et le token est lié à votre clé DPoP. Chaque appel à une ressource nécessite à la fois le token et une preuve fraîche pour cette requête :

curl https://api.example.com/orders \
  -H 'Authorization: DPoP <access_token>' \
  -H 'DPoP: <proof for GET https://api.example.com/orders>'

Envoyer le token en Authorization: Bearer échoue. Une ressource qui contrôle la liaison compare la clé de la preuve au claim de confirmation contenu dans le token : un token dérobé est donc inutilisable sans la clé privée.

Dépannage

  • use_dpop_nonce à chaque requête. Le claim nonce manque dans la preuve, ou vous avez réutilisé la preuve précédente au lieu d'en signer une nouvelle. Chaque preuve est à usage unique.
  • invalid_client alors que la même configuration fonctionnait avant le profil. Soit l'aud de l'assertion est l'URL de l'endpoint et non l'identifiant de l'issuer, soit elle est signée avec autre chose que PS256, soit le kid ne correspond à aucune clé enregistrée.
  • invalid_dpop_proof. Le htu ne correspond pas à l'URL appelée (un proxy qui réécrit l'hôte en est une cause fréquente), ou htm ne correspond pas à la méthode, ou l'horloge dérive au-delà d'une petite marge.
  • invalid_request sur l'endpoint d'autorisation. L'application exige une requête transmise au back-channel : les paramètres ne peuvent plus être envoyés dans l'URL du navigateur. Transmettez-les d'abord et passez la request_uri.
  • La request_uri est rejetée comme inconnue. Elle a déjà été utilisée, ou elle a expiré. Transmettez une nouvelle requête.
  • La ressource rejette le token. Vérifiez qu'il est envoyé avec le schéma DPoP et que la ressource valide bien la liaison au lieu d'attendre un bearer token.

Voir aussi

Sur cette page