Gerenciar a MFA pela API

A MFA usa duas APIs do Access Manager:

O Identity cadastra os métodos e gerencia as configurações de MFA do usuário.
O Auth conclui a segunda etapa de verificação durante a entrada.

Leia Autenticação multifator antes de integrar essas operações.

Operações de adesão da conta

A API do Identity expõe estas operações de autoatendimento:

Operação	Finalidade
`POST /v1/users/{id}/mfa/setup`	Inicia a configuração de `app` ou `email`.
`POST /v1/users/{id}/mfa/verify`	Verifica o código de acesso da configuração.
`POST /v1/users/{id}/mfa/enable`	Habilita o método verificado.
`GET /v1/users/{id}/mfa`	Lê o status atual da MFA e os métodos habilitados.
`PATCH /v1/users/{id}/mfa/preferred`	Seleciona o método habilitado preferencial.
`DELETE /v1/users/{id}/mfa`	Desabilita todos os métodos.
`DELETE /v1/users/{id}/mfa/{mfaType}`	Desabilita um método.
`POST /v1/users/{id}/mfa/recovery-codes`	Gera um novo conjunto de códigos de recuperação. O conjunto anterior deixa de funcionar.

As operações padrão são de autoatendimento. O subject do bearer token precisa corresponder a {id}.

Iniciar a configuração

Envie o método no corpo da requisição:

Request

{
  "mfaType": "app"
}

Este recurso aceita app e email. A configuração do aplicativo autenticador retorna um segredo, uma URL de código QR e códigos de recuperação. A configuração por email retorna códigos de recuperação e envia um código de acesso ao endereço de email salvo do usuário.

Verificar a configuração

Envie o código de acesso da configuração, com 6 a 8 caracteres, e o método. A verificação do aplicativo autenticador também precisa do segredo retornado pela configuração.

Request

{
  "mfaType": "app",
  "passcode": "123456",
  "secret": "setup-secret"
}

Habilitar o método

Depois da verificação, habilite o método com um código de recuperação da resposta de configuração. A habilitação do aplicativo autenticador também precisa do segredo da configuração.

Request

{
  "mfaType": "app",
  "secret": "setup-secret",
  "recoveryCode": "recovery-code"
}

Trate os segredos de configuração e os códigos de recuperação como credenciais. Não os registre em logs nem os armazene no controle de versão.

Desabilitar a MFA ou remover um método

Para desabilitar a MFA, envie o código que a referência Desabilitar MFA descreve. Para remover o aplicativo autenticador ou o método de email, envie um código desse método. Para receber o código por email, chame POST /v1/users/{id}/mfa/disable/challenge. Somente o próprio usuário pode solicitá-lo, e somente quando o método de email está habilitado. O código é válido por 10 minutos e aceita 5 tentativas erradas. Um usuário pode solicitar 3 códigos em 15 minutos.

Operações de administrador

Um administrador gerencia os métodos de outro usuário com mais duas operações. {id} é o usuário de destino. O bearer token precisa da permissão mfa-admin com a ação post para habilitar um método e da ação delete para remover um.

Operação	Finalidade
`POST /v1/users/{id}/mfa/admin/enable`	Habilita `email` para o usuário de destino sem configuração nem verificação. A resposta contém os códigos de recuperação do usuário de destino.
`DELETE /v1/users/{id}/mfa/admin/{mfaType}`	Remove um método (`app`, `email` ou uma adesão legada de `sms`) do usuário de destino. A operação não pede código.

Operações de entrada

O primeiro fator usa Solicitar token de acesso. Quando o usuário tem a MFA habilitada, a operação retorna uma resposta de desafio de MFA em vez de tokens de acesso. A resposta inclui:

mfaRequired: true.
um mfaToken de curta duração.
os métodos habilitados.
o método preferencial.

Cadastrar um método exigido

Quando o usuário não tem nenhum método de MFA e a organização exige um, Solicitar token de acesso responde 401 com o erro AUT-0019 em vez de um desafio de MFA. Verificar login por MFA dá a mesma resposta quando o usuário tem um método, mas não todos os métodos exigidos. O corpo do erro também tem:

