Cliente Financial-grade API (FAPI 2.0)
Adapte um cliente ao FAPI 2.0 Security Profile: private key JWT, pushed authorization requests e tokens sender-constrained com DPoP.
Nota: Disponível com as subscrições Advanced e Pro.
Mudar uma aplicação para o FAPI 2.0 Security Profile altera aquilo que o respetivo cliente tem de enviar. Um cliente que antes funcionava deixa de funcionar: o perfil substitui o client secret por uma assertion assinada, exige que o pedido de autorização seja primeiro enviado por um back channel e emite access tokens ligados a uma chave detida pelo cliente.
Este guia trata apenas das diferenças em relação ao fluxo Authorization Code com PKCE. Leia esse guia primeiro.
O que muda
| Cliente padrão | Cliente FAPI 2.0 | |
|---|---|---|
| Autenticação do cliente | Client secret | Private key JWT, assinado com PS256 |
| Pedido de autorização | Parâmetros no URL do browser | Enviado previamente, o browser recebe um request_uri |
| PKCE | Recomendado | Obrigatório, S256 |
| Access token | Bearer | DPoP, ligado à sua chave |
| Pedidos de token | Uma chamada | Duas no primeiro contacto, por causa do nonce DPoP |
Antes de começar
-
Gere um par de chaves para a autenticação do cliente. RSA (2048 bits ou mais) ou EC na curva P-256.
-
Registe a chave pública na aplicação e mude-a depois para o perfil FAPI 2.0. A ordem a seguir consta de Financial-grade API security.
-
Gere um segundo par de chaves para os proofs DPoP. Mantenha-o separado da chave de autenticação do cliente, para que cada uma tenha uma única função.
-
Leia o documento de discovery. Passa a incluir também
pushed_authorization_request_endpoint, edpop_signing_alg_values_supportedindica que algoritmos os proofs podem usar.https://<your-domain>/.well-known/openid-configuration
Se a API invocada pela sua aplicação emitir access tokens JWT, defina também o algoritmo de assinatura dessa API como PS256. Consulte APIs.
1. Construir uma client assertion
Todas as chamadas que antes transportavam o client secret transportam agora um JWT de curta duração, assinado com a chave privada de autenticação do cliente. Os exemplos usam a biblioteca JOSE de cada stack: jose para Node.js, PyJWT (com o extra crypto) para Python, Nimbus JOSE + JWT para Java, Microsoft.IdentityModel.JsonWebTokens para C#, lestrrat-go/jwx para Go, web-token/jwt-framework para PHP e josekit para 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()
}Dois detalhes decidem se isto é aceite:
audtem de ser o identificador do issuer. Sem perfil, o URL do endpoint também é aceite; sob FAPI 2.0, não é.algtem de ser PS256. O perfil fixa o algoritmo de assinatura das assertions da aplicação.
Envie-a em cada pedido de token e em cada pushed authorization request, como dois campos de formulário:
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<the JWT>2. Enviar previamente o pedido de autorização
Em vez de colocar os parâmetros no URL do browser, envie-os por POST para o endpoint de pushed authorization. A resposta é uma referência de utilização única.
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>Uma chamada bem-sucedida responde 201 com:
{
"request_uri": "urn:ietf:params:oauth:request_uri:...",
"expires_in": 60
}- O
redirect_uritem de ser sempre enviado, mesmo quando a aplicação tem exatamente um registado. O perfil elimina o atalho de o omitir. - O PKCE é obrigatório aqui, com
code_challenge_method=S256. Um pedido enviado sem challenge é recusado. - O
request_urié de utilização única e expira ao fim de um minuto. Envie o pedido no momento em que o utilizador está prestes a ser redirecionado, não com antecedência.
3. Enviar o utilizador para o authorization endpoint
O URL do browser transporta agora apenas o client id e a referência:
https://<your-domain>/authorize
?client_id=<your-client-id>
&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3A...A plataforma devolve o utilizador ao seu redirect URI com code, state e um parâmetro iss que identifica o issuer. Verifique o iss além do state antes de prosseguir; isso protege contra a repetição de uma resposta proveniente de outro issuer.
4. Criar um proof DPoP
Um proof DPoP é um JWT assinado com a sua chave privada DPoP, que transporta a chave pública no cabeçalho. Está ligado a um único pedido: o método e o URL fazem parte dele.
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()
}O htu é o URL do endpoint sem query nem fragmento, e tem de corresponder ao URL efetivamente invocado, incluindo o esquema e o host.
5. Trocar o código, duas vezes
É exigido um nonce do servidor, pelo que o primeiro pedido de token falha sempre. Isto é esperado, não um erro na sua configuração: a resposta entrega-lhe um nonce para incluir no proof seguinte.
# 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>A resposta é 400 com {"error":"use_dpop_nonce"} e um cabeçalho de resposta DPoP-Nonce. Leia esse cabeçalho, construa um novo proof que o contenha no claim nonce e repita o pedido idêntico:
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?;
}Os nonces são reutilizados durante algum tempo, por isso guarde o último que recebeu e comece com ele no pedido seguinte. Trate use_dpop_nonce a qualquer momento: quando um nonce expira, repete-se a mesma troca.
Uma resposta bem-sucedida difere de uma resposta normal num único aspeto, importante:
{
"token_type": "DPoP",
"access_token": "...",
"id_token": "...",
"expires_in": 3600
}6. Invocar APIs com o token
O token_type é DPoP, não Bearer, e o token está ligado à sua chave DPoP. Cada chamada a um recurso precisa do token e de um proof novo para esse pedido:
curl https://api.example.com/orders \
-H 'Authorization: DPoP <access_token>' \
-H 'DPoP: <proof for GET https://api.example.com/orders>'Enviar o token como Authorization: Bearer falha. Um recurso que verifica a ligação compara a chave do proof com o claim de confirmação existente no token, pelo que um token roubado é inútil sem a chave privada.
Resolução de problemas
use_dpop_nonceem todos os pedidos. Falta o claimnonceno proof, ou reutilizou o proof anterior em vez de assinar um novo. Cada proof é de utilização única.invalid_clientquando a mesma configuração funcionava antes do perfil. Ou oaudda assertion é o URL do endpoint em vez do identificador do issuer, ou está assinada com algo que não PS256, ou okidnão corresponde a nenhuma chave registada.invalid_dpop_proof. Ohtunão corresponde ao URL invocado (uma causa frequente é um proxy que reescreve o host), ou ohtmnão corresponde ao método, ou o relógio está desviado mais do que uma pequena margem.invalid_requestno authorization endpoint. A aplicação exige um pedido enviado previamente, pelo que os parâmetros já não podem ser enviados no URL do browser. Envie-os primeiro e passe orequest_uri.request_urirejeitado como desconhecido. Já foi utilizado, ou expirou. Envie um pedido novo.- O recurso rejeita o token. Verifique se é enviado com o esquema
DPoPe se o recurso está a validar a ligação em vez de esperar um bearer token.
Consulte também
- Financial-grade API security para as definições da aplicação e para o que o perfil impõe.
- APIs para o algoritmo de assinatura dos access tokens.
- OpenID Connect (Authorization Code + PKCE) para o fluxo de base.
Aplicação de página única em React
Acrescente o início de sessão a uma aplicação React de browser como cliente public, com react-oidc-context e o fluxo Authorization Code com PKCE.
Proteger uma API
Valide os access tokens da plataforma na sua própria API, com exemplos para Node.js, Python, Java, C#, Go, PHP e Rust.