Política de acesso para tipos de concessão de API

Editar online

A política de acesso pode ser aplicada ao uso orientado por API do OpenID Connect e do OAuth 2.0. Esse uso da API é mais comumente conhecido como o tipo de concessão de credenciais de Senha do Proprietário do Recurso (ROPC), mas também inclui o tipo de concessão baseado em asserção do JWT. Esses tipos de concessão ao contrário do código de autorização e dos tipos de concessão implícita, apresentam uma diferença fundamental na forma como operam. Não existe um agente do usuário do navegador e nenhuma solicitação é feita para o terminal /authorize. Como esse terminal do navegador não é usado, a política de acesso de um aplicativo deve ser avaliada de maneira diferente.

Quando uma política de acesso é aplicada, estes requisitos de negócios fundamentais são abordados:

O usuário autenticou-se suficientemente para acessar esse aplicativo?
O usuário autenticado tem permissão para acessar esse aplicativo?
O contexto do dispositivo ou do cliente que está sendo usado para acessar esse aplicativo é permitido?

Nos fluxos tradicionais do navegador, esses requisitos são aplicados. Se eles não forem atendidos, o navegador solicitará a MFA ou retornará uma página de erro ao usuário que interrompe o acesso. Em um tipo de concessão de API, essas faculdades não estão todas disponíveis. Por isso, os seguintes problemas devem ser abordados.

Recebimento de contexto de um dispositivo cliente.
Retorno de um desafio de MFA, incluindo,
- As APIs que são necessárias para cumprir a MFA.
- Como acessar as APIs.

Os tipos de concessão orientados por API ainda podem retornar um erro, portanto, uma negação é praticamente inalterada.

O tipo de concessão de policyauth

Para aplicar efetivamente uma política de acesso a um fluxo de API somente OAuth 2.0, um novo tipo de concessão foi introduzido. Esse tipo de concessão permite que um cliente apresente algum contexto para a política de acesso antes de qualquer autenticação. Essa capacidade possibilita a implementação de uma experiência do usuário aprimorada. Por exemplo, quando um usuário pressiona um botão de login, antes que seja solicitado que ele insira as credenciais, ele é avaliado de acordo com a política associada. Se elas não satisfazem os requisitos da política, o usuário recebe uma mensagem de erro que indica que não é possível autenticar nem acessar o recurso por causa dos requisitos da política.

Quando o tipo de concessão policyauth é usado, uma destas respostas é retornada.

Uma negação: Um erro que indica que o acesso não pode ser concedido por causa da política.
Um desafio: Um token que pode ser usado para acessar APIs de autenticação é retornado, com uma lista de fatores de autenticação aceitáveis.

Respostas de desafio de MFA de /token

Quando uma política de acesso é aplicada a um fluxo de API OAuth 2.0, um desafio de MFA deve passar a fazer parte do contrato da API. Os métodos tradicionais do OP que executam as etapas de MFA como parte da solicitação para /authorize não são possíveis.

Quando um desafio de MFA é retornado por /token,

O escopo é mfa_challenge e nenhum outro escopo é retornado.
Um token de acesso é emitido.
- O token de acesso tem autorização para acessar as APIs de autenticação necessárias. É importante que esse token de acesso seja usado e não um token de acesso do cliente da API regular. Esse token é usado para rastrear os fatores de autenticação já executados e as ações passadas em toda a concessão.
- O token de acesso retorna active: true das solicitações para /introspect. Quaisquer APIs que protejam um servidor de recursos devem, quando os desafios de MFA estão sendo usados, implementar uma verificação de que o scope retornado de /introspect não é igual a mfa_challenge.
Opcionalmente, uma matriz de fatores que podem ser executados para satisfazer esse desafio allowedFactors é listada.

Apresentando contexto para /token

O cliente da API que executa uma solicitação para /token pode apresentar informações de contexto bem definidas e arbitrárias ao /token a serem usadas na avaliação da política de acesso.

Três partes obrigatórias das informações de contexto devem ser incluídas.

sessionId - Um identificador arbitrário de sessão que é emitido e mantido pelo cliente OAuth.
ipAddress - Como o cliente OAuth é responsável pelas interações com o agente do usuário, o endereço IP do usuário deve ser fornecido explicitamente.
userAgent - Como no caso do endereço IP, o agente do usuário deve ser fornecido explicitamente.

Mais parâmetros podem ser incluídos e as condições de atributo de contexto podem ser criadas nesses valores.

Observação: Se o context parâmetro não for incluído em uma solicitação para /token, a política de acesso não será acionada.

O contexto é fornecido ao /token na forma de JSON codificado em base64. Um exemplo de carga útil JSON para o contexto é:

{
    "sessionId":"MDNjZmQ3NDM2NjFmMDc5NzVmYTJmMT",
    "ipAddress":"129.42.38.10",
    "userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36"
}

