Documentação do Oracle Cloud Infrastructure

Usando a API MFA Sob Demanda para Desenvolver a Página de Acesso Personalizado

Este caso de uso fornece um exemplo passo a passo do uso da API REST de domínios de identidade para autenticar usuários e executar inscrição e autenticação multifator.

Observação

Use essa API de Autenticação somente se estiver criando sua própria experiência de log-in de ponta a ponta desenvolvendo um aplicativo de acesso personalizado a ser usado pelos domínios de identidades.
Observação

Essa API Autenticar não pode ser usada para integrar seus aplicativos a domínios de identidades para fins de sign-on único.

A API de MFA do On Demand se baseia no conceito de uma máquina de estado. As respostas de solicitação informam a um cliente do aplicativo o que deve ser feito a seguir, em vez de exigir que os usuários tenham cookies de terceiros ativados em seus navegadores. Os cookies de terceiros ativados nos navegadores podem representar problemas, especialmente para aplicativos B2C em que os controles sobre o comportamento do usuário final não podem ser impostos. O requestState fornecido em cada resposta de solicitação é usado na próxima solicitação, fornecendo ao cliente as informações necessárias para processar a solicitação e, em seguida, fornecendo o próximo conjunto de operações permitidas.

A API de MFA do On Demand pode:
  • Suporte à inscrição do usuário com fatores de MFA ativados pelo administrador
  • Fortaleça a segurança da autenticação baseada em senha usando MFA (Multifactor Authentication), exigindo verificação adicional, como usar um código de acesso único baseado em tempo ou um código de acesso SMS.
  • Realize inscrição de MFA, verificação de MFA e gerenciamento do Fator de Autenticação do Usuário.

Os seguintes conjuntos de exemplo estão incluídos neste caso de uso:

Inscrição de Fator com Verificação

Inscrição de Fator com Verificação

Esses casos de uso fornecem solicitações de exemplo usando a API REST de domínios de identidade que permite que um usuário se inscreva em fatores de MFA.

Os seguintes casos de uso orientam você pelas etapas para inscrever diferentes fatores de MFA usando a API REST:

Obter Fatores Inscritos de um Usuário

Esse caso de uso fornece um exemplo passo a passo do uso da API de Verificação de domínios de identidades para extrair os fatores nos quais um usuário está inscrito.

Essas etapas pressupõem que os fatores relevantes da MFA sejam ativados usando Configurar Definições de Autenticação Multifator.

Faça download da coleção de exemplos de caso de uso de autenticação de domínios de identidades e do arquivo de variáveis globais na pasta idcs-factor-enrollment-api dentro do repositório idm-samples GitHub e importe-os para o Postman.

A etapa a ser seguida neste caso de uso depende se você deseja solicitar usando o userGUID ou o User Name:
Observação

Os exemplos nesta seção usam userGUID nas solicitações. Você pode solicitar userGUID e userOcid em suas solicitações.

Etapa 1: Obter Fatores Inscritos para um Usuário por userGUID

Esta etapa obtém os fatores inscritos para um usuário com base no userGUID ou no nome do Usuário.

Exemplo de Solicitação 

GET {{HOST}}/mfa/v1/users/{{userGUID}}/factors

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON:


{
    "userGUID": "7b3d902ab05b4214bae6b2924ca6be21",
    "status": "success",
    "preferredFactorId": "b3e04149d958437b9b801fa70c33ca70",
    "preferredMethod": "EMAIL",
    "factors": [
        {
            "factorId": "SecurityQuestions",
            "methods": [
                "SECURITY_QUESTIONS"
            ]
        },
        {
            "displayName": "+155XXXXX555",
            "factorId": "83889faeacaf4592a964405f87506fc6",
            "methods": [
                "SMS"
            ]
        },
        {
            "displayName": "uxxr1@example.com",
            "factorId": "b3e04149d958437b9b801fa70c33ca70",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        }
    ]
}

A resposta contém o userGUID, o fator preferencial e os detalhes do fator inscrito.

