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.
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 standard | Client FAPI 2.0 | |
|---|---|---|
| Authentification du client | Client secret | Private key JWT, signé en PS256 |
| Requête d'autorisation | Paramètres dans l'URL du navigateur | Transmise d'abord, le navigateur reçoit une request_uri |
| PKCE | Recommandé | Exigé, S256 |
| Access token | Bearer | DPoP, lié à votre clé |
| Requêtes de token | Un appel | Deux au premier contact, pour le nonce DPoP |
Avant de commencer
-
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.
-
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.
-
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.
-
Lisez le document de discovery. Il liste désormais également
pushed_authorization_request_endpoint, etdpop_signing_alg_values_supportedindique 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é :
auddoit ê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.algdoit ê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_uridoit 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_uriest à 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 claimnoncemanque 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_clientalors que la même configuration fonctionnait avant le profil. Soit l'audde 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 lekidne correspond à aucune clé enregistrée.invalid_dpop_proof. Lehtune correspond pas à l'URL appelée (un proxy qui réécrit l'hôte en est une cause fréquente), ouhtmne correspond pas à la méthode, ou l'horloge dérive au-delà d'une petite marge.invalid_requestsur 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 larequest_uri.- La
request_uriest 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
DPoPet que la ressource valide bien la liaison au lieu d'attendre un bearer token.
Voir aussi
- Financial-grade API security pour les paramètres de l'application et ce que le profil impose.
- API pour l'algorithme de signature des access tokens.
- OpenID Connect (Authorization Code + PKCE) pour le flux de base.
Application monopage React
Ajoutez la connexion à une application React de navigateur en tant que client public, avec react-oidc-context et le flux Authorization Code avec PKCE.
Protéger une API
Validez les access tokens de la plateforme dans votre propre API, avec des exemples pour Node.js, Python, Java, C#, Go, PHP et Rust.