As informações de contexto são consideradas confiáveis, pois são apresentadas por um cliente da API que recebeu um conjunto seguro de credenciais do cliente. Esse cliente da API deve assegurar que ele não permite que o contexto seja apresentado arbitrariamente pelo agente do usuário consumidor, que poderá ser usado para contornar os controles de negócios.

O contexto deve ser apresentado sempre que uma política de acesso for invocada em todos os tipos de concessão de API: policyAuth JWT Bearer,,, ROPC e refresh token.

Satisfazendo mfa_challenge

Para satisfazer um desafio de MFA que é retornado pelo terminal /token, APIs de fatores de autenticação podem ser usadas. Essas APIs são usadas para satisfazer os requisitos de primeiro e segundo fator. O token de acesso que é retornado na resposta de mfa_challenge é usado para solicitar o fator apropriado. Depois de uma conclusão bem-sucedida do fator, um JWT é retornado. Esse JWT contém algumas informações importantes.

O grant_id que é derivado do token de acesso que foi usado para solicitar a API de fator. Esse ID mantém a correlação entre as diferentes solicitações para /token.
O factor que foi executado e quaisquer fatores que foram executados anteriormente.

Esse JWT é apresentado ao /token como parte de um fluxo de tipo de concessão jwtBearer. A política de acesso é reavaliada e um token totalmente autorizado ou outro desafio é emitido.

Para receber um JWT de uma verificação de fator, o parâmetro de sequência de consultas returnJwt=true deve ser incluído.

As APIs de autenticação de primeiro fator a seguir suportam essa sinalização:
As APIs de MFA a seguir suportam essa sinalização:
- https://securitypoc.ice.ibmcloud.com/developer/explorer/#!/Email_One-time_Password_2.0/attemptEmailotpVerification_2_0
  A API de verificação temporária também suporta essa sinalização. No entanto, para usar o JWT que é emitido por ela, o mapeamento da solicitação de sujeito deve ser configurado.
- https://securitypoc.ice.ibmcloud.com/developer/explorer/#!/SMS_One-time_Password_2.0/attemptSmsotpVerification_2_0
  A API de verificação temporária também suporta essa sinalização. No entanto, para usar o JWT que é emitido por ela, o mapeamento da solicitação de sujeito deve ser configurado.
- https://securitypoc.ice.ibmcloud.com/developer/explorer/#!/FIDO/assertionResult
  Uma senha de acesso pode ser usada como primeiro ou segundo fator.
- https://securitypoc.ice.ibmcloud.com/developer/explorer/#!/Voice_One-time_Password_2.0/attemptVoiceotpVerification_2_0
  A API de verificação temporária também suporta essa sinalização. No entanto, para usar o JWT que é emitido por ela, o mapeamento da solicitação de sujeito deve ser configurado.
- https://securitypoc.ice.ibmcloud.com/developer/explorer/#!/One-time_Password/attemptOtpVerification_2_0
- https://securitypoc.ice.ibmcloud.com/developer/explorer/#!/Time-based_One-time_Password_2.0/verifyTotpEnrollment_2_0

Nota:

Para APIs de fator temporário, o campo sub do JWT é preenchido com as informações temporárias que são usadas na solicitação. Por exemplo, o e-mail ou o número do telefone em vez de um userId.
Quando returnJwt=true é configurado, as APIs de verificação que geralmente retornam o código de status 204 sem nenhum corpo HTTP, alteram o código de status para um 200. Elas retornam o content-type de application/json e têm uma resposta como:
```
{
    "assertion:"ey..."}
```
Para verificações de fator que já retornam JSON, a propriedade assertion é incluída na resposta.

Aplicando a política de acesso a diferentes tipos de concessão

Ao configurar um aplicativo, existe a opção de decidir se a política de acesso é aplicada a um tipo de concessão específico.

Essa configuração controla se a política de acesso é avaliada em uma solicitação para /token que é baseada no valor do parâmetro grant_type. Essa avaliação aplica-se independentemente de qualquer chamada prévia de /token para uma concessão específica.

Essa configuração pode ser aplicada aos seguintes tipos de concessão:

policyauth: A política de acesso deve estar sempre ativada.
ROPC: A política de acesso poderá ser desativada se o consumo do tipo de concessão de ROPC não suportar a resposta de mfa_challenge.
JWT Bearer: Quando a política de acesso é desativada no tipo de concessão jwt-bearer, uma MFA não pode ser executada por meio do fluxo policyauth. Uma política de acesso não será executada depois que o primeiro fator for executado.
Refresh token: Pode ser aplicado a apenas um subconjunto de solicitações de refresh_token que usam o parâmetro de contexto original_grant_type como condição de atributo de contexto.