Etapa 2: Obter Fatores Inscritos para um Usuário Usando Filtros

Você pode obter fatores inscritos para um usuário usando o Nome do Usuário ou o GUID do Usuário. Os seguintes valores userIdType são aceitos:

  • USER_GUID- Por exemplo, aqui userId deve conter USER_GUID, como "7b3d902ab05b4214"
  • USER_NAME- Por exemplo, aqui userId deve conter USER_NAME, como John.

Exemplo de Solicitação para extrair os fatores inscritos com base no Nome do Usuário

O exemplo a seguir mostra o exemplo de solicitação para obter os fatores inscritos para um usuário com base em seu Nome de Usuário no formato JSON:

GET {{HOST}}/mfa/v1/users?userId=user1@example.com&userIdType=USER_NAME&attributes=factors

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON: 

{
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "status": "success",
    "preferredFactorId": "88178d80636a428393a5674ba46dc867",
    "preferredMethod": "SMS",
    "factors": [
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        },
        {
            "displayName": "user1@example.com",
            "factorId": "30db2274140043918edb033d9fe29ff3",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "displayName": "+1554455555",
            "factorId": "88178d80636a428393a5674ba46dc867",
            "methods": [
                "SMS"
            ]
        }
    ]
}

A resposta contém o userGUID, o fator preferencial e os detalhes do fator inscrito.

Exemplo de Solicitação para extrair os fatores inscritos com base no GUID do Usuário

O exemplo a seguir mostra o exemplo de solicitação para obter os fatores inscritos para um usuário com base no GUID do Usuário no formato JSON:

GET {{HOST}}/mfa/v1/users?userId=589879c55b7340518141eab82493f0cc&userIdType=USER_GUID&attributes=factors

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON:

{
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "status": "success",
    "preferredFactorId": "88178d80636a428393a5674ba46dc867",
    "preferredMethod": "SMS",
    "factors": [
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        },
        {
            "displayName": "user1@example.com",
            "factorId": "30db2274140043918edb033d9fe29ff3",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "displayName": "+1554455555",
            "factorId": "88178d80636a428393a5674ba46dc867",
            "methods": [
                "SMS"
            ]
        }
    ]
}

A resposta contém o userGUID, o fator preferencial e os detalhes do fator inscrito.

Iniciar e Verificar o Fator Preferencial

Este caso de uso fornece um exemplo passo a passo do uso da API de Inscrição de Fator dos domínios de identidade para se inscrever na Autenticação Multifator (MFA) com Verificação de Fator.

Essas etapas pressupõem que os fatores relevantes da MFA sejam ativados usando Configurar Definições de Autenticação Multifator.

Faça download da coleção de exemplos de caso de uso de autenticação de domínios de identidades e do arquivo de variáveis globais na pasta idcs-factor-verification-api dentro do repositório idm-samples GitHub e importe-os para o Postman.

Faça download da coleção e do arquivo de variáveis globais da pasta idcs-factor-verification-api em GitHub e importe-os para o Postman.

Use as seguintes etapas para o caso de uso. Cada etapa contém exemplos de solicitação e resposta:
Observação

Os exemplos nesta seção usam userGUID nas solicitações. Você pode solicitar userGUID e userOcid em suas solicitações.

Step1: Iniciar Verificação do Fator Preferencial

Essa etapa inicia a verificação do fator preferencial de um usuário. Se você precisar usar a API do fator de verificação sem fornecer o userGUID, poderá fornecer um id exclusivo do usuário, como nome de usuário, como userId. O userIdType na solicitação indica que tipo de credencial o usuário está informando como o valor do userId. Os seguintes valores userIdType são aceitos:

  • USER_GUID - Por exemplo, aqui userId deve conter USER_GUID, como "7b3d902ab05b4214"
  • USER_NAME - Por exemplo, aqui userId deve conter USER_NAME, como John.

O atributo userId contém o valor real da credencial do usuário informada.

Exemplo de Solicitação

O exemplo a seguir mostra a solicitação POST para o ponto final {{HOST}}/mfa/v1/requests no formato JSON.

