NOTA: Esse artigo foi traduzido do artigo original escrito por Takahiko Kawasaki, em 24 de abril de 2019 e atualizado em Março de 2021 após a publicação da versão FAPI 1.0 Final Version. Clique aqui para ler o artigo original

NOTA: A OpenID Foundation gostaria de agradecer ao membro e autor original, Taka Kawasaki, co-fundador da Authlete, por apoiar a tradução de seu blog para o Português a fim de apoiar o lançamento do Open Banking Brasil. A Fundação também gostaria de agradecer ao novo membro, Danillo Branco co-fundador da Finansystech, por concluir a tradução e seu apoio e contribuições para a Fundação OpenID Foundation.

Introdução

Financial-grade API (FAPI) é uma especificação técnica, também considerado como um padrão técnico (e.g. ISO) de implementação de software, desenvolvido pelo grupo de trabalho (WG) de FAPI da OpenID Foundation (Fundação sem fins lucrativos). O padrão utiliza outros dois padrões conhecidos, são eles: OAuth 2.0 e OpenID Connect (OIDC). Estes padrões são a base da especificação FAPI, que combinou essas técnicas e somou com outros artefatos de segurança, isto para que fosse possível atender os altos padrões de segurança exigidos pela indústria financeira, porém também podendo esse ser estendido para outras indústrias com padrões de segurança similares.) A OIDF já iniciou os trabalhos para a nova versão da especificação FAPI, nomeada como “FAPI 2.0”. A nova versão conta com novos componentes técnicos tais como, PAR (OAuth 2.0 Pushed Authorization Requests), RAR (OAuth 2.0 Rich Authorization Requests) e DPoP (OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer).

OpenID Foundation Working Groups and Financial-grade API Stack

Histórico

Versão inicial 1 — A primeira versão da especificação FAPI foi publicada em 2017. Essa versão foi nomeada como Implementer’s Draft 1, conhecida pelo acrônimo ID1.

Versão inicial 2 — A segunda versão foi publicada em Outubro de 2018. Essa versão foi nomeada como Implementer’s Draft 2, conhecida pelo acrônimo ID2. Nessa versão o FAPI foi renomeado de “Financial API” para o conhecido “Financial-grade API”. A alteração do nome ocorreu para que houvesse a adoção do padrão por outras indústrias além da financeira.

Versão Final — A versão final do FAPI foi publicada em Março de 2021. Nessa versão é possível observar que as duas partes principais do FAPI foram renomeadas conforme abaixo:

  • “Part 1: Read-Only Security Profile” para “Part 1: Baseline Security Profile”
  • “Part 2: Read and Write API Security Profile” para “Part 2: Advanced Security Profile”

FAPI 2.0 — O GT do FAPI (OIDF
History of Financial-grade API

Especificações FAPI

Os componentes principais da especificação FAPI são a Part 1 e Part 2. As versões disponíveis estão a seguir:

Versão inicial 1 (ID1) – (Part 1: 2 de fevereiro de 2017 / Part 2: 17 de julho de 2017)

Versão inicial 2 (ID2) (Outubro de 2018)

Versão Final (12 de março de 2021)

Adicionalmente, em Agosto de 2019 foi lançada uma lista adicional de requisitos que são aplicados quando o FAPI é utilizado junto com o CIBA (Client Initiated Backchannel Authentication, Autenticação de Cliente por Canais Internos). Para tanto foi criada a especificação FAPI-CIBA Profile.

Para maiores detalhes sobre o CIBA acesse o link abaixo (Em breve traduzido em Português)

Concept of CIBA

Programa de Certificação

Certificação de Provedores FAPI (FAPI OpenID Providers)

O programa de certificação para provedores FAPI da OpenID (FAPI OpenID Providers) foi iniciada oficialmente em 1° de abril de 2019 (anúncio). Dois provedores realizaram a certificação no primeiro dia, dentre eles a Authlet, Inc., empresa do autor original do artigo (Takahiko Kawasaki).

Certified Financial-grade API OpenID Providers on April 1, 2019

Passados dois anos do lançamento, a certificação de provedores FAPI já conta com mais de 30 provedores habilitados.

O programa de certificação para o FAPI Final ainda não foi iniciada, ao menos na data de produção desse artigo (Abril, 2021), mas a solução Authlet 2.2 já concede suporte para a versão FAPI Final.

Certificação para Provedores FAPI-CIBA

O programa de certificação para provedores FAPI-CIBA foi iniciado em 16 de Setembro de 2019 (anúncio). A Authlete foi a única solução certificada no dia de lançamento.

Certified FAPI-CIBA Profile OpenID Providers on September 16, 2019

Até abril de 2021, data de escrita desse artigo, além da Authlete, somente outras duas soluções se certificaram para provedores FAPI-CIBA.

Base de Conhecimento Prévio

Especificações Base

A especificação FAPI é formada por uma lista enxuta de requisitos técnicos, todavia, é preciso ter conhecimento de outras especificações já existentes para a compreensão completa do modelo. Dentre todos, destacam-se para o aprendizado a RFC 6749 e RFC 6750 (coração do OAuth 2.0) e a OpenID Connect Core 1.0 (coração da OpenID Connect), a compreensão desses é imprescindível para entender o modelo FAPI.

Visto que as especificações que compõem o modelo JWT (JSON Web Token, JWS, JWE, JWK, JWA e JWT) são conhecimentos básicos da estrutura OIDC (OpenID Connect), então também é considerado como conhecimento prévio necessário e recomendado que se tenha total domínio para melhor compreensão do FAPI.

JWS Compact Serialization (RFC 7515 Section 7.1)

Por fim, a especificação PKCE (RFC 7636), publicada em Setembro de 2015, agora faz parte da composição básica do OAuth 2.0, assim como a RFC 6749 e RF 6750.

A seguir você encontra uma lista das especificações que devem ser lidas ao menos uma vez antes da especificação FAPI em si.

Os artigos a seguir (não traduzidos para Português) podem ajudar a compreender os padrões e iniciar a leitura do FAPI:

TLS Mútuo (MTLS)

O TLS Mútuo, ou em inglês Mutual TLS, é a representação de que o cliente da conexão também precisa apresentar um certificado do tipo X.509 no momento de realizar a conexão TLS. Todavia, no contexto do FAPI, a conexão TLS mútua significa a execução do MTLS conforme descrito na RFC 8705, e nos passos resumidos a seguir, mais detalhes em: “RFC 8705 OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens” (MTLS).

  1. Autenticação OAuth do cliente usando o certificado Cliente
  2. Troca de tokens vinculados ao certificado do cliente

Autenticação OAuth do Cliente Usando o Certificado Cliente

Quando um cliente determinado, ou confidential client conforme determinado nos tipos de clientes da RFC 6749 (RFC 6749, 2. Client Types), acessa um caminho para token, ou token endpoint conforme item 3.2 da mesma RFC (RFC 6749, 3.2. Token Endpoint), a autenticação do cliente é requerida (RFC 6749, 2.3. Client Authentication). A autenticação do cliente é um processo onde a aplicação cliente prova que ela é detentora das informações declaradas como confidential client.

Client Authentication at Token Endpoint

Existem várias formas de realizar a autenticação do cliente. As opções abaixo são os métodos que você pode encontrar no modelo OIDC Core, 9. Client Authentication(exceto o tipo none).

  • client_secret_basic — Autenticação básica usando o par client ID e client secret;
  • client_secret_post — Encapsulamento do par client ID e client secret dentro do body da requisição;
  • client_secret_jwt — Enviar um objeto JWT assinado por uma chave que está baseado no client secret com um algoritmo criptográfico do tipo simétrico
  • private_key_jwt — Enviar um objeto JWT assinado com uma chave privada com um algoritmo criptográfico do tipo assimétrico

Nos métodos client_secret_basic e client_secret_post, a aplicação cliente se apresenta explicitamente para o servidor, mostrando o seu client secret a fim de provar que ele contém a informação necessária.

Client Authentication using Basic Authentication

No método client_secret_jwt, a aplicação cliente apresenta implícitamente para o servidor, provando que ele possui o client secret através da assinatura do objeto JWT e passando o objeto JWT para o

servidor que possui a chave privada utilizada para assinatura. Por outro lado, o método private_key_jwt, o objeto JWT é assinado com uma chave privada assimétrica, e o servidor verifica esse objeto JWT utilizando a chave pública dessa chave privada.

Client Authentication using JWT

Além dos métodos apresentados anteriormente, a RFC 8705 introduz novas formas de realizar a autenticação de clientes (“2. Mutual TLS for OAuth Client Authentication”, RFC 8705)

  • tls_client_auth — Utilização do certificado cliente PKI na conexão TLS
  • self_signed_tls_client_auth — Utilização do certificado cliente auto-assinado na conexão TLS

Esses dois modelos certificados são utilizados na conexão TLS entre cliente e o endpoint do token para a autenticação do cliente.

Client Certificate for Client Authentication

No tls_client_auth, o certificado de cliente PKI é usado na conexão TLS entre um cliente e um servidor, isso para realizar a autenticação do cliente. O servidor verifica o certificado do cliente (isso deve ser feito independentemente do contexto OAuth) e, em seguida, verifica se o Subject Distinguished Name ou Subject Alternative Name corresponde ao registrado no servidor. Para este processo, os aplicativos clientes que desejam usar o

tls_client_auth para autenticação do cliente devem ser registrados o Subject Distinguished Name ou Subject Alternative Name no servidor antes da conexão TLS. Recentemente a RFC passou a conter as definiçoes dos metadados para essa conexão (RFC 8705, 2.1.2 Client Registration Metadata).

  • tls_client_auth_subject_dn
  • tls_client_auth_san_dns
  • tls_client_auth_san_uri
  • tls_client_auth_san_ip
  • tls_client_auth_san_email

No método self_signed_tls_client_auth, o certificado cliente auto-assinado é usado ao invés do certificado registrado PKI. Para usar esse método de autenticação, as aplicações clientes devem registrar o certificado auto-assinado cliente dentro do servidor antes de realizar a conexão.

A lista abaixo descreve os métodos de autenticação cliente estabelecidos na especificação FAPI.

Client Authentication Methods

Para uma explicação detalhada sobre a autenticação de cliente, verifique no artigo a seguir (em inglês) “OAuth 2.0 Client Authentication”. E caso necessite entender mais sobre o X.509, verifique em (em inglês) “Illustrated X.509 Certificate”.

X.509 Certificate Chain

X.509 Certificate in PEM Format

Tokens Gerados a partir do Certificado

Tradicionalmente, quando um access token é exposto (crime cibernético), o atacante passa a ter acesso às APIs com esse Access Token. O Access Token é como um bilhete de metrô, uma vez que alguém rouba o seu bilhete, essa pessoa passa a poder usar o metrô.

O conceito para mitigar essa vulnerabilidade é verificar o cliente das APIs no momento da chamada através da combinação do Access Token com as identificações do cliente, garantindo que ele é o legítimo dono do token apresentado. Esse é o procedimento realizado em Aeroportos, onde o passageiro precisa apresentar tanto o bilhete de viagem como o seu documento de identidade.

O conceito é chamado de “Prova de Posse” (PoP) e para o FAPI, o “Mutual TLS” é o único método que garante o PoP ( — conforme últimas versões (ID1 e ID2), “Token Binding” é mencionado como mecanismo de PoP mas foi retirado na versão final do FAPI). Portanto, “Mutual TLS” é a representação do que esta definido nos artigos a seguir (em inglês) “3. Mutual-TLS Client Certificate-Bound Access Tokens” da RFC 8705.

Por causa disso, Mutual TLS pode ter vários significados como explicado acima, e atualmente é visto problemas como o descrito abaixo:

Eu: A sua solução de API Management não suporta Mutual TLS (como mecanismo PoP).

The company: Incorreto. Nossa solução suporta Mutual TLS (porque pode ser configurado como mandatório apresentar o certificado cliente na comunicação TLS).

Eu pessoalmente decidi chamar o Mutual TLS como mecanismo PoP de “Certificate Binding” (tradução livre, vincular um certificado). Esse nome é adequado para fazer referência a simetria do Token Binding e porque atualmente as implementações eventualmente se tornaram vinculadas ao certificado (Certificate Binding) para acessar o Access Token e não mais levaram em conta se ele foi apresentado na conexão de TLS mútuo ou qualquer outra conexão similar.

A implementação do Certificate Binding, quando o endpoint do servidor de autorização gera o Access Token, é baseada no cálculo da hash do certificado do cliente que foi apresentado durante a conexão TLS, e este remete a vinculação do Access Token com o valor da hash (ou encapsula o valor da hash dentro do Access Token quando a implementação for JWT auto-contido). Quando a aplicação cliente acessa a API no servidor de recursos (Resource Server), ele deve utilizar o mesmo certificado cliente utilizado previamente na geração do Access Token. O API deverá extrair o Access Token e o certificado cliente da requisição, calculando a hash e verificando se a hash corresponde com o valor apresentado. Se a hash for a mesma, o API aceita a requisição, senão, rejeita a requisição.

Certificate Binding

Implementar o Certificate Binding é relativamente simples, porque ele pode ser feito somente se o certificado cliente for acessivel. Por outro lado, Token Binding é relativamente complexo, uma vez que é necessário alterar algumas camadas, tal como a camada do TLS e HTTP. Adicionalmente, o futuro do Token Binding é incerto, uma vez que o Chrome retirou a funcionalidade devido ao pedido do time de desenvolvimento, verifique com mais detalhe nos links a seguir: Chrome has removed the Token Binding feature e Intent to Remove: Token Binding”).

