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.

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.

Operações de entrada

O primeiro fator usa Solicitar token de acesso. Quando a MFA é obrigatória, 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.

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 entrada com 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. 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-0015`	A MFA é obrigatória antes que o Auth possa emitir tokens de acesso.
`AUT-0016`	O código de acesso ou de recuperação é inválido.
`AUT-0017`	A sessão de MFA expirou. Reinicie a entrada.
`AUT-0018`	O limite de verificações ou reenvios foi excedido.
`AUT-0019`	O método selecionado ainda precisa ser configurado.
`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.

Primeiros passos

Funcionalidades

Deploy e operações

Arquitetura

Provedor de identidade (Caradhras)

Gerenciar a MFA pela API

Operações de adesão da conta

Iniciar a configuração

Verificar a configuração

Habilitar o método

Operações de entrada

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

​Operações de entrada

​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

Operações de entrada

Solicitar a entrega por email

Verificar o segundo fator

Tratamento de erros

Páginas relacionadas