{
   "userId":"{{userGUID}}",
   "userIdType": "USER_GUID"
}

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta POST para o ponto final {{HOST}}/mfa/v1/requests no formato JSON depois de iniciar o fator preferencial no ID preferencial:


{     
"status": "success",
"requestId": "f843736e-cbd8-4548-b41f-343b624a79fc",
"userGUID": "589879c55b7340518141eab82493f0cc",  
"factorId": "88178d80636a428393a5674ba46dc867",   
"method": "SMS",   
"displayName": "+4455665455",   
"requestState": "GwHJr3RvycjNEv.....MhQTLmWYzA/LVp0s"
}

Na resposta, o valor requestId é o identificador exclusivo gerado para essa solicitação. Inclua o requestId em cada chamada subsequente para concluir a verificação do fator. O factorId é o dispositivo preferencial no qual ele foi iniciado. O method é o fator que o usuário iniciou. O requestState contém os dados contextuais necessários para processar a solicitação.

Neste exemplo, um otpCode (no caso do fator SMS e EMAIL) é enviado usando SMS para o dispositivo móvel do usuário.

Etapa 2: Verificar o Fator Preferencial

Esta etapa verifica o fator informando o otpCode em uma solicitação PATCH para {{HOST}}/mfa/v1/requests/{{requestId}}.

O cliente deve incluir os seguintes atributos:

  • otpCode: o código recebido pelo usuário em seu dispositivo
  • requestState: recebido na resposta da Etapa 1
  • requestId: recebido na resposta da Etapa 1

Exemplo de Solicitação

O exemplo a seguir mostra o conteúdo da solicitação PATCH no formato JSON: 

{  
"otpCode":"170230", 
"requestState": "{{requestState}}" 
}

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON: 

{"status":"success"}

Êxito indica que a verificação foi bem-sucedida.

Iniciar e Verificar um Fator de Backup

Esse caso de uso fornece um exemplo passo a passo do uso da API de Verificação dos domínios de identidades para concluir a verificação do fator de backup.

Essas etapas pressupõem que os fatores relevantes da MFA sejam ativados usando Configurar Definições de Autenticação Multifator.

Faça download da coleção de exemplos de caso de uso de autenticação de domínios de identidades e do arquivo de variáveis globais na pasta idcs-factor-verification-api dentro do repositório idm-samples GitHub e importe-os para o Postman.

Use as seguintes etapas para o caso de uso. Cada etapa contém exemplos de solicitação e resposta:
Observação

Os exemplos nesta seção usam userGUID nas solicitações. Você pode solicitar userGUID e userOcid em suas solicitações.

Etapa 1: Iniciar e Verificar as Perguntas de Segurança do Fator de Backup

Essa etapa inicia a verificação do fator de backup de um usuário. O cliente deve fornecer o factorId e o method na solicitação. Se você precisar usar a API do fator de verificação sem fornecer o userGUID, poderá fornecer um id exclusivo do usuário, como nome de usuário, como userId. O userIdType na solicitação indica que tipo de credencial o usuário está informando como o valor do userId. Os seguintes valores userIdType são aceitos:

  • USER_GUID - Por exemplo, aqui userId deve conter USER_GUID, como "7b3d902ab05b4214".
  • USER_NAME - Por exemplo, aqui userId deve conter USER_NAME, como Joe John.

O atributo userId contém o valor real da credencial do usuário informada.

Para obter uma lista de fatores inscritos e seus IDs para um usuário, consulte o Caso de Uso Extrair Fatores Inscritos de um Usuário. Neste exemplo, o fator de backup escolhido é Perguntas de Segurança.

Exemplo de Solicitação para Iniciar Perguntas de Segurança do Fator de Backup

O exemplo a seguir mostra o conteúdo da solicitação POST para o ponto final {{HOST}}/mfa/v1/requests/ no formato JSON:

Observação