Todavia, foram realizadas algumas especificações nas RFCs no inicio de Outubro de 2018 referenciando o Token Binding.

  • RFC 8471 — Protocolo Token Binding Versão 1.0
  • RFC 8472 — Transport Layer Security (TLS) Extensão para a negociação do protocolo Token Binding
  • RFC 8473 — Token Binding no HTTP

“OAuth 2.0 Token Binding” (esta como “expirado”) essa é a especificação que define as regras a serem aplicadas no Token Binding para tokens OAuth 2.0 conforme a listagem acima.

NOTE: A versão final do FAPI retirou o método Token Binding devido a possibilidade de não haver compatibilidade futura.

JARM

O JARM é uma nova especificação que foi aprovada junto com a versão FAPI Implementer’s Draft 2. O JARM é referenciado no FAPI Parte 2.

Links sugeridos:

A especificação define novos valores para o parâmetro de requisição response_mode conforme apresentado abaixo.

  1. query.jwt
  2. fragment.jwt
  3. form_post.jwt
  4. jwt

Se um dos parâmetros acima for especificado, os parâmetros de resposta de autorização são encapsulados dentro do JWT e o JWT é retornado como valor dentro do parâmetro response.

Por exemplo, a resposta tradicional de autorização dentro do fluxo de códigos de autorização são como o descrito abaixo, sendo o parâmetro code e state incluídos de forma separada.

HTTP/1.1 302 Found
Location: https://client.com/callback?code={CODE}&state={STATE}

Por outro lado, se o response_mode=query.jwt for adicionado a requisição de autorização, a resposta de autorização será parecida conforme abaixo.

HTTP/1.1 302 Found
Location: https://client.com/callback?response={JWT}

JARM example

Devido o JWT ser assinado por uma chave do servidor, o cliente pode confirmar que a resposta não foi exposta através da verificação do JWT.

Client Metadata para JARM

Antes de usar o JARM, as aplicações clientes tinham que definir os valores de metadados antecipadamente no authorization_signed_response_alg. O metadado representa um algoritmo de assinatura de resposta para JWTs. Se o valor do parâmetro da requisição do response_mode é *.jwt e se os metadados não forem incluídos, a requisição de autorização falha porque a especificação requer que a resposta JWT seja sempre assinada.

Para encriptar o JWT de resposta, os algoritmos devem ser selecionados anteriormente através dos metadados no authorization_encrypted_response_alg e no authorization_encrypted_response_enc. O algoritmo utilizado deve ser assimétrico, e a configuração da chave pública do cliente também é necessária.

A imagem abaixo são opções do lado cliente para configuração do JARM na console web da Authlete.

Authorization Response Algorithms (in Developer Console provided by Authlete)

Servidor de metadados para JARM

Descobrir as informações de servidores de autorização que suportam JARM inclui um ou mais query.jwt, fragment.jwt, form_post.jwt e jwt dentro da lista de modos suportados (response_modes_supported).

Além disso, descobrir essas informações incluem também verificar os metadados relacionados aos algoritmos de resposta utilizados nos JWTs.

authorization_signing_alg_values_supported — algoritmos de assinatura suportados

authorization_encryption_alg_values_supported — chaves de algoritmos para encriptar suportados

authorization_encryption_enc_values_supported — algoritmos de encriptação de contexto (payload) suportados

As informações dos servidores de autorização que suportam JARM completamente devem ter uma resposta conforme abaixo

Server Metadata related to JARM

Part 1: Baseline de Segurança

Com o conhecimento prévio adquirido, vamos iniciar a parte principal do artigo. Para começar, “Part 1” é o que define os requisitos de base para o perfil de segurança, nomeado como Baseline (“Part 1” é um termo sem tradução, uma vez que ele faz referência direta a especificação FAPI, e que por isso será mantido em inglês)

Part 1: Requisitos para o Ervidor de Autorização

“5.2.2. Servidor de Autorização” em “Part 1” lista os requisitos para o servidor de autorização, do qual vamos verificar um a um.

Part 1: 5.2.2. Servidor de autorização, 1.

deve suportar clientes confidenciais;

Part 1: 5.2.2. Servidor de Autorização 2.

deve suportar clientes públicos;

A definição de “clientes confidenciais” e “clientes públicos” está descrito no item “2.1. Client Types” da RFC 6749. Aqui não é explicado a diferença entre eles, uma vez que é esperado que você saiba para entender o FAPI. Todavia, a relação entre os tipos de cliente e os fluxos de OAuth 2.0 são geralmente mal interpretados por aqueles conhecem esses fluxos. Isso é apenas a combinação entre o “cliente publico” e o “fluxo de credenciais do cliente”que a RFC 6749 explicitamente proíbe. Outras combinações são permitidas. Sem esse entendimento, você provavelmente interpretará mal o FAPI.

Combinations of Flow and Client Type (RFC 6749)

Nota: Esse é o cliente confidencial que somente é permitido para fazer a autenticação por canais internos, sendo essas requisições descritas no CIBA.

Combinations of Flow and Client Type (CIBA)

Part 1: 5.2.2. Servidor de autorização, 3.

deve prover ao cliente um segredo (client secret) que seja aderente aos requisitos descritos na seção 16.19 do OIDC utilizando uma chave simétrica;

OIDC Core afirma que um valor calculado com base em um segredo do cliente (client secret) deve ser usado como chave compartilhada quando um algoritmo simétrico é usado para assinatura e criptografia. Se a entropia do segredo do cliente for menor do que a exigida pelo algoritmo, a força do algoritmo é enfraquecida. Todavia, em “16.19. Symmetric Key Entropy” exige que os segredos do cliente tenham entropia forte o suficiente para os algoritmos usados. Por exemplo, quando HS256 (HMAC usando o modelo SHA-256) é usado para assinar o algoritmo ID tokens, o segredo (client secrets) deve conter no minimo uma entropia do tipo 256-bit.

Part 1: 5.2.2. Servidor de autorização, 4.

deve autenticar o cliente confidencial usando um dos seguintes métodos:

    1. O TLS Mutuo para autenticação do cliente OAuth (Client Authentication) esta especificado na seção 2 do MTLS;
    2. client_secret_jwt ou private_key_jwt conforme especificado na seção 9 do OIDC;

Note que client_secret_basic e client_secret_post são definidos na RFC 6749 não são permitidos para autenticação de clientes para geração do token.

Client Authentication Methods allowed in FAPI Part 1

Part 1: 5.2.2. Servidor de autorização, 5.

deve exigir e usar uma chave de 2048 bits ou maior para algoritmo RSA;

Part 1: 5.2.2. Servidor de autorização, 6.

deve obrigatoriamente exigir e usar uma chave de tamanho 160 bits ou maior para algoritmos de curva elíptica;

Por exemplo, quando o private_key_jwt é usado como método de autenticação de cliente e RSA é usado para assinar o JWT, o tamanho da chave deve ser 2048 ou maior. Da mesma forma, quando um algoritmo de curva elíptica é usado, o tamanho da chave deve ser 160 no mínimo.

Part 1: 5.2.2. Servidor de autorização, 7.

deve requerer a RFC7636 com S256 como o código de desafio;

É necessário implementar a RFC 7636 (PKCE), que é uma prevenção para “ataque de interceptação de código de autorização”

Authorization Code Interception Attack

A RFC 7636 adiciona o code_challenge e code_challenge_method como parâmetros da requisição para autorização e o parâmetro code_verifier para a requisição do token. Como o valor padrão do code_challenge_method é plain, requisições de autorização que estão em conformidade com o FAPI devem incluir o code_challenge_method=S256 explicitamente.

Veja “Proof Key for Code Exchange (RFC 7636)” para mais detalhes sobre o PKCE.

Part 1: 5.2.2. Servidor de autorização, 8.

exigirá que os URIs de redirecionamento sejam pré-registrados;

No RFC 6749, o registro de URIs de redirecionamento não é necessário em algumas condições. Para FAPI, o registro de URIs de redirecionamento é sempre necessário.

Part 1: 5.2.2. Servidor de autorização, 9.

deve requerer o parâmetro redirect_uri na requisição de redirecionamento;

Na RFC 6749, o parâmetro redirect_uri de uma requisição de autorização pode ser omitido em algumas condições. Para o FAPI, o parâmetro de solicitação deve ser sempre incluído. O OIDC tem o mesmo requisito.

Part 1: 5.2.2. Servidor de autorização, 10.

deve requerer que o valor do redirect_uri seja exatamente o mesmo que esta nas URIs de redirecionamento;

Quando um servidor de autorização verifica se o valor do parâmetro redirect_uri corresponde a um pré-registrado, a regra descrita em “6. Normalization and Comparison” of RFC 3986 (Uniform Resource Identifier (URI): Sintaxe genérica) é aplicado, a menos que o pré-registro seja de uma URI absoluta. Por outro lado, o FAPI (e também o OIDC) requer que uma comparação de string simples seja sempre usada para verificar se as URIs de redirecionamento correspondem.

