Documentação do Oracle Cloud Infrastructure

Usando a API MFA sob Demanda para Desenvolver uma Página de Acesso Personalizada

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

Observação

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

Essa API de Autenticação 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 é baseada no conceito de uma máquina de estado. As respostas de solicitação informam a um cliente de 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 aplicados. 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:
  • Suportar inscrição de usuário com fatores MFA ativados pelo administrador
  • Reforce a segurança da autenticação baseada em senha usando a Autenticação Multifator (MFA) exigindo verificação adicional, como usar um código de acesso único baseado em tempo ou um código de acesso SMS.
  • Realize a inscrição de MFA, a verificação de MFA e o gerenciamento do Fator de Autenticação do Usuário.

Os seguintes exemplos de conjuntos são incluídos neste caso de uso:

Inscrição do Fator com Verificação

Inscrição do Fator com Verificação

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

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

Extrair Fatores Inscritos de um Usuário

Esse caso de uso fornece um exemplo passo a passo de uso da API de Verificação de domínios de identidade 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 identidade e do arquivo de variáveis globais na pasta idcs-factor-enrollment-api no repositório GitHub idm-samples e importe-os para o Postman.

A etapa a seguir 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 de 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 Nome do Usuário ou 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 de 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 de 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

Esse caso de uso fornece um exemplo passo a passo de 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 casos de uso de autenticação de domínios de identidades e do arquivo de variáveis globais da pasta idcs-factor-verification-api no repositório GitHub de idm-samples 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.

Utilize 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

Esta 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 o nome de usuário userId. O userIdType na solicitação indica qual 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 que foi 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 ao ponto final {{HOST}}/mfa/v1/requests no formato JSON após 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 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 de SMS e fator EMAIL) é enviado usando SMS para o dispositivo móvel do usuário.

Etapa 2: Verificar o Fator Preferencial

Esta etapa verifica o fator passando 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 de uso da API de Verificação de domínios de identidades para concluir a verificação de fator 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 casos de uso de autenticação de domínios de identidades e do arquivo de variáveis globais da pasta idcs-factor-verification-api no repositório GitHub de idm-samples e importe-os para o Postman.

Utilize 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

Esta 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 o nome de usuário userId. O userIdType na solicitação indica qual 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 que foi informada.

Para obter uma lista de fatores inscritos e seus IDs para um usuário, consulte o Caso de Uso Obter 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

A opção preferencial factorId contém o ID exclusivo do fator preferencial. No caso do 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 à 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

Este 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 casos de uso de autenticação de domínios de identidades e do arquivo de variáveis globais da pasta idcs-factor-verification-api no repositório GitHub de idm-samples 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 Suportados/Valores de Amostra Multivalor Detalhes de Uso
userFlowControlledByExternalClient true / false 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 SHA-1 da string/X509

Quando especificado, o serviço usa esse certificado submetido a upload para criptografar os dados 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 Suportados/Valores de Amostra Multivalor Detalhes de 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 do Fator - SMS

Esse caso de uso fornece um exemplo passo a passo de 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 identidade e do arquivo de variáveis globais na pasta idcs-factor-enrollment-api no repositório GitHub idm-samples e importe-os para o Postman.

Utilize 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 SMS

Esta etapa inicia a inscrição por 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 de celular inscrito
  • method: Método de fator SMS
  • factorId: identificador exclusivo gerado para o fator que está sendo inscrito
Sucesso indica que:
  • O userGUID 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 de 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"}

Sucesso indica que:

  • OTP é válido
  • O userGUID 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ê recebe 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 do Fator - E-mail

Esse caso de uso fornece um exemplo passo a passo de 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 identidade e do arquivo de variáveis globais na pasta idcs-factor-enrollment-api no repositório GitHub idm-samples e importe-os para o Postman.

Utilize 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 por e-mail. O cliente deve incluir o seguinte atributo:

  • method: define para se inscrever no E-mail. O usuário não informará 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
  • displayName: id de e-mail do usuário inscrito
  • method: Método do fator EMAIL

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: isso deve ser passado pelo cliente na próxima etapa
  • displayName: id do 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

Sucesso indica que:

  • O userGUID ou o userOcid 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 de EMAIL

Esta etapa ativa a inscrição no EMAIL do 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"}

Sucesso indica que:

  • OTP é válido
  • O userGUID ou o userOcid 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 o 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 o EMAIL está desativado. Você recebe um código de resposta HTTP 401.

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