O factorId preferencial contém o ID exclusivo do fator preferencial. No caso de SECURITY_QUESTIONS, ele terá a string fixa "SecurityQuestions".
{
    "userId":"{{userID}}",
    "userIdType":"USER_GUID",
    "factorId":"{{factorID}}",
    "method":"SECURITY_QUESTIONS"
}

Na resposta, o valor requestId é o identificador exclusivo gerado para essa solicitação. Inclua o requestId em cada chamada subsequente para concluir a verificação do fator. O requestState contém dados contextuais necessários para processar a solicitação.

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON para o método de backup SEQURITY_QUESTIONS: 

{
    "status": "success",
    "requestId": "8da79411-5388-41ee-990e-935e74cb40f3",
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "factorId": "SecurityQuestions",
    "method": "SECURITY_QUESTIONS",
    "requestState": "hBJIvkyfsXBv....movYarft8HlYANV3c+0",
    "securityQuestions": [
        {
            "id": "MaidenName",
            "localizedText": "What's your mother's maiden name?"
        }
    ]
}

Na resposta, o valor requestId é o identificador exclusivo gerado para essa solicitação. Inclua o requestId em cada chamada subsequente para concluir a verificação do fator. O requestState contém dados contextuais necessários para processar a solicitação. Neste exemplo, uma pergunta é enviada de volta da lista de perguntas inscritas para as quais o usuário precisa responder.

Exemplo de Solicitação para Verificar Perguntas de Segurança do Fator de Backup

Esta etapa verifica o fator de backup informando a resposta para a Pergunta de Segurança em uma solicitação PATCH para {{HOST}}/mfa/v1/requests/{{requestID}}. O cliente deve incluir os seguintes atributos:

  • requestState: recebido na resposta da Etapa 1
  • securityQuestions id/answers: definido pelo usuário durante a inscrição

Exemplo de Solicitação

O exemplo a seguir mostra o conteúdo da solicitação PATCH no formato JSON para SECURITY_QUESTIONS: 
{
 "securityQuestions":[
        {
            "id":"MaidenName",
            "answer":"Smith"
        }
    ],
"requestState": "{{requestState}}"
 }

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON: 

{"status":"success"}

Êxito indica que a verificação foi bem-sucedida.

Etapa 2: Iniciar e Verificar E-MAIL do Fator de Backup

Esta etapa inicia a verificação de um fator de backup EMAIL.

Exemplo de Solicitação para Iniciar fator EMAIL

O exemplo a seguir mostra o exemplo de solicitação no formato JSON para o método preferencial "EMAIL":

{
    "userId":"{{userID}}",
    "userIdType":"USER_GUID",
    "factorId":"{{factorID}}",
    "method":"EMAIL"
}

Exemplo de Resposta

O exemplo a seguir mostra o exemplo de resposta para iniciar o fator EMAIL no formato JSON:

{ 
 "status":"success",
 "requestId":"<Request ID>",
 "userGUID":"<User GUID>",
 "factorId":"factorID",
 "method":"EMAIL",
 "displayName":"Joe John",
 "requestState":"QYV81R9eoagwWQ"
 }

Exemplo de Solicitação para Verificar Fator de E-mail

O exemplo a seguir mostra a solicitação PATCH no formato JSON para o fator EMAIL:

{
    "otpCode":"170230"
     "requestState": "QYV81R9eoagwWQ"
 }

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON para verificar o Fator EMAIL: 

{"status":"success"}

Êxito indica que a verificação foi bem-sucedida.

Retornar Fatores OTP sem Notificar o Usuário

Esse caso de uso fornece um exemplo de inicialização da API de MFA do On Demand para retornar fatores de código de acesso único (OTP) (SMS, E-mail ou Chamada telefônica) em uma resposta sem notificar o usuário.

Faça download da coleção de exemplos de caso de uso de autenticação de domínios de identidades e do arquivo de variáveis globais na pasta idcs-factor-verification-api dentro do repositório idm-samples GitHub e importe-os para o Postman.

Essas etapas pressupõem que os fatores relevantes da MFA sejam ativados usando Configurar Definições de Autenticação Multifator.