Part 1: 5.2.2. Servidor de autorização, 11.

deve exigir autenticação do usuário para um nível de garantia apropriado para as operações que o cliente será autorizado a realizar em nome do usuário;

É necessário que a autenticação do usuário executada durante o processo de autorização satisfaça um nível apropriado de garantia. ID1 e ID2 exigidos LoA (nível de garantia, Level of Assurance) 2, que é definido em X.1254 (Estrutura de garantia de autenticação de entidade. No entanto, a versão final tornou o requisito mais abstrato ( mudou o requisito de “LoA2” para “LoA apropriado”).

Nota: A seguir está a definição de LoA 2 descrita em “6.2 Nível de garantia 2 (LoA2)” de X.1254.

Na LoA2, há alguma confiança na identidade reivindicada ou afirmada da entidade. Este LoA é usado quando há risco associado à autenticação. A autenticação de um único fator é aceitável. A autenticação bem-sucedida deve depender da entidade provar, por meio de um protocolo de autenticação seguro, que a entidade tem o controle da credencial. Devem existir controles para reduzir a eficácia de ataques de adivinhação online ou introspecção indevida. Os controles devem estar em vigor para proteger contra ataques a credenciais armazenadas.

Por exemplo, um provedor de serviços pode operar um site que permite que seus clientes alterem seu endereço de registro. A transação na qual um beneficiário altera um endereço de registro pode ser considerada uma transação de autenticação LoA2, pois a transação pode envolver um risco moderado de inconveniência. Como os avisos oficiais sobre valores de pagamento, status da conta e registros de alterações são geralmente enviados para o endereço de registro do beneficiário, a transação também envolve risco moderado de liberação não autorizada de PII. Como resultado, o provedor de serviços deve obter pelo menos alguma garantia de autenticação antes de permitir que essa transação ocorra.

Part 1: 5.2.2. Servidor de autorização, 12.

deve exigir a aprovação explícita do usuário para autorizar o escopo solicitado, caso não tenha sido previamente autorizado;

Claro.

Part 1: 5.2.2. Servidor de autorização, 13.

deve rejeitar um código de autorização (Seção 1.3.1 do RFC6749) se ele tiver sido usado anteriormente;

Proibir a reutilização de códigos de autorização e garantir que códigos de autorização nunca tenham sido usados anteriormente são coisas diferentes. Se a implementação atual de um servidor de autorização usa cadeias geradas aleatoriamente como códigos de autorização e as remove do banco de dados depois de serem usados, os códigos de autorização devem ser mantidos no banco de dados mesmo depois de serem usados apenas para a verificação. Se as strings que representam códigos de autorização são geradas aleatoriamente com entropia alta o suficiente, é um desperdício manter códigos de autorização no banco de dados mesmo após seu uso. Um certo engenheiro famoso diz: “A maioria das implementações evita a reutilização de códigos de autorização, excluindo os registros do banco de dados correspondentes e não verifica se eles foram usados anteriormente, e se tais implementações são suficientes”.

Part 1: 5.2.2. Servidor de autorização, 14.

deve retornar respostas de token que estejam em conformidade com a Seção 4.1.4 do RFC6749;

Este não é um requisito específico da FAPI. Cada implementação de servidor de autorização que afirma ser compatível com OAuth 2.0 deve estar em conformidade com a Section 4.1.4 da RFC 6749.

Part 1: 5.2.2. Servidor de autorização, 15.

deve retornar a lista de escopos concedidos com o token de acesso emitido se a solicitação foi aprovada no canal frontal e não foi protegida por integridade;

No RFC 6749, scope o parâmetro de resposta pode ser omitido, a menos que os escopos solicitados e os concedidos sejam diferentes (RFC 6749, 5.1. Successful Response). No FAPI, o parâmetro scope da resposta é necessário (mesmo se os escopos solicitados e os concedidos forem iguais) se a solicitação de autorização for passada no canal de entrada e não for protegida por integridade.

“Integridade protegida” aqui significa que um objeto de solicitação (OIDC Core Section 6 do JAR) é usado.

Part 1: 5.2.2. Servidor de autorização, 16.

deve fornecer tokens de acesso não adivinhados, códigos de autorização e token de atualização (quando aplicável), com entropia suficiente de modo que a probabilidade de um invasor adivinhar o token gerado seja computacionalmente inviável de acordo com a RFC 6749 Seção 10.10;

O ID2 exige que os tokens de acesso tenham no mínimo 128 bits de entropia, mas a versão final evita mencionar o tamanho exato da entropia mínima e apenas diz “entropia suficiente”.

Part 1: 5.2.2. Servidor de autorização, 17.

deve identificar claramente os detalhes da concessão ao usuário durante a autorização conforme 16.18 do OIDC;

Suponha que um aplicativo cliente solicite o escopo payment. Uma página de autorização comum dirá ao usuário apenas que o aplicativo cliente está solicitando o escopo payment. No entanto, regulamentações recentes nos setores financeiros exigem que os detalhes sejam explicados ao usuário. Por exemplo, informações sobre a finalidade do acesso ao escopo payment, como a quantia de dinheiro transferida e assim por diante. De um modo geral, os regulamentos recentes exigem que a concessão seja mais específica.

O UK Open Banking inventou a “Intenção de Hospedagem”, ou em inglês “Lodging Intent” para esse fim. No mecanismo, um aplicativo cliente registra detalhes de concessão que deseja em um servidor de autorização com antecedência, o servidor de autorização emite um ID de intenção que representa os detalhes registrados e o cliente faz uma solicitação de autorização com o ID da intenção. Como resultado, o servidor de autorização pode gerar uma página de autorização que inclui os detalhes da solicitação de autorização.

Para disponibilizar o padrão de intenção de hospedagem como padrões, a OpenID Foundation desenvolveu duas especificações separadas, são elas:

“OAuth 2.0 Pushed Authorization Requests” (PAR) e “OAuth 2.0 Rich Authorization Requests” (RAR). Essas especificações serão detalhadas ao longo do artigo.

Part 1: 5.2.2. Servidor de autorização, 18.

deve fornecer um mecanismo para o usuário final revogar tokens de acesso e atualizar tokens concedidos a um cliente, conforme 16.18 do OIDC;

Deve-se notar que, se o formato dos tokens de acesso for do tipo autocontido (por exemplo, JWT), os tokens de acesso não podem ser revogados, a menos que o sistema implemente e utilize um mecanismo como CRL (Certificate Revocation List) ou OCSP (Online Certificate Status Protocol) do PKI (Public Key Infrastructure). Se o sistema não fornecer esse mecanismo, significa que o sistema decidiu desistir da revogação dos tokens de acesso. Nesse caso, a duração dos tokens de acesso deve ser curta o suficiente para mitigar os danos do vazamento do token de acesso. Verifique mais detalhes em “OAuth Access Token Implementation”

Part 1: 5.2.2. Servidor de autorização, 19.

deve retornar o erro invalid_client conforme definido em 5.2 da RFC6749 quando identificadores de cliente incompatíveis for fornecidos por meio de métodos de autenticação de cliente que permitam o envio do identificador de cliente de várias maneiras;

FAPI Part 1 requer o MTLS (tls_client_auth, self_signed_tls_client_auth) ou JWT (client_secret_jwt, private_key_jwt) para autenticação do cliente.

MTLS usa um certificado de cliente, mas um certificado não inclui o identificador de clienteque tenta se autenticar com o certificado. Portanto, o parâmetro de requisição client_id precisa ser enviado explicitamente.

Por outro lado, o método de autenticação baseado em JWT, tem o valor do parâmetro client_assertion e o JWT contém a identificação do cliente na declaração iss. Todavia, o parâmetro client_id não é necessário. Adicionalmente, de acordo com a RFC 7523, 3. e OIDC Core, 9., a declaração sub também contém a identificação do cliente quando o JWT é utilizado como método de autenticação.


JWT-based Client Authentication and Client Identifiers

No MTLS, somente o parâmetro client_id representa a identificação do cliente. Por outro lado, a autneticação baseada em JWT, usa ambos, o iss e o sub para identificar o cliente. Os valores devem ser correspondente. Além disso, se o client_id for apresentado em uma autenticação baseada em JWT, o valor do parâmetro também deve ser correspondente com os demais anteriores.

Part 1: 5.2.2. Servidor de autorização, 20.

deve requerer que a URI de redirecionamento use https;

Este requisito adicionado pelo FAPI ID2 é pequeno, mas tem um grande impacto. Por causa disso, os desenvolvedores não podem mais usar esquemas customizados no FAPI. Para tratar o redirecionamento no lado do cliente sem preparar um servidor Web externo, os desenvolvedores devem usar o método descrito em “7.2. Claimed “https” Scheme URI Redirection” do BCP 212 (OAuth 2.0 para App Nativos).

Part 1: 5.2.2. Servidor de autorização, 21.

deve emitir tokens de acesso com uma vida útil de menos de 10 minutos, a menos que os tokens sejam restritos pelo remetente; e

Este requisito foi adicionado pela versão final da FAPI. “Restrito pelo remetente” aqui significa que os tokens de acesso devem ser vinculados a um certificado de cliente (MTLS).

Part 1: 5.2.2. Servidor de autenticação, 22.

deve suportar OIDD, pode suportar RFC8414 e não deve revelar os metadados de descoberta (como o endpoint de autorização) por qualquer outro meio.

Este requisito foi adicionado pela versão final da FAPI. OIDD é a abreviação de “OpenID Connect Discovery 1.0”. Todavia, os servidores de autorização FAPI devem implementar um “ponto final de descoberta” que é definido no OIDD, seção 4 (Section 4).

Part 1: 5.2.2.1. Retornando a identificação do usuário autenticado

Além disso, se for desejado transmitir o identificador do usuário autenticado ao cliente na resposta do token, o servidor de autorização:

Seção 5.2.2.1. lista os requisitos que um servidor de autorização deve seguir quando o identificador do usuário autenticado é solicitado. Em outras palavras, quando um ID token é solicitado.

Part 1: 5.2.2.1. Retornando a identificação do usuário autenticado, 1.

deve apoiar a solicitação de autenticação conforme a Seção 3.1.2.1 do OIDC;

“3.1.2.1. Authentication Request” do OIDC Core é a definição de uma solicitação para um endpoint de autorização no contexto do OpenID Connect. O RFC 6749 chama uma solicitação para um endpoint de autorização “solicitação de autorização”. O OIDC Core chama isso de “solicitação de autenticação”. Além dos nomes, considerando que a especificação de um endpoint de autorização é a parte principal do OIDC Core, o requisito da FAPI é similar ao declarar “deve oferecer suporte ao OIDC Core_”_.

Part 1: 5.2.2.1. Retornando a identificação do usuário autenticado, 2.

deve realizar a verificação da solicitação de autenticação conforme a Seção 3.1.2.2 do OIDC;

Part 1: 5.2.2.1. Retornando a identificação do usuário autenticado, 3.

deverá autenticar o usuário conforme as Seções 3.1.2.2 e 3.1.2.3 do OIDC;

Part 1: 5.2.2.1. Retornando a identificação do usuário autenticado, 4.

deve fornecer a resposta de autenticação como na Seção 3.1.2.4 e 3.1.2.5 do OIDC dependendo do resultado da autenticação;

Part 1: 5.2.2.1. Retornando a identificação do usuário autenticado, 5.

deve realizar a verificação da solicitação de token conforme a Seção 3.1.3.2 do OIDC; e

Part 1: 5.2.2.1. Retornando a identificação do usuário autenticado, 6.

deve emitir um token de identificação na resposta do token quando openid for incluído no escopo da requisição em scope conforme a seção 3.1.3.3 do OIDC com o seu valor sub correspondendo ao valor do usuário autenticado e opcionalmente no valor acr do ID Token.

O resumo dos requisitos acima é “deve seguir as especificações OIDC Core”. Nada de especial para a FAPI.

Part 1: 5.2.2.2. Escopo Open id requisitado pelo cliente

Se o cliente requer o escopo openid, o servidor de autorização

    1. deve requerer o parâmetro nonce definido na seção 3.1.2.1 do OIDC na requisição de autenticação.

OIDC Seção 3.1.2.1 (Fluxo de código de autorização) afirma que nonce é opcional. Por outro lado, OIDC Seção 3.2.2.1 (Implicit Flow) afirma que nonce é mandatório.

O requisito FAPI acima requer nonce mesmo no fluxo do código de autorização, se o openid é incluido no scope.

Part 1: 5.2.2.3. Escopo Open id requisitado pelo cliente

Se o cliente não solicitar o escopo openid o servidor de autorização

    1. deve requerer o parâmetro state definido na Seção 4 da RFC6749

Na RFC 6749, o parâmetro state é opcional. O FAPI torna o parâmetro mandatório quando openid não esta incluido no scope.

Part 1: Requisitos para o Cliente Público

“5.2.3. Public client” d0 “Part 1” lista os requisitos para o cliente público. Vamos ver esses requisitos a seguir

Part 1: 5.2.3. Cliente público, 1.

Deve suprotar a RFC7636;

RFC 7636 é PKCE.

Part 1: 5.2.3. Cliente público, 2.

deve usar S256 como o método de desafio de código para o RFC7636;

Isso significa que “uma solicitação de autorização deve incluir code_challenge_method=S256__.”

Part 1: 5.2.3. Cliente público, 3.

deve usar URI de redirecionamento separado e distinto para cada servidor de autorização com o qual se comunica;

Part 1: 5.2.3. Cliente público, 4.

deve armazenar a URI de redirecionamento na sessão de agentes de usuário (como navegador) do proprietário do recurso e compará-lo com o URI de redirecionamento em que a resposta de autorização foi recebida, onde, se os URIs não corresponderem, o cliente deve encerrar o processo com erro;

Esses requisitos são tão claros que não são necessárias mais explicações.

Part 1: 5.2.3. Cliente público, 5.

(retirado); e

(retirado); e aqui indica que o requisito que existia nas versões anteriores da FAPI foi retirado. Você também verá mais “retirados” nas seções a seguir.

Part 1: 5.2.3. Cliente público, 6.

deve implementar uma proteção eficaz contra CSRF.

Em casos normais, a proteção CSRF é implementada no lado do servidor. O que é proteção contra CSRF como um requisito para clientes públicos? Esta é a proteção CSRF para redirecionar URIs. A parte a seguir é um trecho da Seção “10.12. Cross-Site Request Forgery” do RFC 6749.

O cliente DEVE implementar proteção contra CSRF para seu URI de redirecionamento. Isso normalmente é realizado exigindo que qualquer solicitação enviada a URI de redirecionamento inclua um valor que vincule a solicitação ao estado autenticado do agente do usuário (por exemplo, um hash do cookie de sessão usado para autenticar o agente do usuário). O cliente DEVE utilizar o parâmetro de solicitação “estado” para entregar este valor ao servidor de autorização ao fazer uma solicitação de autorização.

Além dos requisitos de “Cliente público, 1” para “Cliente público, 6”, “se for desejado obter um identificador persistente do usuário autenticado”, ou seja, se um ID token for solicitado, um pedido de autorização por um cliente público:

Part 1: 5.2.3. Cliente público, 7.

deve incluir openid no valor do scope; e

Part 1: 5.2.3. Cliente público, 8.

deve incluir o parâmetro nonce definido na Seção 3.1.2.1 do OIDC na requisição de autenticação.

Por outro lado, “Se openid não está no valor do scope”, um pedido de autorização por um cliente público:

Part 1: 5.2.3. Cliente público, 9.

deve incluir o parâmetro state definido na Seção 4.1.1 da RFC6749;

Part 1: 5.2.3. Cliente público, 10.

deve verificar se o scope recebido na resposta do token é uma correspondência exata ou contém um subconjunto do scope enviado no pedido de autorização; e

Part 1: 5.2.3. Cliente público, 11.

deve usar apenas metadados do Servidor de Autorização obtidos a partir do documento de metadados publicado pelo Authorization Server em seu terminal bem conhecido, conforme definido no OIDD ou RFC 8414.

Part 1: Requisitos para o Cliente Confidencial

“5.2.4. Confidential client” da “Part 1” lista os requisitos para clientes confidenciais. Os requisitos são posicionados como acréscimos aos requisitos para clientes públicos. Portanto, os clientes confidenciais devem seguir não apenas os requisitos em 5.2.4, mas também os requisitos em 5.2.3.

 Part 1: 5.2.4. Cliente confidencial, 1.

deve suportar os seguintes métodos para autenticação em relação ao endpoint de token:

    1. TLS mútuo para autenticação de cliente OAuth conforme especificado na Seção 2 do MTLS, e
    2. client_secret_jwt ou private_key_jwt conforme especiicado na Seção 9 do OIDC;

Observe que os métodos de autenticação de cliente definidos em RFC 6749 (client_secret_basic e client_secret_post) não podem ser usados

Part 1: 5.2.4. Cliente confidencial, 2.

deve usar chaves RSA com um mínimo de 2048 bits se estiver usando criptografia RSA;

Part 1: 5.2.4. Cliente confidencial, 3.

deve usar chaves de curva elíptica com um mínimo de 160 bits se estiver usando criptografia de curva elíptica; e

Part 1: 5.2.4. Cliente confidencial, 4.

deve verificar se o segredo do cliente tem um mínimo de 128 bits se estiver usando criptografia de chave simétrica.

Esses requisitos se aplicam quando JWTs criptografados são usados.

Part 1: Requisitos para Recursos Protegidos

“6.2.1. Protected resources provisions” da “Part 1” lista os requisitos para recursos protegidos.

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 1.

deve suportar o uso do método HTTP GET como na Seção 4.3.1 do RFC7231;

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 2.

deve aceitar tokens de acesso no cabeçalho HTTP como na Seção 2.1 do OAuth 2.0 Bearer Token Usage RFC6750;

Ou seja, os endpoints de recursos protegidos devem oferecer suporte ao método HTTP GET e ser capaz de aceitar um token de acesso no formato de Authorization: Bearer {AccessToken}.


Request to Protected Resource Endpoint

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 3.

não deve aceitar tokens de acesso nos parâmetros de consulta indicados na Seção 2.3 do OAuth 2.0 Bearer Token Usage RFC6750;

Ou seja, os terminais de recursos protegidos não devem aceitar um parâmetro de consulta no formato de access_token={AccessToken}.

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 4.

deve verificar se o token de acesso não expirou nem foi revogado;

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 5.

deve verificar se o escopo associado ao token de acesso autoriza o acesso ao recurso que está representando;

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 6.

deve identificar a entidade associada ao token de acesso;

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 7.

deve retornar apenas o recurso identificado pela combinação da entidade implícita no acesso e o escopo concedido e, de outra forma, retornar erros como na Seção 3.1 da RFC6750;

Estas são etapas gerais de verificação de token de acesso que se espera que os endpoints de recursos protegidos realizem.

“3.1. Error Codes” da RFC 6750 define três códigos de erro. São eles invalid_request, invalid_token e insufficient_scope. Um ponto que aqueles que não estão familiarizados com o RFC 6750 podem se sentir estranhos é que um código de erro está embutido não no corpo da resposta, mas no WWW-Authenticate , no cabeçalho HTTP.


RFC 6750 Error Response

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 8.

deve realizar a codificação da resposta em UTF-8 se aplicável;

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 9.

deve enviar o cabeçalho HTTP Content-type como Content-Type: application/json; se aplicável;

Espera-se que os endpoints de recursos protegidos em FAPI retornem suas respostas no formato JSON.

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 10.

deve enviar a data do servidor no cabeçalho HTTP Date conforme Seção 7.1.1.2 da RFC7231;

O formato do cabeçalho Date esta definido em “7.1.1.1. Date/Time Formats” da RFC 7231. Exemplo abaixo.

Date: Sun, 06 Nov 1994 08:49:37 GMT

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 11.

de enviar o cabeçalho de resposta dentro do valor x-fapi-interaction-id que corresponde ao cabeçalho da requisição do cliente ou ao valor do tipo UUID da RFC 4122 caso o cabeçalho de requisição não tenha previsto um para controlar a requisição, e.g., x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a;

Este é um requisito específico da FAPI. As respostas dos endpoints de recursos protegidos pelo FAPI devem incluir no cabeçalho x-fapi-interaction-id.

Quando a requisição possui o x-fapi-interaction-id, o mesmo valor do cabeçalho deve ser incluído na resposta. Caso contrário, o endpoint de recurso protegido deve gerar um novo valor para x-fapi-interaction-id.

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 12.

deve registrar o x-fapi-interaction-id no arquivo de log; e

Isso é específico para o FAPI. Esse requisito não tem impacto sobre os formatos de solicitação e resposta, mas pode facilitar a correlação de registros do lado do servidor e do lado do cliente.

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 13.

não deve rejeitar requisições com o cabeçalho x-fapi-customer-ip-address que contenha um valor válido do tipo IPv4 ou IPv6.

Part 1: 6.2.1. Pré-requisitos de recursos protegidos, 14.

deve oferecer suporte ao uso de Cross Origin Resource Sharing (CORS) [CORS] e ou outros métodos conforme apropriado para permitir que clientes JavaScript acessem o terminal se decidir fornecer acesso a clientes JavaScript.

Por exemplo, se um endpoint de recurso protegido deseja permitir que clientes JavaScript o acessem de qualquer lugar, o endpoint deve incluir um cabeçalho Access-Control-Allow-Origin: * nas respostas.

Part 1: Requisitos para os Clientes de Recursos Protegidos

“6.2.2. Client provisions” da “Part 1” lista os requisitos a serem seguidos pelos clientes ao acessar recursos protegidos.

Part 1: 6.2.2. Pré-requisitos do Cliente, 1.

deve enviar tokens de acesso no cabeçalho HTTP conforme a Seção 2.1 do OAuth 2.0 Bearer Token Usage RFC6750; e

Ou seja, os clientes devem enviar um token de acesso no formato de Authorization: Bearer {AccessToken}.

Part 1: 6.2.2. Pré-requisitos do Cliente, 2.

(retirado);

Part 1: 6.2.2. Pré-requisitos do Cliente, 3.

pode enviar a última vez que o cliente logou no cliente no cabeçalho x-fapi-auth-date onde o valor é fornecido como uma data, similar ao cabeçalho HTTP apresentado anteriormente, e conforme Seção 7.1.1.1 de RFC7231, e.g., x-fapi-auth-date: Tue, 11 Sep 2012 19:43:31 GMT;

Part 1: 6.2.2. Pré-requisitos do Cliente, 4.

pode enviar o endereço IP do cliente se esses dados estiverem disponíveis no cabeçalho x-fapi-customer-ip-address, e.g., x-fapi-customer-ip-address: 2001:DB8::1893:25c8:1946 ou x-fapi-customer-ip-address: 198.51.100.119; e

Part 1: 6.2.2. Pré-requisitos do Cliente, 5.

x-fapi-interaction-id, nesse caso, o valor deve ser um UUID RFC4122 para ajudar o servidor a correlacionar as entradas de log entre o cliente e o servidor, e.g., x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a.

Esses são cabeçalhos HTTP específicos do FAPI. Depende do cliente enviar ou não os cabeçalhos.


FAPI-specific HTTP Headers

Part 1: Considerações de Segurança

“7. Security considerations” da “Part 1” lista as considerações de segurança. O resumo é o seguinte.

7.1. — Siga o BCP 195. Utilize o TLS 1.2 ou mais recente. Siga RFC 6125.

7.2. — Part 1 não autentica solicitação de autorização e resposta.

7.3. — Part 1 não garante a integridade da mensagem de solicitação de autorização.

7.4.1. — Part 1 não entra no mérito da criptografia de solicitação de autorização.

7.4.2. — Tenha cuidado para não vazar informações por meio de registros de log.

7.4.3. — Tenha cuidado para não vazar informações através do referenciador. Faça a duração dos tokens de acesso curta.

7.5. — Aplicações nativas devem seguir o BCP 212 mas não devem suportar “Private-Use URI Scheme Redirection” e “Loopback Interface Redirection”. Eles devem usar o https para o esquema de redirecionamento da URI conforme introduzido no “Claimed https Scheme URI Redirection”.

7.6. — Tanto a implementação FAPI quanto a implementação OAuth / OIDC subjacente devem ser completas e corretas. Verifique em OpenID Certification.

7.7. — Use um issuer diferente por marca, caso seja necessário suportar diferentes marcas ou empresas.

“Part 2” fornece soluções para considerações de segurança listadas na “Parte 1”, por exemplo, tornando “objeto de solicitação” obrigatório. A “Parte 2” é recomendada quando uma segurança maior do que a “Parte 1” é necessária.

Part 2: Advanced (Avançado)

Próximo, vamos verificar o “Part 2” que define alguns requisitos avançados de segurança.

Assinatura desvinculada

“5.1.1. ID Token as Detached Signature” do “Part 2” determina que ele utiliza o “ID token” como uma “assinatura desvinculada (detached signature)”.

Um ID Token é assinado por um servidor de autorização, portanto, mesmo que um invasor adultere o conteúdo do ID Token, ele pode ser detectado. Um aplicativo cliente que recebeu um ID Token pode confirmar que o ID Token não foi adulterado, verificando a assinatura do ID Token.

Se um servidor de autorização incorpora valores hash de parâmetros de resposta (como code e state) em um ID Token, um aplicativo cliente pode confirmar que os valores dos parâmetros de resposta não foram adulterados calculando os valores de hash dos valores de parâmetro de resposta e comparando-os aos valores de hash embutidos no ID Token. No contexto, o token de ID é considerado uma assinatura separada.


ID Token as Detached Signature

Para o parâmetro de resposta code que representa um código de autorização, c_hash representa um código de autorização code. Assim como, at_hash representa um código de autorização access_token.

Representa um código de autorização como parâmetro de resposta state. Para, “5.1.1. ID Token as Detached Signature” define o s_hash para este propósito.

s_hash

Valor de hash do estado. Seu valor é a codificação de base64url da metade esquerda do hash dos octetos da representação ASCII do valor no parâmetro state, onde o algoritmo de hash usado é o algoritmo de hash usado no alg parâmetro de cabeçalho do cabeçalho JOSE do token de ID. Por exemplo, se o alg for HS512, hash o valor do estado com SHA-512, depois pegue os 256 bits mais à esquerda e base64url codifique-os. O valor é uma string que leva em consideração maiusculas e minusculas s_hash.

Como a “Parte 2” usa tokens de ID como assinaturas separadas, mesmo se os aplicativos cliente não precisarem de tokens de ID em sua camada de aplicativo, eles precisam enviar solicitações de autorização que exigem um token de ID. Para ser exato, eles devem incluir id_token no parâmetro de requisição no response_type. Esta é a razão pela qual o segundo requisito em “5.2.2. Authorization Server” está dizendo “exigirá os valores do response_type e code id_token__”.

No entanto, desde o Rascunho 2 do Implementador, os ID Tokens não precisam ser usados como assinaturas separadas quando JARM é usado. É porque todo o conjunto de parâmetros de resposta é compactado em um JWT.

Part 2: Requisitos para o Servidor de Autorização (Authorization Server)

“5.2.2. Authorization server” da “Part 2” lista os requisitos para o servidor de autorização.

Part 2: 5.2.2. Servidor de autorização, 1.

exigirá um objeto de solicitação JWT assinado JWS passado por valor com o parâmetro request parameter ou por referência através do parâmetro request_uri;

Os parâmetros request e request_uri são definidos em “6. Passing Request Parameters as JWTs” of OIDC Core. Para usar esses parâmetros, a primeira etapa é compactar os parâmetros de solicitação em um JWT. Este JWT é denominado “objeto de solicitação”. Uma solicitação de autorização (1) passa o objeto da solicitação como o valor do parâmetro request diretamente ou (2) coloca o objeto de solicitação em algum lugar acessível a partir do servidor de autorização e passa o URI apontando para o local como o valor do parâmetro request_uri.

Passing a Request Object by Value

A assinatura de um objeto de solicitação não é obrigatória no OIDC Core, mas a assinatura é obrigatória na FAPI Parte 2. Se os objetos de solicitação forem assinados, os servidores de autorização podem confirmar que os parâmetros de solicitação não foram adulterados, verificando as assinaturas dos objetos de solicitação.

Para ser honesto, o que mais me surpreendeu quando li a especificação FAPI pela primeira vez (muitos anos atrás) foi esse requisito. É porque eu sabia, por experiência própria, que é difícil implementar o recurso de objeto de solicitação no lado do servidor de autorização. Como o recurso é difícil de implementar e opcional em OIDC, existem muitas implementações de servidor de autorização que afirmam que oferecem suporte a OIDC, mas não oferecem suporte a objeto de solicitação. Tenha cuidado para não escolher uma implementação de servidor de autorização que não suporte objeto de solicitação se você quiser construir um sistema que suporte FAPI Parte 2.

Part 2: 5.2.2. Servidor de autorização, 2.

deve requerer

    1. o response_type com valor code id_token, ou
    2. o response_type com valor code em ligação com o response_mode com valor jwt;

Para usar ID Token como assinatura separada, mesmo se um ID Token não for necessário na camada da aplicação, o id_token deve ser incluido no parâmetro da requisição response_type.

Mas, conforme mencionado anteriormente o id_token não precisa ser incluido no response_type quando o JARM é usado. “Quando o JARM é utilizado”, é, de forma concreta, “quando o parâmetro da requisição response_mode é incluido e o seu valor é igual a algum dos a seguir, query.jwt, fragment.jwt, form_post.jwt e jwt”.

NOTA: ID2 requer que o response_type seja tanto code id_token ou code id_token token quando o JARM não é utilizado, mas a versão Final retirou o code id_token token.

Part 2: 5.2.2. Servidor de autorização, 3.

(movido para 5.2.2.1);

Part 2: 5.2.2. Servidor de autorização, 4.

(movido para 5.2.2.1);

Part 2: 5.2.2. Servidor de autorização, 5.

deve apenas emitir tokens de acesso restrito do remetente;

Em ID2, esta cláusula era “só deve emitir código de autorização, token de acesso e token de atualização que são detentores dos limites da chave;”. No entanto, como o requisito era impraticável, ele foi alterado para o atual. Verifique em FAPI Issue 202 para maiores detalhes.

Part 2: 5.2.2. Servidor de autorização, 6.

deve suportar MTLS como mecanismo para restringir os remetentes legítimos de tokens de acesso;

Em ID2, esta cláusula era “deve apoiar [OAUTB] ou [MTLS] como um detentor de mecanismos de chave;”. No entanto, OAUTB (Token Binding) foi removido da versão final devido à sua improbabilidade de disponibilidade futura.

Part 2: 5.2.2. Servidor de autorização, 7.

(retirado);

Part 2: 5.2.2. Servidor de autorização, 8.

(movido para 5.2.2.1);

Part 2: 5.2.2. Servidor de autorização, 9.

(movido para 5.2.2.1);

Part 2: 5.2.2. Servidor de autorização, 10.

deve usar apenas os parâmetros incluídos no objeto de solicitação assinado, passado por meio do parâmetro request ou request_uri;

Em ID2, este requisito era “deve exigir que todos os parâmetros estejam presentes dentro do objeto de solicitação assinado passado no parâmetro request ou request_uri__;”. A expressão foi alterada, mas o ponto permanece o mesmo. Um objeto de solicitação deve incluir todos os parâmetros de solicitação para estar em conformidade com a FAPI Parte 2.

Isso é diferente do OIDC Core, que permite que parâmetros de solicitação sejam colocados dentro ou fora de um objeto de solicitação e os mescla.

Part 2: 5.2.2. Servidor de autorização, 11.

pode suportar o endpoint de solicitação de autorização por push, conforme descrito em PAR;

O “endpoint de solicitação de autorização por push” é um novo endpoint definido em “OAuth 2.0 Pushed Authorization Requests” (PAR). O aplicativo cliente pode registrar uma solicitação de autorização no terminal e obter um URI de solicitação que representa a solicitação de autorização registrada. O cliente especifica a URI de solicitação através do parâmetro request_uri quando envia uma requisição de autorização para o endpoint de autorização.

O diagrama a seguir foi retirado do artigo “Illustrated PAR: OAuth 2.0 Pushed Authorization Requests” mostra o fluxo do código de autorização que utiliza o endpoint de solicitação de autorização enviada.

Authorization Code Flow with Pushed Authorization Request Endpoint

História: A sétima seção do ID2 mostrou uma ideia sobre o pré-registro de um pedido de autorização. A seção denominada endpoint para o pré-registro “endpoint do objeto de solicitação”. A especificação do PAR foi desenvolvida com base na ideia. Como resultado, a versão FAPI Final retirou a 7ª seção.

Part 2: 5.2.2. Servidor de autorização, 12.

(retirado);

Part 2: 5.2.2. Servidor de autorização, 13.

deve exigir que o objeto da solicitação contenha uma declaração exp que tem uma vida útil não superior a 60 minutos após a declaração nbf;

O OIDC Core não exige que os objetos de solicitação incluam a declaração exp. Em contrapartida, FAPI Part 2 requer de forma mandatória a declaração exp.

Além disso, a versão final adicionou o requisito de “uma vida útil não superior a 60 minutos após a declaração nbf__”. Por causa desse requisito, a declaração nbf se tornou mandatória.

O novo requisito é uma mudança significativa do ponto de vista dos aplicativos clientes porque os servidores de autorização agora rejeitam as solicitações de autorização cujo objeto de solicitação não inclui a declaração nbf. Na verdade, alguns casos de teste na ferramenta oficial de conformidade (conformance suite) deverá ser atualizado com esse novo requisito.

As implementações do servidor de autorização podem fornecer um mecanismo para mitigar o impacto da alteração significativa. Por exemplo, Authlete definiu Service.nbfOptional como uma que indica quando a declaração nbf no objeto de solicitação é opcional, mesmo quando a solicitação de autorização é considerada uma solicitação FAPI-Parte2. O valor do sinalizador pode ser alterado por “nbf Claim” no console do proprietário do serviço.

Service Configuration: nbf Claim

Part 2: 5.2.2. Servidor de autorização, 14.

deve autenticar o cliente confidencial usando um dos seguintes métodos (isto substitui o FAPI Security Profile 1.0 – Parte 1: cláusula 5.2.2-4):

    1. tls_client_auth ou self_signed_tls_client_auth conforme especificado na seção 2 do MTLS, ou
    2. private_key_jwt conforme especificado na seção 9 do OIDC;

Perceba que client_secret_jwt não é permitido no Part 2. Isso é diferente do Part 1.

Client Authentication Methods in FAPI

Part 2: 5.2.2. Servidor de autorização, 15.

deve requisitar que a declaração aud no objeto a ser requisitado, ou para ser uma matriz contendo, o URL do identificador do emissor do OP;

Este requisito foi adicionado pela Final Version. Os aplicativos do cliente devem colocar a declaração aud na requisição. O valor do “OP’s Issuer Identifier URL” pode ser encontrado no documento como o metadado do issuer (cf. OpenID Connect Discovery 1.0, 3. OpenID Provider Metadata).

Part 2: 5.2.2. Servidor de autorização, 16.

não deve apoiar clientes públicos;

Este requisito é um novo adicionado pela Final Version, mas diz-se que é logicamente impossível oferecer suporte a clientes públicos no contexto da FAPI Parte 2 desde as versões FAPI mais antigas.

Part 2: 5.2.2. Servidor de autorização, 17.

deve exigir que o objeto da solicitação contenha a declaração nbf e que ela tenha sido criada a no máximo 60 minutes, e

O décimo terceiro requisito implica que a declaração nbf é mandatória. Neste requisito a declaração é explícita.

Part 2: 5.2.2. Servidor de autorização, 18.

deve exigir solicitações PAR, se suportadas, para usar PKCE (RFC7636) com S256 como código de desafio.

“PAR” aqui é “Solicitações de autorização por push do OAuth 2.0”.

5.2.2.1. Assinatura do ID Token desacoplada

Adicionalmente, se o response_type com valor code id_token é usado, o servidor de autorização.

Seção 5.2.2.1. lista os requisitos para servidores de autorização que são aplicados quando um token de ID é usado como uma assinatura separada.

5.2.2.1. Assinatura do ID Token desacoplada, 1.

deve suportar OIDC;

5.2.2.1. Assinatura do ID Token desacoplada, 2.

deve suportar ID Tokens assinados;

5.2.2.1. Assinatura do ID Token desacoplada, 3.

deve suportar ID Tokens encriptados e assinados;

Do ponto de vista do OIDC, esses requisitos não são novos. Por definição, os ID Tokens são sempre assinados. A criptografia de ID Tokens é opcional.

Part 2: 5.2.2.1. Assinatura do ID Token desacoplada, 4.

deve retornar o token de identificação como uma assinatura separada para a resposta de autorização;

Isso requer que um servidor de autorização emita um token de ID, mas porque a condição escrita na parte superior da Seção 5.2.2.1 exige que id_token seja incluido no response_type e, portanto, um ID Token é emitido como uma consequência geral, esse requisito não precisa existir.

Part 2: 5.2.2.1. Assinatura do ID Token desacoplada, 5.

deve incluir o estado da hash, s_hash, no ID Token para proteger o valor do state se o cliente forneceu um valor para state. s_hash pode ser omitido do ID Token retornado do endpoint do token quando s_hash esta presente no ID Token retornado pelo endpoint do Servidor de Autorização; e

Quando o JARM é usado, este requisito não precisa ser seguido.

Part 2: 5.2.2.1. Assinatura do ID Token desacoplada, 6.

não deve retornar PII confidenciais no ID Token na resposta de autorização, mas se for necessário, deve criptografar o ID Token.

PII é abreviação de “Personally Identifiable Information” (Informação pessoalmente identificável).

O recurso de criptografia de ID Token existe desde o OIDC Core. Quando o algoritmo de criptografia para tokens de ID é assimétrico, o servidor de autorização deve (1) gerenciar as chaves públicas de aplicativos clientes diretamente em seu banco de dados ou (2) buscar documentos do conjunto de JWK dos locais apontados pelos metadados do cliente no jwks_uri e extrair chaves públicas dos documentos.

Para assinar ID Tokens, usa somente as chaves do lado do servidor e somente ele pode manipular essas chaves.

ID Token Signing

Em contraste, se um servidor de autorização deseja oferecer suporte à criptografia de ID Tokens, o servidor de autorização também deve manipular as chaves do lado do cliente.

ID Token Encryption

Este é o motivo pelo qual não um pequeno número de implementações de servidor de autorização não suporta criptografia de token de ID.

5.2.2.2. JARMAdicionalmente, se o valor do response_type seja code, é utilizado em conjunto com o valor do response_mode como jwt, no servidor de autorização

5.2.2.2. JARM, 1.

deve criar respostas de autorização protegidas pelo JWT conforme especificado no JARM, Seção 4.3.

Esta cláusula não inclui quaisquer requisitos específicos do FAPI. Diz apenas que as implementações JARM devem funcionar conforme a especificação JARM.

Quando response_type não contém o id_token, a resposta de autorização não incluirá nenhum ID Token. Portanto, um ID Token não pode ser usado como uma assinatura separada. Neste caso, o JARM deve ser usado para garantir que a resposta de autorização não foi adulterada.

Part 2: Requisitos para Cliente Confidencial

A versão final da FAPI renomeou a Parte 2: Seção 5.2.3 de “Cliente público” para “Cliente confidencial”.

 Part 2: 5.2.3. Cliente confidencial, 1.

deve suportar MTLS como mecanismo para tokens de acesso restrito do remetente;

Ou seja, o servidor de autorização deve emitir tokens de acesso certificados, conforme definido na Seção 3 da RFC 8705.

Part 2: 5.2.3. Cliente confidencial, 2.

Deve incluir os parâmetros request ou request_uri conforme definido na Seção 6 do OIDC na solicitação de autenticação;

Conforme listado na lista de requisitos para servidores de autorização, o parâmetro request ou request_uri deve ser incluido. Observe que o OIDC Core diz “Se um desses parâmetros for usado, o outro NÃO DEVE ser usado na mesma solicitação”.

Part 2: 5.2.3. Cliente confidencial, 3.

deve garantir que o servidor de autorização autenticou o usuário em um nível de garantia apropriado para a finalidade pretendida do cliente;

Este requisito afirma apenas que o usuário deve ser autenticado de forma adequada. A versão final da FAPI removeu o requisito “ao solicitar a declaração acr ccomo uma declaração essencial” que existia na cláusula.

HISTÓRIA:

No ID2, este requisito era “deve solicitar a autenticação do usuário na LoA 3 ou superior, solicitando o acr como uma declaração essencial conforme definido na seção 5.5.1.1 do [OIDC]; ”.

Quando um cliente deseja exigir declarações como essenciais, o parâmetro acr_values não pode ser usado. Ao invés disso, o cliente deve usar nos parâmetros da requisição o claims, passando o valor JSON e incluindo a declaração a seguir no JSON {“essential”:true}. A seguir está um exemplo de JSON que precisa ser fornecido como o valor do claims a fim de marcar urn:mace:incommon:iap:silver como uma ACR essencial.


Claims for Essential ACR

Em paralelo, este requisito foi afrouxado em UK Open Banking que se baseia na FAPI Parte 2. Ou seja, os clientes não precisam exigir ACRs como essenciais. Provavelmente, não é intencional. Eu acho que o instantâneo da especificação FAPI que foi referido quando o Perfil de Open Banking (OBP) foi desenvolvido não continha a frase, “solicitando a declaração acr como uma declaração essencial”.

O conjunto de testes de conformidade oficial do FAPI (Financial-grade API) (conformance-suite) é desenvolvido e mantido pela FinTechLabs.io e contém os casos de teste para OBP. Quando FinTechLabs executou os casos de teste OBP usando a solução da Authlete para testar a própria ferramenta de conformidade, eles encontraram um erro. Porque a Authlete segue fielmente a especificação FAPI, a Authlete reportou a “declaração acr como não obrigatório, mas como essencial. ” No entanto, o comportamento esperado no contexto do OBP é ignorar o requisito FAPI.

A abordagem certa para o erro foi corrigir o OBP (para tornar o OBP compatível com a especificação FAPI mais recente). No entanto, recebi uma explicação como “se o conjunto de testes de conformidade oficial fizesse isso, todas as implementações de OBP existentes não seriam capazes de passar nos testes oficiais. Alterar os testes neste momento pode causar atrasos no cronograma oficialmente anunciado do Open Banking. ”

Portanto, decidi ajustar o Authlete e adicionei a opção OPEN_BANKING além da opção FAPI.

Supported Service Profiles (in Service Owner Console provided by Authlete)

Se OPEN_BANKING estiver ativado, Authlete não se atreve a verificar se a declaração acr é necessária como essencial, mesmo no contexto da FAPI Parte 2. O trecho de código abaixo é a implementação real extraída do código-fonte da Authlete.

Code to judge whether acr should be required as an essential claim

Como resultado disso, a Authlete é listada como um fornecedor de plataforma que passou nos testes “Open Banking Security Profile Conformance”.

Authlete listed in Open Banking Security Profile Conformance

~Fim da história

No entanto, mais uma vez, a FAPI Final removeu o requisito “ao solicitar a declaração acr como uma declaração essencial”, de modo que a Authlete não verifica mais se os ACRs são solicitados como essenciais. Portanto, o sinalizador OPEN_BANKING não é mais significativo.

Part 2: 5.2.3. Cliente confidencial, 4.

(movido para 5.2.3.1);

Part 2: 5.2.3. Cliente confidencial, 5.

(retirado);

Part 2: 5.2.3. Cliente confidencial, 6.

(retirado);

Part 2: 5.2.3. Cliente confidencial, 7.

(movido para 5.2.3.1);

Part 2: 5.2.3. Cliente confidencial, 8.

deve enviar todos os parâmetros dentro do objeto de solicitação assinado do pedido de autorização

Part 2: 5.2.3. Cliente confidencial, 9.

deve, adicionalmente, enviar cópias dos parâmetros response_type, client_id, e scope usando a sintaxe de solicitação OAuth 2.0 conforme exigido pela Seção 6.1 da especificação OpenID Connect se não estiver usando PAR;

Se os parâmetros de solicitação forem colocados em um objeto de solicitação, o parâmetro request ou o request_uri é suficiente. No entanto, se os parâmetros que são obrigatórios no OAuth 2.0 / OIDC Core (e.g. client_id e response_type) são omitidos, a solicitação não é mais compatível com OAuth 2.0 / OIDC Core. Portanto, os parâmetros obrigatórios no OAuth 2.0 / OIDC Core devem ser colocados fora do objeto de solicitação de forma duplicada, mesmo que existam dentro do objeto de solicitação.

A versão FAPI Final adicionou uma condição “se não estiver usando PAR”. Isso significa que o conjunto de parâmetros de solicitação não precisa ser compatível com OAuth 2.0 / OIDC quando PAR é usado. Essa incompatibilidade vem do JWT Secured Authorization Request (JAR). Verifique “Implementer’s note about JAR (JWT Secured Authorization Request)” para mais detalhes.


response_type requirement in OAuth 2.0, OIDC and JAR

Part 2: 5.2.3. Cliente confidencial, 10.

deve enviar a declaração aud no objeto da solicitação como o URL do identificador do emissor do OP;

Part 2: 5.2.3. Cliente confidencial, 11.

deve enviar a delcaração exp no objeto de solicitação que tem uma vida útil não superior a 60 minutos;

Os mesmos requisitos podem ser encontrados na Seção 5.2.2. Servidor de autorização.

Part 2: 5.2.3. Cliente confidencial, 12.

(movido para 5.2.3.1);

Part 2: 5.2.3. Cliente confidencial, 13.

(movido para 5.2.3.1);

Part 2: 5.2.3. Cliente confidencial, 14.

deve enviar a declaração nbf no objeto da request;

O mesmo requisito pode ser encontrado na Seção 5.2.2. Servidor de autorização.

Part 2: 5.2.3. Cliente confidencial, 15.

deve usar RFC7636 com S256 como o método de desafio se estiver usando PAR; e

Ou seja, uma solicitação de autorização deve incluir code_challenge_method=S256 parâmetro de solicitação quando PAR é usado.

Part 2: 5.2.3. Cliente confidencial, 16.

deverá, além disso, envie uma cópia do client_id (parâmetro e valor) usando a sintaxe de solicitação OAuth 2.0 para o endpoint de autorização, conforme exigido pela Seção 5 do JAR, se estiver usando PAR.

A especificação PAR requer que os servidores de autorização manipulem objetos de solicitação com base nas regras definidas no JAR. A especificação JAR tornou o parâmetro da requisição response_type como opcional, mas client_id continua obrigatório. Verifique “Implementer’s note about JAR (JWT Secured Authorization Request)” para mais detalhes.

Part 2: 5.2.3.1. ID Token como assinatura segregada

Adicionalmente, se no response_type o valor code id_token é usado, o cliente

Seção 5.2.3.1. lista os requisitos para aplicativos cliente que são aplicados quando um ID Token é usado como uma assinatura separada.

Part 2: 5.2.3.1. ID Token como assinatura segregada, 1.

deve incluir o valor openid dentro do parâmetro scope para afirmar o suporte ao OIDC;

Este não é um requisito específico da FAPI. O OIDC Core requer que uma solicitação OIDC inclua openid no parâmetro scope. Veja a explicação sobre o parâmetro scope escrito em Seção 3.1.2.1. Authentication Request do OIDC Core para detalhes.

Part 2: 5.2.3.1. ID Token como assinatura segregada, 2.

exigirá que o ID Token assinado pelo JWS seja retornado dos endpoints;

Nada de novo do ponto de vista do OIDC. Por definição, os tokens de ID são sempre assinados. E quando response_type é code id_token e o scope contém openid, o terminal de autorização e o terminal de token retornam um token de ID. Ver “Diagrams of All The OpenID Connect Flows” para obter detalhes sobre o que os endpoints retornam.

Part 2: 5.2.3.1. ID Token como assinatura segregada, 3.

deve verificar se a resposta de autorização não foi adulterada usando o token de identificação como a assinatura separada;

Ou seja, os aplicativos cliente precisam calcular os valores de hash dos parâmetros de resposta fora do token de ID emitido e comparar os valores aos valores de hash no token de ID.

Part 2: 5.2.3.1. ID Token como assinatura segregada, 4.

deve verificar se o valor do s_hash é igual ao valor calculado a partir do valor do state na resposta de autorização, além de todos os requisitos em 3.3.2.12 do OIDC; e

NOTA: Isso permite que o cliente verifique se a resposta de autorização não foi adulterada, usando o ID Tokencomo uma assinatura separada.

Este requisito menciona particularmente o parâmetro state e a declaração s_hash no ID token embora sejam apenas um dos pares de parâmetro / hash que devem ser considerados.

Part 2: 5.2.3.1. ID Token como assinatura segregada, 5.

deve suportar ID Tokens assinados, e, assinados e criptografados.

Por definição, os ID Token são sempre assinados. Quando os ID Token são criptografados, a ordem de assinatura e criptografia é “assinar e criptografar”. Como resultado, um ID Token criptografado assume a forma de “JWT aninhado” conforme ilustrado abaixo.


Nested JWT (JWS in JWE pattern)

Verifique “Understanding ID Token” para obter detalhes sobre a estrutura dos ID Token.

Part 2: 5.2.3.2. JARM

Adicionalmente, se o valor do response_type for code usado em conjunto com o valor response_mode como jwt, o cliente

Part 2: 5.2.3.2. JARM, 1.

deverá verificar as respostas de autorização conforme especificado no JARM, Seção 4.4.

Verifique “Section 4.4. Processing rules” do JARM para obter detalhes sobre as etapas de verificação.

Part 2: 5.2.4.

(retirado)

Part 2: 5.2.5.

(retirado)

Part 2: 6.2.1. Pré-requisitos de recursos protegidos, 1.

deve apoiar as disposições especificadas na cláusula 6.2.1 Financial-grade API Security Profile 1.0 – Part 1: Baseline; e

Part 2: 6.2.1. Pré-requisitos de recursos protegidos, 2.

devem cumprir os requisitos do MTLS.

Part 2: 6.2.2. Pré-requisitos do cliente

O cliente que apoia este documento deve apoiar as disposições especificadas na cláusula 6.2.2 of Financial-grade API Security Profile 1.0 – Part 1: Baseline.

Basta colocar, Seção 6 da Part 2 afirma que os endpoints de recursos protegidos e os aplicativos clientes devem usar tokens de acesso vinculados a certificados e seguir os requisitos da Part 1.

Part 2: 7. (retirado)

Sétima seção do ID2 era “Solicitar endpoint do objeto”. No entanto, a seção foi removida pela Final Version da FAPI porque foi substituída por “endpoint de solicitação de autorização por push” definido em “Solicitações de autorização por push do OAuth 2.0” (PAR). Ver “Illustrated PAR: OAuth 2.0 Pushed Authorization Requests” para verificar o PAR.

Part 2: Considerações de Segurança

“8. Security considerations” da “Part 2” suas considerações de segurança. O resumo é o seguinte.

8.1 — Esta especificação faz referência a considerações de segurança na seção 10 do RFC 6749 e RFC 6819.

8.2 — Os endpoints de recursos protegidos devem aceitar apenas tokens de acesso vinculados a certificados.

8.3.1 — Os clientes devem usar uma URI de redirecionamento diferente por servidor de autorização.

8.3.2 — Os códigos de autorização e os segredos do cliente são passados para os invasores se os desenvolvedores forem enganados e usarem um endpoint de token falso.

8.3.3 — O fluxo híbrido ou JARM pode ser usado como uma contramedida para o ataque de confusão do IdP (provedor de identidade).

8.3.4 — (removido)

8.3.5 — Como um token de acesso está vinculado a um certificado X.509, os tokens de acesso roubados não podem ser usados sem os certificados correspondentes.

8.4.1 — O RFC 6749 não garante a integridade da mensagem de solicitação e resposta de autorização.

8.4.2 — Usar objetos de solicitação evita o ataque de injeção de parâmetro de solicitação de autorização.

8.4.3 — O uso de fluxo híbrido ou JARM impede o ataque de injeção de parâmetro de resposta de autorização.

8.5 — Os conjuntos de criptografia para TLS 1.2 são restritos.

“8.5. TLS considerations” da “Part 2” permite apenas os seguintes conjuntos de criptografia para comunicação TLS quando a versão TLS em uso está abaixo de 1.3.

  1. TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  2. TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  3. TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  4. TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Mas, do ponto de vista da interoperabilidade dos navegadores da web, suítes de criptografia adicionais, permitida na última BCP 195, são permitidos também para os endpoints de autorização.

… Porque eu, pessoalmente, não consegui encontrar bons motivos para excluir os seguintes conjuntos de criptografia,

  1. TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  2. TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Eu criei o Issue 216 (TLS_ECDHE_ECDSA métodos de criptografia) para sugerir adicioná-los à lista de conjuntos de criptografia permitidos. 1 ano e 4 meses depois, o problema foi encerrado com o motivo de a FAPI agora permitir o TLS 1.3.

8.6 — PS256 e ES256 são permitidos apenas para o algoritmo de assinatura JWS.

Os algoritmos de assinatura do JWS estão listados em “3.1. “alg” (Algorithm) Header Parameter Values for JWS” da RFC 7518 (Algoritmos JSON Web). Entre os 13 algoritmos, “8.6. Algorithm considerations” do “Part 2” permite apenas o PS256 e ES256. A seção afirma explicitamente que RSASSA-PKCS1-v1_5 (e.g. RS256) não deve ser usado e none também não deve ser usado.

JWS algorithms permitted by Financial-grade API, Part 2

Informação: JWT é usado nos seguintes locais em uma implementação de servidor de autorização.


JWT Usage in Authorization Server Implementation

8.6.1 — RSA1_5 o algoritmo de criptografia não deve ser usado.

Este requisito sobre algoritmos de criptografia foi adicionado pela versão FAPI Final. FAPI Part 2 proíbe RSA1_5. O identificador do algoritmo é definido em “4.1. “alg” (Algorithm) Header Parameter Values for JWE” do RFC 7518 (Algoritmo JSON Web). O identificador representa RSAES-PKCS1-v1_5.

8.7 — Use implementações FAPI certificadas.

8.8 — Não permita ações privilegiadas sem um token de acesso.

8.9 — As chaves para verificação de assinatura devem ser acessíveis através dos metadados do jwks_uri ou jwks (cf. RFC 7591) e dos metadados do servidor jwks_uri (cf. RFC 8414).

8.10 — O comprometimento de qualquer cliente que compartilhe a mesma chave com outros clientes resultaria no comprometimento de todos os clientes.

8.11 —Os conjuntos JWK não devem conter várias chaves com o mesmo kid, mas outros atributos-chave podem ser usados para selecionar um entre vários candidatos-chave.

Implementação do FAPI

Este capítulo pega alguns tópicos relacionados à implementação da FAPI.

Baseline ou Advanced?

Quando um aplicativo cliente solicita um token de acesso e acessa APIs com o token de acesso, qual perfil de segurança deve ser aplicado, FAPI Part 1 ou FAPI Part 2, ou nenhum deles?

Algumas implementações podem se configurar estaticamente e outras podem tomar a decisão dinamicamente em tempo de execução. A especificação FAPI não menciona nada sobre como determinar qual perfil de segurança deve ser aplicado.

Uma abordagem simples seria “Considere todas as solicitações de autorização como solicitações FAPI Part 2”. Na verdade, o UK Open Banking adotou essa abordagem. Uma implementação embutida em código como esta pode ser aceitável se o desenvolvimento do sistema for um trabalho único.

No entanto, essa abordagem não é apropriada para uma implementação de servidor de autorização genérica. É porque uma implementação codificada dificulta muito a flexibilidade do design do sistema. Portanto, em uma implementação genérica, é melhor julgar dinamicamente no tempo de execução se uma solicitação de autorização é para FAPI Part 1 ou FAPI Part 2 (ou para OAuth 2.0 / OIDC normal).

Se sim, como julgar dinamicamente? A conclusão a que todos chegarão depois de pensar será apenas uma. Ele é julgado pela verificação dos escopos solicitados.

(Nota: Outra forma possível seria utilizar o parâmetro da requsição resource definida em “RFC 8707 Resource Indicators for OAuth 2.0”.)

Por exemplo, (1) preparar escopos chamados read e write, (2) adotar uma regra onde o escopo read requer que os requisitos da Part 1 da FAPI sejam satisfeitos e o escopo write requer que os requisitos da Parte 2 da FAPI sejam satisfeitos e (3) implemente APIs para que interpretem os escopos de acordo. Se as APIs forem implementadas desta forma, a implementação de um endpoint de autorização pode alterar seu comportamento dinamicamente (a) aplicando os requisitos da Parte 2 da FAPI quando o parâmetro scope na requisição dentro do escopo write, (b) aplicando os requisitos da Part 1 da FAPI quando o parâmetro da requisição scope não inclui o escopo do write mas inclui o escopo do read, e (c) aplicando os requisitos OAuth 2.0 e OIDC quando o parâmetro scope não inclui nem o escopo read nem o escopo write.

Como implementar o switch baseado em escopo? Por exemplo, uma abordagem pode ser considerar escopos cujo nome começa com read como escopos para FAPI Part 1. No entanto, essa abordagem impõe fortes restrições aos nomes de escopo. Se for esse o caso, que abordagem Authlete adotou?

Como primeira etapa, Authlete implementou um mecanismo genérico para definir atributos arbitrários para cada escopo. No mecanismo, Authlete trata o nome do atributo fapi de uma forma específica. Um atributo com o nome fapi e valor r representa Read-Only (Apenas leitura) (= Baseline). Da mesma forma, um atributo com nome fapi e o valor rw representa Read-and-Write (leitura e escrita) (Advanced).

O console da web para Authlete compatível com FAPI (versão 2.0+) fornece IU para atributos de escopo. A captura de tela abaixo define um escopo chamado read com o atributo fapi=r.


Scope Settings for FAPI Read-Only

Authlete’s /auth/authorization API que analisa uma solicitação de autorização, verifica os escopos listados no parâmetro scope na solicitação de autorização e considera a solicitação como uma solicitação para FAPI Part 2 se a lista de escopo inclui um escopo que tem um atributo de fapi=rw. Se a lista de escopos não inclui nenhum escopo com um atributo de fapi=rw mas inclui um escopo com um atributo de fapi=r, a solicitação de autorização é considerada uma solicitação para FAPI Part 1. Em outros casos, a solicitação de autorização é tratada como uma solicitação OAuth 2.0 / OIDC.

NOTA: No ID2, os nomes da FAPI Part 1 e Part 2 eram “Perfil de segurança somente leitura” e “Perfil de segurança de leitura e gravação”. A versão final do FAPI os renomeou para “Perfil de segurança de linha de base (Baseline)” e “Perfil de segurança avançado (Advanced)”. Os valores de r e rw para o atributo fapi foram determinados com base nos nomes antigos.

TLS Mútuo

“Mutual TLS” tem três significados conforme listado abaixo (conforme já explicado anteriormente).

  1. Comunicação TLS usando um certificado de cliente
  2. Autenticação de cliente usando um certificado de cliente
  3. Vinculação de certificado

A primeira parte é tratada por soluções de gerenciamento de API. Por outro lado, a segunda e a terceira partes não precisam necessariamente ser tratadas pela camada de gerenciamento de API. Em vez disso, uma arquitetura de sistema melhor os trataria em uma camada diferente, independente da camada de gerenciamento de API.

Por causa de sua arquitetura única, Authlete não assume nenhuma tarefa na camada de gerenciamento de API. Ou seja, Authlete não faz nada para a primeira parte. Por outro lado, Authlete suporta a segunda e a terceira partes. Graças a isso, com Authlete, os sistemas podem suportar MTLS (RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens) exigido pela FAPI em qualquer solução de gerenciamento de API que os desenvolvedores desejam usar. Na verdade, tentei MTLS no Amazon API Gateway e escrevi um artigo intitulado “Financial-grade Amazon API Gateway” para explicar como consegui-lo.

Example of Component Deployment for MTLS on Amazon API Gateway

Qualquer solução de gerenciamento de API pode suportar MTLS usando Authlete, desde que a solução forneça um mecanismo que permita aos desenvolvedores acessar o certificado de cliente usado na comunicação TLS.

As soluções de gerenciamento de API existentes podem tentar implementar o MTLS diretamente. No entanto, levaria tempo e, acima de tudo, não é um bom design de sistema oferecer suporte à funcionalidade diretamente na camada de gerenciamento de API. No momento em que este artigo foi escrito, se você usar uma solução de gerenciamento de API fornecida por um dos fornecedores de nuvem gigantes, o Authlete é a melhor resposta para MTLS.

O video abaixo é uma sessão da “Financial APIs Workshop” que aconteceu em Tóquio em 24 de julho de 2018. No vídeo, Justin Richer,um dos engenheiros de software mais famosos da comunidade e autor de “OAuth 2 in Action”, está explicando a implementação de MTLS da Authlete.

O material e a transcrição da apresentação estão disponíveis em “Authlete FAPI Enhancements”.

Duração do Access Token

Isso não está relacionado ao FAPI, mas eu explico esse recurso aqui porque sou frequentemente consultado sobre o recurso no contexto da API do Banco por clientes que desejam tornar a duração dos tokens de acesso para remessas mais curta do que a dos tokens de acesso para outros fins.

A funcionalidade pode ser obtida diminuindo a duração do token de acesso quando uma solicitação de autorização contém um escopo para remessa. Por exemplo, se uma API para remessa requer um escopo denominado remit, o servidor de autorização encurta a duração do token de acesso quando uma solicitação de autorização contém o escopo.

Authlete suporta a funcionalidade tratando um atributo de escopo denominado access_token.duration de uma forma específica.

O Authlete verifica todos os atributos de escopo dos escopos solicitados, pega o menor valor entre os valores dos atributos access_token.duration, e o usa como a duração de um token de acesso que está sendo emitido. Se nenhum dos escopos solicitados tiver um atributo access_token.duration, Authlete usa o valor padrão de duração do token de acesso definido por instância do servidor de autorização. Se o valor padrão for menor que o menor valor do atributo access_token.duration, o valor padrão é usado.

A tela abaixo mostra como definir access_token.duration=300 como atributo do escopo.


Scope Settings for Access Token Duration

Da mesma forma, a duração dos tokens de atualização pode ser definida utilizando o atributo refresh_token.duration.

NOTA: Authlete 2.1 e versões mais recentes suportam “duração do token de acesso por cliente”. Verifique em “How Authlete determines token duration” no Authlete Knowledge Base para mais detalhes.

Token de Acesso com Informações de Transação

Esse recurso também não está relacionado ao FAPI, mas eu o explico aqui, pois sou frequentemente consultado sobre ele no contexto da API do Banco por clientes que desejam associar informações detalhadas da transação a um token de acesso. Ouvi dizer que alguns regulamentos na Europa exigem que um token de acesso seja emitido por transação sob algumas condições.

Esta funcionalidade não pode ser alcançada pelo “atributo de escopo” que foi explicado em “Duração do token de acesso” porque a funcionalidade requer que os dados sejam tratados por token de acesso, não por escopo.

Desde os velhos tempos, Authlete fornece um mecanismo para definir pares de valores-chave arbitrários para um token de acesso. Este recurso pode ser utilizado para associar informações de transação a um token de acesso. Os detalhes técnicos sobre este recurso são explicados em “Extra Properties”. Veja também “How to add extra properties to an access token” em Authlete Knowledge Base.

No entanto, observe que não é uma maneira inteligente de associar informações detalhadas, como quantidade de dinheiro, a um token de acesso diretamente. Em vez disso, uma maneira recomendada é (1) armazenar informações detalhadas da transação em outro banco de dados e (2) associar o identificador exclusivo do registro do banco de dados a um token de acesso.

Detalhes de Autorização

Desde a versão 2.2, Authlete suporta “OAuth 2.0 Rich Authorization Requests” (RAR). A especificação padrão adiciona um parâmetro de solicitação / resposta, authorization_details.

O parâmetro authorization_details é usado para permitir que um token de acesso mantenha informações detalhadas sobre a autorização. Por exemplo, informações detalhadas sobre o pagamento, como “Quanto?”, “Para quem?”, Etc.

De acordo com a especificação, o parâmetro authorization_details pode ser usado em qualquer lugar do scope. Por exemplo, (a) na solicitação de autorização, (b) na resposta do token, (c) na resposta de introspecção e assim por diante.


(a) authorization_details in Authorization Request (RAR Section 3)


(b) authorization_details in Token Response (RAR Section 7)


(c) authorization_details in Introspection Response (RAR Section 8.2)

RAR é um padrão aberto para descrever detalhes sobre autorização e vincular as informações a um token de acesso. RAR deve ser adotado como um componente do FAPI 2.0 (cf. “Existem implementações FAPI 2.0?” verifique FAPI FAQ).

Authlete’s Propriedades Extra pode ser usado para o mesmo propósito. Uma diferença funcional é que as propriedades extras podem escolher expor ou ocultar propriedades extras. Propriedades extras ocultas nunca aparecem em nenhuma resposta OAuth / OIDC, mas podem ser recuperadas pela API de introspecção do Authlete (/auth/introspection API). Existem alguns casos de uso em que você deseja vincular as informações a um token de acesso, mas ocultar as informações do aplicativo cliente e do usuário. Nesses casos, Propriedades extras são úteis.

Finalmente

Obrigado por ler este longo post até o fim.

Authlete já suporta a versão final FAPI 1.0 e especificações técnicas conhecidas de FAPI 2.0 conforme mencionado em FAPI FAQ. Você pode experimentar o FAPI por meio Authlete API Tutorials com uma conta Authlete (signup).

Takahiko Kawasaki
Co-founder and representative director of Authlete, Inc.
https://www.authlete.com/

Artigo Original