Table of Contents
Grant Management for OAuth 2.0 é uma especificação técnica que permite gerenciar privilégios concedidos a aplicativos clientes de uma forma mais refinada do que especificações padrão pré-existentes.
Um motivo para prestar atenção à especificação é que ela está posicionada como parte da API 2.0 de grau financeiro, a sucessora da API 1.0 de grau financeiro que agora é o padrão de fato para alta segurança de API e foi adotado por ecossistemas como [UK Open Banking] (https://www.openbanking.org.uk/), [Australian Consumer Data Right](https://www.cdr.gov .au /) e Open Banking Brasil. A gestão de subvenções também é mencionada no white paper de GAIN (Global Assured Identity Network), que é um projeto para construir uma rede global de identidade digital de alta confiança na Internet.
Este artigo explica a especificação com base no primeiro projeto do implementador, lançado em setembro de 2021 ([anúncio](https://openid.net/2021/09/21/implementers-draft-of-fapi-grant-management-approved / “Minuta do Implementador de Gestão de Subsídios FAPI aprovada”)). No entanto, como acontece com outros, o primeiro rascunho não é perfeito. Algumas definições técnicas que os implementadores precisarão mais cedo ou mais tarde estão faltando e há espaço para diferentes interpretações. Mas, considerando que o objetivo do primeiro rascunho é incentivar os implementadores a começarem a trabalhar, é bastante natural.
Além da explicação sobre a especificação em si, este artigo também descreve como Authlete interpreta e implementa a especificação, esperando receber feedback de um implementador para aperfeiçoar a especificação.
No OAuth 2.0, um usuário concede alguns privilégios a um aplicativo cliente. Como resultado, um token de acesso é emitido de um servidor de autorização para o aplicativo cliente.
O processo de emissão do token de acesso pode ser repetido. Os privilégios solicitados pelo aplicativo cliente no segundo e nos processos subsequentes podem ser diferentes daqueles solicitados no primeiro processo. Dessa forma, os privilégios concedidos ao aplicativo cliente se acumulam.
A especificação Grant Management chama o conjunto de privilégios acumulados “grant” e define os meios pelos quais consultar, atualizar e revogar uma concessão.
Uma grant ID é atribuída a cada concessão para torná-la administrável. Um ID de concessão é emitido junto com um token de acesso do terminal do token. Para solicitar a um servidor de autorização para emitir um ID de concessão, um aplicativo cliente inclui um novo parâmetro de solicitação de autorização grant_management_action em uma solicitação de autorização com um valor create. O ID de concessão emitido é incluído na resposta do token como o valor de um novo parâmetro de resposta do token grant_id.
Para acumular privilégios, o aplicativo cliente inclui grant_management_action=merge na próxima solicitação de autorização com um novo parâmetro de solicitação de autorização grant_id cujo valor é um ID de concessão emitido anteriormente.
Além de create e merge, replace é definido como um valor para o parâmetro de solicitação grant_management_action. A ação replace substitui os privilégios acumulados vinculados ao ID de concessão especificado por novos que são concedidos apenas por meio da solicitação, incluindo grant_management_action=replace. Os privilégios anteriores são revogados.
Quando o valor do parâmetro de solicitação grant_management_action é merge ou replace, o parâmetro de solicitação grant_id é obrigatório.
Em relação aos parâmetros de solicitação grant_management_action e grant_id, a especificação afirma o seguinte.
Esses parâmetros podem ser usados com qualquer solicitação servindo como solicitação de autorização, por exemplo, pode ser usado com solicitações da CIBA.
Para ser concreto, a especificação CIBA Core / Section 7 espera que o ponto de extremidade de autenticação de backchannel reconheça os parâmetros de solicitação.
A especificação Grant Management define um novo ponto de extremidade denominado “ponto de extremidade de gerenciamento de concessão”. O endpoint permite consultar e revogar uma concessão. Para acessar o terminal, um token de acesso pré-emitido é necessário.
| QUERY | ||
|---|---|---|
| Request | HTTP Method | GET |
| URL | {endpoint}/{grant-id} |
|
| Protection | Acccess token having the grant_management_query scope |
|
| Response | Status Code | 200 OK |
| Content-Type | application/json |
|
| Format | See “6.4. Query Status of a Grant”. |
A seguir está um exemplo de resposta extraído de “[6.4. Status de consulta de uma concessão] (https://openid.net/specs/fapi-grant-management.html#name-query-status-of-a-grant)" da especificação do Grant Management.
O JSON no corpo da resposta mostra os privilégios acumulados de uma concessão. Ele tem "escopos", "afirmações" e "authority_details" como propriedades de nível superior.
O valor de "scopes" é um array de combinações de escopos e recursos (doravante referidos como “clusters de escopo-recurso”). Cada cluster consiste em "scope" e "resource". O valor de "scope" é um escopo delimitado por espaço. O valor de "resource" é um array de recursos. Os valores dos escopos e recursos são aqueles especificados pelo parâmetro de solicitação scope ([RFC 6749] (https://www.rfc-editor.org/rfc/rfc6749.html) / [Seção 3.3] (https: // www.rfc-editor.org/rfc/rfc6749.html#section-3.3)) e parâmetros de solicitação resource ([RFC 8707] (https://www.rfc-editor.org/rfc/rfc8707.html) / [Seção 2] (https://www.rfc-editor.org/rfc/rfc8707.html#name-resource-parameter)).
A estrutura de "scopes" faz com que os implementadores percebam que os clusters de recursos de escopo devem ser gerenciados separadamente, mesmo se os privilégios forem acumulados por meio de operações de atualização repetidas. Se o conteúdo dos clusters foi misturado por meio de operações merge, os escopos podem ser acoplados a recursos não intencionais. O JSON inferior direito na figura abaixo indica que o escopo change é combinado com o recursohttps://payment.example.com se o conteúdo dos clusters for misturado, o que pode causar um grave incidente de segurança, como roubo de dinheiro.
O valor de "claims" é uma matriz de “afirmações” que o usuário consentiu que o aplicativo cliente conhecesse. Simplificando, “reivindicações” aqui são atributos do usuário. Alguns atributos do usuário, como family_name e phone_number são definidos como declarações padrão na Seção 5.1 do OpenID Connect Core 1.0.
Um aplicativo cliente pode solicitar declarações incluindo escopos especiais (profile, email, address e phone) no parâmetro de solicitação scope ([OIDC Core] (https://openid.net/specs/openid-connect-core-1_0.html) / [Seção 5.4] (https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims)) e / ou usando o parâmetro de solicitação Claims ([OIDC Core] (https://openid.net/specs/openid-connect-core-1_0.html) / [Seção 5.5] (https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter)).
O valor de " authority_details " é um array de informações detalhadas sobre autorização. As informações são aquelas especificadas pelo parâmetro de solicitação Authorization_details que é definido em” [OAuth 2.0 Rich Authorization Requests] (https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/) “(RAR).
Antes do RAR ser desenvolvido, as implementações do servidor de autorização tinham que introduzir um parâmetro de solicitação não padrão ou usar o parâmetro de solicitação scope de uma forma não padronizada para anexar informações detalhadas a uma solicitação de autorização. A última abordagem é chamada de “escopo parametrizado” ou “escopo dinâmico”, que incorpora um valor dinâmico em uma string de escopo. Por exemplo, [Open Banking Brasil Financial-grade API Security Profile 1.0] (https://openbanking-brasil.github.io/specs-seguranca/open-banking-brasil-financial-api-1_ID3.html) define “Consentimento dinâmico Escopo “([Seção 7.1.2] (https://openbanking-brasil.github.io/specs-seguranca/open-banking-brasil-financial-api-1_ID3.html#name-dynamic-consent-scope-defin) ) cujo formato é consent: {ConsentID} onde consent: é um prefixo de string fixo e {ConsentID} é a parte dinâmica (por exemplo, consent: urn: bancoex: C1DD33123).
O problema da abordagem de escopo dinâmico é que ela não é padronizada e a interoperabilidade entre as implementações é impossível devido aos seus formatos intrinsecamente variantes. O RAR foi desenvolvido para resolver o problema e está posicionado como parte da API 2.0 de grau financeiro.
| REVOKE | ||
|---|---|---|
| Request | HTTP Method | DELETE |
| URL | {endpoint}/{grant-id} |
|
| Protection | Access token having the grant_management_revoke scope |
|
| Response | Status Code | 204 No Content |
A especificação do Grant Management afirma que todos os tokens de atualização associados à concessão revogada devem ser revogados e todos os tokens de acesso associados à concessão revogada devem ser revogados.
A especificação Grant Management adiciona os seguintes metadados de servidor.
| Metadata | Description |
|---|---|
grant_management_actions_supported |
Grant management actions supported by the authorization server. Possible values are create, query replace, revoke and merge. |
grant_management_endpoint |
The URL of the grant management endpoint |
grant_management_action_required |
Boolean flag indicating whether the grant_management_action request parameter is always required. |
Porque “o gerenciamento de concessões é restrito apenas a clientes confidenciais por motivos de segurança” (Seção 5.1) , se o documento de descoberta (OIDC Discovery) inclui "grant_management_action_required": true, isso implica que o endpoint de autorização da autorização servidor rejeita qualquer solicitação de clientes públicos.
As implementações da especificação do Grant Management serão consideravelmente diferentes umas das outras porque os implementadores enfrentarão muitas opções que não têm uma resposta absoluta. A seguir estão exemplos de tais escolhas.
Se o ciclo de vida de um grant é administrado independentemente dos elementos do grant ou depende totalmente deles.
Se o conteúdo de uma concessão pode mudar sem ações explícitas de gerenciamento de concessão (solicitações de autorização com grant_management_action e solicitações de revogação para o endpoint de gerenciamento de concessão) ou nunca muda sem ações explícitas.
Se os privilégios de tokens de acesso e tokens de atualização podem mudar quando o conteúdo de sua concessão associada muda ou se eles nunca mudam após a emissão.
Como os tokens de atualização estão vinculados a uma grant. A vinculação é necessária porque os refresh tokens devem ser revogados quando seu grant associado é revogado.
Se os access tokens são revogados ou não quando um grant associado é revogado. A especificação diz que os tokens de acesso devem ser revogados. Observe que algumas implementações de servidor de autorização não podem revogar tokens de acesso depois de emitidos. (cf. "[Implementação do token de acesso OAuth] (https://darutk.medium.com/oauth-access-token-implementation-30c2e8b90ff0)")
Como os privilégios herdados por grant_management_action = merge são gerenciados. Como um instantâneo no momento da emissão do token de acesso (que nunca muda depois) ou como um link para outra coisa (cujo conteúdo pode mudar mais tarde), ou em outras formas.
Como um servidor de recursos valida um token de acesso que herdou privilégios por meio de grant_management_action = merge. Atualmente, não há formatos padrão acordados de resposta de introspecção e token de acesso JWT para Grant Management, e a discussão é um pouco controversa. (cf. "[FAPI ISSUE 455: Impact of grant_management_action = update on AT deployment and introspection] (https://bitbucket.org/openid/fapi/issues/455)")
Grant Management é apoiado por Authlete 2.3. Como feedback para a comunidade, descrevo o design adotado na implementação do Authlete.
A seguir está o conhecimento prévio sobre a implementação do token de acesso da Authlete, necessário para a leitura das seções subsequentes.
O tipo de implementação de tokens de acesso é “identificador”, não “independente” (normalmente JWT). Ao definir “Access Token Signature Algorithm”, você pode fazer o Authlete emitir tokens de acesso JWT (cf. "[Habilitando tokens de acesso baseados em JWT] (/kb/oauth-and-openid-connect/jwt-based-access-token) “). No entanto, por motivos de privacidade e segurança, os tokens de acesso JWT da Authlete intencionalmente não contêm todos os dados associados a eles e algumas partes dos dados são armazenadas apenas no banco de dados da Authlete sem serem incorporados aos próprios tokens de acesso. Leia "[Vazamento de informações pessoais por meio do token de acesso JWT] (https://darutk.medium.com/leakage-of-personal-information-via-jwt-access-token-c222a3293898)" and "[Acesso OAuth Implementação de token] (https://darutk.medium.com/oauth-access-token-implementation-30c2e8b90ff0)" para obter detalhes.
Quando um token de atualização flui ([RFC 6749] (https://www.rfc-editor.org/rfc/rfc6749.html) / Seção 6) for bem-sucedido, o token de acesso anterior vinculado ao token de atualização usado será revogado mesmo que ainda não tenha expirado.
É configurável se um novo token de atualização é emitido quando um fluxo de token de atualização é bem-sucedido ou um novo não é emitido e o token de atualização usado permanece válido (cf. "[Atualizar tokens após ser usado] (/kb/oauth-and-openid-connect/refreshing-refresh-tokens)”). Quando um novo token de atualização é emitido, o token de atualização usado é revogado mesmo se ainda não tiver expirado.
A relação entre o token de atualização e o token de acesso é individual. Ou seja, o número de tokens de acesso válidos por token de atualização é no máximo um e vice-versa.
Quando um token de atualização é excluído, o token de acesso junto com o token de atualização é excluído. Da mesma forma, quando um token de acesso é excluído, o token de atualização juntamente com o token de acesso são excluídos. Algumas pessoas podem se surpreender com o último comportamento, mas Seção 2.1 de [RFC 7009 OAuth 2.0 Token Introspection](https: //www.rfc-editor.org/rfc/rfc7009.html) afirma explicitamente como segue: “Se o token passado para a solicitação for um token de acesso, o servidor PODE revogar o respectivo token de atualização também.”
Os comportamentos dos tokens de atualização descritos acima podem ser explicados pela decisão de design feita na fase inicial do Authlete: um par de token de acesso e token de atualização é gerenciado em um registro de banco de dados na tabela de tokens de acesso.
Um registro de token de acesso é considerado ativo (não expirado) quando um ou ambos o token de acesso e o token de atualização no registro não expiraram.
Authlete define uma concessão como uma coleção de registros de token de acesso “ativos”. Como resultado, o conteúdo de uma concessão muda quando os registros de token de acesso da concessão expiram. A mudança pode acontecer sem ações explícitas de gerenciamento de concessão (solicitações de autorização com grant_management_action e solicitações de revogação para o endpoint de gerenciamento de concessão) porque a expiração dos registros de token de acesso ocorre independentemente das ações de gerenciamento de concessão.
As implementações do servidor de autorização podem escolher criar uma nova tabela de banco de dados para gerenciar as IDs de concessão, mas Authlete escolheu uma abordagem diferente e simplesmente adicionou uma coluna grant_id à tabela de token de acesso existente. A figura abaixo ilustra que uma concessão consiste em registros de token de acesso ao vivo.
No Authlete, uma resposta de token contém um ID de concessão apenas quando a solicitação de autorização anterior (ou solicitação de autenticação de backchannel ou solicitação de autorização de dispositivo) contém o parâmetro de solicitação grant_management_action embora Seção 5.4 Resposta de Token do primeiro rascunho do implementador diz “O AS retornará um grant_id se suportar qualquer uma das ações de gerenciamento de concessões “.
A descrição na especificação resulta em que ela requer que o servidor de autorização sempre emita um ID de concessão incondicionalmente, uma vez que suporta Gerenciamento de Concessão. No entanto, não faz sentido emitir um ID de concessão para clientes públicos que não têm permissão para usar o gerenciamento de concessão (Seção 5.1). Estou sugerindo alterar a descrição em "[FAPI ISSUE 455: Condition for a token response to include a grant_id] (https://bitbucket.org/openid/fapi/issues/445)"
O Authlete não emite um ID de concessão do endpoint de autorização, mesmo quando um pedido de autorização inclui o parâmetro de solicitação grant_management_action e um token de acesso é emitido do endpoint de autorização porque foi confirmado que os autores da especificação excluíram intencionalmente o caso do especificação. Estou sugerindo mencioná-lo explicitamente na especificação em "[FAPI ISSUE 453: Grant ID from Authorization Endpoint] (https://bitbucket.org/openid/fapi/issues/453)".
Por outro lado, o Authlete inclui um grant ID em uma notificação push CIBA quando uma solicitação de autenticação de backchannel inclui o parâmetro de solicitação grant_management_action e o cliente é configurado para usar o modo CIBA PUSH. No entanto, eu não sugeri registrar o parâmetro grant_id para notificações push CIBA ainda. Em qualquer caso, porque o [Perfil FAPI-CIBA] (https://openid.net/specs/openid-financial-api-ciba.html) proíbe o uso do modo CIBA PUSH, o [FAPI WG] (https://openid.net/wg/fapi/) não mostrará nenhum interesse nisso.
Quando uma solicitação de autorização inclui grant_management_action = merge, o token de acesso recém-emitido herda os privilégios da concessão identificada pelo parâmetro de solicitação grant_id. O Authlete obtém essa herança copiando os privilégios dos registros de token de acesso existentes para a coluna grant do registro de token de acesso recém-inserido.
O conteúdo da coluna grant é um instantâneo dos privilégios que existiam no momento da emissão do token de acesso. O instantâneo não muda mesmo depois que os registros do token de acesso que forneciam os privilégios expiram ou são excluídos.
Os valores dos metadados do servidor relacionados ao Grant Management são determinados conforme a tabela abaixo descreve.
| Metadata | Value |
|---|---|
grant_management_actions_supported |
When the grant management endpoint is set, [create, query, replace, revoke, merge]. Otherwise, [create, replace, merge]. |
grant_management_endpoint |
Configurable at “Grant Management Endpoint” in the web console. |
grant_management_action_required |
Configurable at “Grant Management Action Required” in the web console. |
Um usuário é autenticado (se ainda não estiver) em um processo de autorização. Pode acontecer que o usuário autenticado seja diferente do usuário da concessão especificada pelo parâmetro de solicitação grant_id. A especificação não descreve como o servidor de autorização deve se comportar nesse caso. Eu criei * “[FAPI 452: Quando o usuário que está sendo autenticado é diferente do usuário da concessão] (https://bitbucket.org/openid/fapi/issues/452)" * para discuti-lo, mas a conclusão parece que deve ser deixado para implementações.
Quando o usuário autenticado é diferente do usuário da concessão, Authlete pula silenciosamente as etapas relacionadas ao Gerenciamento da concessão sem gerar nenhum erro.
Por design, Authlete não se envolve na interação entre um servidor de autorização e um usuário. O Authlete não é um servidor de autorização, mas um conjunto de APIs da Web com o qual os desenvolvedores implementam seus servidores de autorização por conta própria. Portanto, a Authlete não sabe como os servidores de autorização desenvolvidos por desenvolvedores obtêm o consentimento de um usuário. Quando escopos especiais (profile, email, address e phone) que são expandidos para conjuntos de declarações são incluídos no parâmetro de solicitação scope, um servidor de autorização pode obter consentimento sobre as reivindicações expandidas uma por uma ou pode omitir a etapa. O Authlete apenas incorpora os dados de reivindicação fornecidos em um token de ID ou uma resposta UserInfo sem saber se as reivindicações foram consentidas pelo usuário ou não.
No entanto, para tornar a propriedade reivindicações em respostas do ponto de extremidade de gerenciamento de concessões significativa, Authlete deve saber o conjunto exato de reivindicações consentidas. Para este propósito, o parâmetro de solicitação consentedClaims foi adicionado às seguintes APIs. (cf. AuthorizationIssueRequest.setConsentedClaims () )
/api/auth/authorization/issue/api/backchannel/authentication/complete/api/device/completeQuando o parâmetro de solicitação é fornecido e seu valor não está vazio, Authlete considera o valor como o conjunto de reivindicações consentidas. Caso contrário, Authlete calcula o conjunto de escopos especiais consentidos (por exemplo, profile) e dados de reivindicação fornecidos (pelo parâmetro de solicitação Claims), embora Authlete saiba a possibilidade de que o conjunto computado pode ser diferente do conjunto real de reivindicações consentidas. Especialmente, o conjunto computado pode não incluir declarações que o servidor de autorização retorna do terminal UserInfo. Portanto, se o conjunto exato de reivindicações consentidas precisa ser controlado, o parâmetro de solicitação consentedClaims deve ser usado.
Authlete compacta o conteúdo de uma resposta de gerenciamento de concessão.
As entradas no array scopes são agrupadas por um conjunto de recursos. As entradas são classificadas pelo conjunto de recursos. Escopos no mesmo conjunto de recursos são mesclados na propriedade scope.
Por exemplo, quando os registros de token de acesso ao vivo de uma concessão têm os seguintes privilégios,
| scope | resource |
|---|---|
"X23 L23" |
["r2", "r3"] |
"X2 K2" |
["r2" ] |
"X3 J3" |
["r3" ] |
"X13 I13" |
["r1", "r3"] |
"X12 H12" |
["r1", "r2"] |
"X1 G1" |
["r1" ] |
"X3 F3" |
["r3" ] |
"X23 E23" |
["r2", "r3"] |
"X13 D13" |
["r1", "r3"] |
"X2 C2" |
["r2" ] |
"X1 B1" |
["r1" ] |
"X12 A12" |
["r1", "r2"] |
a coleção será compactada da seguinte forma.
| scope | resource |
|---|---|
"B1 G1 X1" |
["r1" ] |
"A12 H12 X12" |
["r1", "r2" ] |
"D13 I13 X13" |
["r1", "r3" ] |
"C2 K2 X2" |
["r2" ] |
"E23 L23 X23" |
["r2", "r3" ] |
"F3 J3 X3" |
["r3" ] |
Como resultado, o array scopes na resposta do gerenciamento de concessões será semelhante a abaixo.
{
"scopes": [
{ "scope": "B1 G1 X1", "resource": [ "r1" ] },
{ "scope": "A12 H12 X12", "resource": [ "r1", "r2" ] },
{ "scope": "D13 I13 X13", "resource": [ "r1", "r3" ] },
{ "scope": "C2 K2 X2", "resource": [ "r2" ] },
{ "scope": "E23 L23 X23", "resource": [ "r2", "r3" ] },
{ "scope": "F3 J3 X3", "resource": [ "r3" ] }
]
}
Declarações consentidas de registros de token de acesso ao vivo de uma concessão são coletadas, duplicatas são descartadas, os elementos restantes são classificados e, em seguida, colocados no array declarações.
Por exemplo, quando os registros de token de acesso ao vivo de uma concessão têm as seguintes reivindicações consentidas,
| consented claims |
|---|
[ c3, c5 ] |
[ c1, c3 ] |
[ c2, c4, c5 ] |
a coleção será compactada da seguinte forma.
| consented claims |
|---|
[ c1, c2, c3, c4, c5 ] |
Como resultado, o array Claims na resposta do gerenciamento de concessões será parecido com o mostrado abaixo.
{
"claims": [
"c1", "c2", "c3", "c4", "c5"
]
}
As duplicatas no array authority_details são removidas. O Authlete detecta duplicatas comparando os valores de hash dos elementos da matriz. Espaços e novas linhas em JSON não afetam o resultado da computação de hash. A ordem das chaves em objetos JSON também não afeta o resultado. Os dois seguintes elementos authorisation_details são considerados idênticos.
{
"authorization_details": [
{
"type": "t1",
"actions": [ "a1", "a2" ],
"my_custom_data": {
"key1": "value1",
"key2": "value2"
}
},
{
"my_custom_data": { "key2": "value2", "key1": "value1" },
"actions": [
"a1",
"a2"
],
"type": "t1"
}
]
}
Como mencionado anteriormente, a fim de evitar que os escopos sejam acoplados a recursos não intencionais, as implementações do servidor de autorização não podem ajudar a gerenciar clusters de recursos de escopo separadamente, mesmo se os privilégios forem acumulados por meio de operações merge repetidas.
Um token de acesso herda esses clusters de recursos de escopo por meio da operação merge. Em caso afirmativo, é necessário estender os formatos de resposta de introspecção ([RFC 7662] (https://www.rfc-editor.org/rfc/rfc7662.html)) e token de acesso JWT ([RFC 9068](https: //www.rfc-editor.org/rfc/rfc9068.html)). Isso ocorre porque, de outra forma, os terminais de recursos protegidos não podem validar os tokens de acesso adequadamente.
Para discutir o problema, criei "[FAPI ISSUE 455: Impact of grant_management_action = update on AT deployment and introspection] (https://bitbucket.org/openid/fapi/issues/455)" e escrevi um artigo ” [Complexidade dos privilégios de token de acesso introduzidos pela Grant Management] (https://darutk.medium.com/complexity-of-access-token-privileges-introduced-by-grant-management-ec527b5c6d6a) “ que articula os pontos de discussão.
No entanto, foi muito mais difícil chegar a um consenso do que eu esperava😅. No momento em que este livro foi escrito, não parecia realista para a comunidade chegar a um acordo sobre uma solução para o problema em um curto período.
Felizmente, o Authlete fornece aos desenvolvedores sua própria API de introspecção (/api/auth/introspection), que é diferente do endpoint de introspecção padrão. A API é muito mais útil do que a padrão nos pontos a seguir.
Os desenvolvedores podem fazer a API de introspecção executar validação complexa para vinculação de certificado ([RFC 8705] (https://www.rfc-editor.org/rfc/rfc8705.html)), [DPoP] (https://datatracker.ietf.org/doc/draft-ietf-oauth-dpop/), recursos ([RFC 8707] (https://www.rfc-editor.org/rfc/rfc8707.html)), escopos ([RFC 6749] ( https://www.rfc-editor.org/rfc/rfc6749.html)) e assunto do proprietário do recurso.
Em casos de erro, a API de introspecção prepara uma mensagem de erro em conformidade com a [RFC 6750] (https://www.rfc-editor.org/rfc/rfc6750.html) para que os endpoints de recursos protegidos possam estar em conformidade com a especificação facilmente .
Os desenvolvedores podem vincular pares de valores-chave arbitrários a um token de acesso usando o recurso “Propriedades extras” do Authlete (cf. "[Como adicionar propriedades extras a um token de acesso] (/kb/oauth-and-openid-connect/extra-properties)”). Uma resposta da API de introspecção inclui os pares de valores-chave.
O Authlete aprimorou a API de introspecção para gerenciamento de concessões.
Primeiro, novos parâmetros de resposta, grantId e grant, foram adicionados.
| Parameter | Description |
|---|---|
grantId |
O ID de concessão vinculado ao token de acesso. O parâmetro mantém um valor não nulo se a solicitação de autorização para o token de acesso incluiu grant_management_action. |
grant |
Os privilégios herdados. O parâmetro mantém um valor não nulo se a solicitação de autorização para o token de acesso incluiu grant_management_action = merge. A classe Grant Java representa o formato do valor. |
Em segundo lugar, a API de introspecção agora reconhece um novo parâmetro de solicitação, resources. E, a lógica de validação para escopos e recursos foi reescrita do zero e agora se comporta como a tabela a seguir explica.
| scopes | resources | Behavior |
|---|---|---|
| not given | not given | Não execute nenhuma validação em escopos e recursos. |
| given | not given | Verifique se todos os escopos especificados são cobertos pelo token de acesso. A verificação de inclusão é realizada por cluster de recursos de escopo. Por exemplo, se um token de acesso contém dois clusters que são " scope ":" s1 " e " scope ":" s2 " respectivamente e o valor do parâmetro de solicitação scopes é [ s1, s2 ], a validação falha. Para compatibilidade com versões anteriores, os recursos dos clusters de recursos de escopo não são levados em consideração. |
| not given | given | Verifique se todos os recursos especificados são cobertos pelo token de acesso. A verificação de inclusão é realizada por cluster de recursos de escopo. Por exemplo, se um token de acesso contém dois clusters que são " resource ": [" r1 "] e " resource ": [" r2 "] respectivamente e o valor do parâmetro de solicitação resources é [r1, r2], a validação falha. Os escopos dos clusters de recursos de escopo não são levados em consideração. |
| given | given | Verifique se todos os escopos e recursos especificados são cobertos pelo token de acesso. A verificação de inclusão é realizada por cluster de recursos de escopo. |
Uma nova API, /api/gm, foi adicionada. Os desenvolvedores podem implementar o ponto de extremidade de gerenciamento de concessão usando a API.
A tabela abaixo lista os parâmetros de solicitação da API /api/gm. Veja o JavaDoc do GMRequest </ code > classe para detalhes.
| Parameter | Necessity | Description |
|---|---|---|
gmAction |
REQUIRED | QUERY or REVOKE |
grantId |
REQUIRED | Grant ID |
accessToken |
REQUIRED | Access token |
clientCertificate |
OPTIONAL | [RFC 8705] Certificado de cliente na conexão TLS mútua |
dpop |
OPTIONAL | [DPoP] DPoP proof JWT |
htm |
OPTIONAL | [DPoP] HTTP method (Authlete pode calcular o padrão de gmAction) |
htu |
OPTIONAL | [DPoP] A URL do endpoint (Authlete pode calcular o padrão de Service.grantManagementEndpoint e grantId) |
Grant Management for OAuth 2.0 é compatível com Authlete 2.3. A versão não foi implantada no servidor compartilhado (api.authlete.com) no momento desta escrita. Por favor, [entre em contato] (/contact/) para acesso antecipado ao Authlete 2.3.
November 9, 2021
Responsibility for the wording and content of this article: Takahiko Kawasaki