Payload de Solicitação
Atributo Valores/Valores de Amostra Suportados Vários Valores Detalhes do Uso
userFlowControlledByExternalClient verdadeiro / falso falso
Definir esta opção como 
true
e o OTP será retornado na resposta no formato criptografado especificado.

Observação: O certificado usado para criptografia é submetido a upload para o aplicativo com antecedência e é referenciado usando o atributo x5t no exemplo de solicitação, conforme mencionado abaixo.
x5t Miniatura do certificado String / X509 SHA-1

Quando especificado, o serviço usa esse certificado submetido a upload para criptografar os dados do OTP.

Observação: o atributo "x5t" deve corresponder ao certificado submetido a upload.
Exemplo de Solicitação
{
    "userId":"<Unique Id>",
    "userIdType":"USER_NAME/USER_GUID",
    "userFlowControlledByExternalClient": true,
    "x5t" :"<certificate thumbprint>"
}
Payload de Resposta
Atributo Valores/Valores de Amostra Suportados Vários Valores Detalhes do Uso
otp

Mapear

"otp": {
    "value": "IMCw==",
    "alg": "RSAES-OAEP",
      "x5t": "<certificate thumbprint>"
 }
falso

Quando presente na resposta, o atributo contém o OTP criptografado com os seguintes detalhes.

  • value: Valor criptografado.
  • alg: Algoritmo usado para criptografia.
  • x5t: SHA-1 X509 Miniatura do certificado usado para criptografia.

Exemplo de Resposta

{
    "status": "success",
    "requestId": "<Request ID>",
    "userGUID": "<User GUID>",
    "factorId": "<SMS/EMAIL/PHONE_CALL factor GUID>",
    "method": "SMS/EMAIL/PHONE_CALL",
    "displayName": "+91XXXXXXXX984",
    "requestState": "4p7ViEzP2bP1MIM",
    "otp": {
        "value": "<Encrypted OTP value>",
        "alg": "<Encryption algorithm>",
        "x5t": "<x5t of the certificate used to encrypt the OTP>"
           }
}

Inscrição do Fator de Autenticação com Verificação de Fator - SMS

Este caso de uso fornece um exemplo passo a passo do uso da API de Inscrição de Fator dos domínios de identidade para se inscrever na Autenticação Multifator (MFA) com Verificação de Fator.

Essas etapas pressupõem que os fatores relevantes da MFA sejam ativados usando Configurar Definições de Autenticação Multifator.

Faça download da coleção de exemplos de caso de uso de autenticação de domínios de identidades e do arquivo de variáveis globais na pasta idcs-factor-enrollment-api dentro do repositório idm-samples GitHub e importe-os para o Postman.

Use as seguintes etapas para o caso de uso. Cada etapa contém exemplos de solicitação e resposta:
Observação

Os exemplos nesta seção usam userGUID nas solicitações. Você pode solicitar userGUID e userOcid em suas solicitações.

Etapa 1: Iniciar Inscrição do Fator SMS

Esta etapa inicia a inscrição de SMS. O cliente deve incluir os seguintes atributos:

  • method: define para se inscrever no fator SMS
  • phoneNumber: define o número de telefone para o qual o texto SMS será enviado
  • countryCode: define o código do país do número de telefone para o qual o texto SMS será enviado

Exemplo de Solicitação

O exemplo a seguir mostra a solicitação POST para o ponto final {{HOST}}/mfa/v1/users/{{userGUID}}/factors no formato JSON:

{ 
"method": "SMS",
"countryCode": "+44", 
"mobileNumber": "1122334455", 
}

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON: 

{
"status": "success", 
"factorId": "88178d80636a428393a5674ba46dc867",
"factorStatus": "ENROLLMENT_INITIATED", 
"methods": [ "SMS" ],
"displayName": "+1122334455", 
"requestState": "QK1.....y+OFP//0" 
}

displayName é o número do celular. Um otpCode será enviado para o dispositivo móvel dos usuários, que é usado para concluir a inscrição.