mfaToken: um token válido apenas para a adesão.
availableMethods: os métodos que o usuário pode cadastrar, app ou email.

Inicie a configuração com Iniciar adesão à MFA.
Request
{ "mfaToken": "enrollment-mfa-token", "mfaType": "app" }
Para app, a resposta tem um secret e uma url para o aplicativo autenticador. Para email, o Access Manager envia um código ao endereço de email salvo do usuário. A resposta sempre tem um código de recuperação em recoveryCodes. Guarde-o: você não poderá recuperá-lo depois. Uma nova chamada de configuração substitui a configuração anterior.
Confirme o método com Confirmar adesão à MFA. Envie o código de acesso do aplicativo autenticador ou do email.
Request
{ "mfaToken": "enrollment-mfa-token", "mfaType": "app", "passcode": "123456" }
O Access Manager habilita o método e retorna uma resposta de desafio de MFA com o mesmo mfaToken. Continue com Solicitar a entrega por email para email e, depois, com Verificar o segundo fator.

Códigos de acesso errados contam para o mesmo limite por usuário da verificação (AUT-0018). O token de MFA mantém a duração que tinha no primeiro fator, então conclua a adesão e a verificação dentro de uma sessão de MFA.

Solicitar a entrega por email

Use Iniciar desafio de MFA para email.

Request

{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "email"
}

Não solicite a entrega para app. O aplicativo autenticador gera o código de acesso localmente.

Verificar o segundo fator

Use Verificar login por MFA. Envie passcode ou recoveryCode, nunca os dois.

Passcode

{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "passcode": "123456"
}

Recovery code

{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "recoveryCode": "unused-recovery-code"
}

Uma verificação bem-sucedida retorna a resposta padrão de token de acesso, a menos que o usuário ainda tenha um método exigido a cadastrar (AUT-0019). Um código de recuperação é consumido depois de um uso bem-sucedido.

Tratamento de erros

Os erros de entrada importantes incluem:

Código	Significado
`AUT-0016`	O código de acesso é inválido ou, em Iniciar adesão à MFA, o método não é um que o usuário deve cadastrar.
`AUT-0017`	A sessão de MFA expirou, ou o token de MFA não é válido para esta etapa. Reinicie a entrada.
`AUT-0018`	O limite de verificações foi excedido.
`AUT-0019`	A organização exige um método de MFA que o usuário não cadastrou. Cadastre-o com o token de MFA retornado.
`AUT-0020`	O token de MFA é inválido.

O Identity também pode recusar um método não compatível, um segredo de configuração ausente, um destino de email ausente ou uma configuração não verificada. Veja a lista de erros do Access Manager para consultar o envelope completo dos erros e os códigos atuais.

Introdução

Access Manager

Console

Streaming Hub

Multi-tenancy

Observabilidade

Narya

Lifecycle Management

Licenciamento

Gerenciar a MFA pela API

Operações de adesão da conta

Iniciar a configuração

Verificar a configuração

Habilitar o método

Desabilitar a MFA ou remover um método

Operações de administrador

Operações de entrada

Cadastrar um método exigido

Solicitar a entrega por email

Verificar o segundo fator

Tratamento de erros

Páginas relacionadas

Conclua a MFA no Console

APIs do Identity

​Operações de adesão da conta

​Iniciar a configuração

​Verificar a configuração

​Habilitar o método

​Desabilitar a MFA ou remover um método

​Operações de administrador

​Operações de entrada

​Cadastrar um método exigido

​Solicitar a entrega por email

​Verificar o segundo fator

​Tratamento de erros

​Páginas relacionadas

Conclua a MFA no Console

APIs do Identity

Operações de adesão da conta

Iniciar a configuração

Verificar a configuração

Habilitar o método

Desabilitar a MFA ou remover um método

Operações de administrador

Operações de entrada

Cadastrar um método exigido

Solicitar a entrega por email

Verificar o segundo fator

Tratamento de erros

Páginas relacionadas