Etapa 1a: Reenviar o OTP

Se o usuário não receber o OTP, este exemplo mostrará como solicitar que um OTP seja reenviado. O cliente deve incluir os seguintes atributos:

requestState: recebido na resposta da Etapa 1

resendOtp: Booliano para indicar que o OTP foi recebido

Exemplo de Solicitação

O exemplo a seguir mostra a solicitação PATCH para o ponto final {{HOST}}/mfa/v1/users/{{userGUID}}/factors/{{factorID}} no formato JSON:

{
 "resendOtp":true,
 "requestState": "QK1.....y+OFP//0"
}

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON:

{ 
"status": "success",
"factorId": "88178d80636a428393a5674ba46dc867", 
"factorStatus": "ENROLLMENT_INITIATED",
"methods": [ "SMS" ],
"displayName": "+445544455",
"requestState": "+HFVV...qgMUI" 
}

A resposta contém os seguintes parâmetros:

  • requestState: que deve ser passado pelo cliente na próxima etapa
  • displayName: é o número do celular que está sendo inscrito
  • method: Método do fator SMS
  • factorId: identificador exclusivo gerado para o fator que está sendo inscrito
O sucesso indica que:
  • O userGUID que foi fornecido é válido
  • O usuário está ativo
  • A conta do usuário não está bloqueada
  • O fator SMS está ativado

Etapa 2: Ativando o Fator SMS

Esta etapa ativa a inscrição de SMS para o usuário, em uma solicitação PATCH para o ponto final /mfa/v1/users/{{userGUID}}/factors/{{factorID}}.

O cliente deve incluir os seguintes atributos:

  • otpCode: o código recebido pelo usuário em seu dispositivo
  • requestState: recebido na resposta da Etapa 1

Exemplo de Solicitação

O exemplo a seguir mostra o conteúdo da solicitação PATCH no formato JSON: 

{  
"otpCode":"170230", 
"requestState": "{{requestState}}"
 }

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON: 

{"status":"success"}

O sucesso indica que:

  • OTP é válido
  • O userGUID que foi fornecido é válido
  • O usuário está ativo
  • A conta do usuário não está bloqueada
  • O fator SMS está ativado e o fator foi inscrito com sucesso

Exemplos de Resposta de Erro

O exemplo a seguir mostra a mensagem de erro no formato JSON quando o userGUID é inválido. Você obterá um código de resposta HTTP 404 se o userGUID for inválido.
{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

O exemplo a seguir mostra a mensagem de erro no formato JSON quando o usuário está bloqueado. Você obtém um código de resposta HTTP 401.

{
    "status": "failed",
    "ecId": "0ISDCif1Qy6wg0000A8",
    "cause": [
        {
            "code": "AUTH-1010",
            "message": "Your account is locked.Contact your system administrator."
        }
    ]
}

Inscrição do Fator de Autenticação com Verificação de Fator - E-mail

Este caso de uso fornece um exemplo passo a passo do uso da API de Inscrição de Fator dos domínios de identidade para se inscrever na Autenticação Multifator (MFA) com Verificação de Fator.

Essas etapas pressupõem que os fatores relevantes da MFA sejam ativados usando Configurar Definições de Autenticação Multifator.

Faça download da coleção de exemplos de caso de uso de autenticação de domínios de identidades e do arquivo de variáveis globais na pasta idcs-factor-enrollment-api dentro do repositório idm-samples GitHub e importe-os para o Postman.

Use as seguintes etapas para o caso de uso. Cada etapa contém exemplos de solicitação e resposta:
Observação

Os exemplos nesta seção usam userGUID nas solicitações. Você pode solicitar userGUID e userOcid em suas solicitações.

Etapa 1: Iniciar Inscrição do Fator de E-mail

Esta etapa inicia a inscrição de E-mail. O cliente deve incluir o seguinte atributo:

  • method: define para se inscrever no E-mail. O usuário não passará o id do e-mail. O ID do e-mail principal é extraído automaticamente do perfil do usuário.

Exemplo de Solicitação

O exemplo a seguir mostra o conteúdo da solicitação POST para o ponto final {{HOST}}/mfa/v1/users/{{userGUID}}/factors no formato JSON: 

{ 
"method": "EMAIL",
}

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON: 

{
    "status": "success",
    "factorId": "30db2274140043918edb033d9fe29ff3",
    "factorStatus": "ENROLLMENT_INITIATED",
    "methods": [
        "EMAIL"
    ],
    "displayName": "user1@example.com",
    "requestState": "Vxar...bWTTA"
}

Um otpCode será enviado para o id de e-mail do usuário, que é usado para concluir a inscrição.

A resposta contém:

  • requestState: que deve ser passado pelo cliente na próxima etapa
  • ID de e-mail displayName: do usuário inscrito
  • method: Método do fator EMAIL

O sucesso indica que:

A inscrição do fator foi iniciada.

Etapa 1a: Reenviar o OTP

O exemplo a seguir mostra a solicitação PATCH para o ponto final {{HOST}}/mfa/v1/users/{{userGUID}}/factors/{{factorID}} no formato JSON.

Se o usuário não receber o OTP, este exemplo mostrará como solicitar que um OTP seja reenviado. O cliente deve incluir os seguintes atributos:

  • requestState: recebido na resposta da Etapa 1
  • resendOtp: para indicar que o OTP foi recebido

Exemplo de Solicitação

O exemplo a seguir mostra o conteúdo da solicitação PATCH no formato JSON: 

{  
"resendOtp":true, 
 "requestState": "QK1.....y+OFP//0"
 }

O exemplo a seguir mostra o conteúdo da resposta no formato JSON: 

{    
"status": "success",     
"factorId": "30db2274140043918edb033d9fe29ff3",
"factorStatus": "ENROLLMENT_INITIATED",   
"methods": ["EMAIL"],
"displayName": "username@example.com", 
"requestState": "AmgsMN.....2sk4SI" 
}

A resposta contém:

  • requestState: que deve ser passado pelo cliente na próxima etapa
  • displayName: id de e-mail extraído do perfil do usuário
  • method: a lista de métodos que estão sendo inscritos no método EMAIL
  • factorId: identificador exclusivo gerado para o fator que está sendo inscrito

O sucesso indica que:

  • O userGUID ou userOcid que foi fornecido é válido
  • O usuário está ativo
  • A conta do usuário não está bloqueada
  • O fator EMAIL está ativado

Etapa 2: Ativar o Fator EMAIL

Esta etapa ativa a inscrição E-MAIL para o usuário, em uma solicitação PATCH para o ponto final /mfa/v1/users/{{userGUID}}/factors/{{factorID}}.

O cliente deve incluir os seguintes atributos:

  • otpCode: o código recebido pelo usuário em seu id de e-mail
  • requestState: recebido na resposta da Etapa 1

Exemplo de Solicitação

O exemplo a seguir mostra o conteúdo da solicitação PATCH no formato JSON: 

{
"otpCode":"710130", 
"requestState": "{{requestState}}"
}

Exemplo de Resposta

O exemplo a seguir mostra o conteúdo da resposta no formato JSON: 

{"status":"success"}

O sucesso indica que:

  • OTP é válido
  • O userGUID ou userOcid que foi fornecido é válido
  • O usuário está ativo
  • A conta do usuário não está bloqueada
  • O fator EMAIL está ativado e o fator foi inscrito com sucesso

Exemplos de Resposta de Erro

O exemplo a seguir mostra a mensagem de erro no formato JSON quando o userGUID é inválido. Você obterá um código de resposta HTTP 404 se userGUID ou userOcid for inválido.
{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

O exemplo a seguir mostra a mensagem de erro no formato JSON quando EMAIL está desativado. Você obtém um código de resposta HTTP 401.

{
    "status": "failed",
    "ecId": "0000M00000A",
    "cause": [
        {
            "code": "AUTH-1125",
            "message": "The EMAIL factor has been disabled."
        }
    ]
}