Documentação do Oracle Cloud Infrastructure

Inscrevendo-se no MFA usando o Fator SMS no Autoatendimento

Este caso de uso fornece um exemplo passo a passo do uso da API REST dos domínios de identidade para inscrição de Autoatendimento na Autenticação Multifator (MFA) usando o Fator SMS.

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-rest-clients dentro do repositório idm-samples GitHub e importe-os para o Postman.

Como etapa de pré-requisito, você deve obter um token ME antes de seguir essas etapas. Consulte Gerando Token de Acesso Usando a API de Autenticação para obter informações sobre como obter um token ME.

Há três etapas neste caso de uso. Cada etapa contém exemplos de solicitação e resposta:
Observação

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

Step1: Criar a Inscrição Self-Service Usando o Fator SMS

Esta etapa inicia a inscrição de SMS em uma solicitação POST para o ponto final /admin/v1/MyAuthenticationFactorEnroller. O cliente deve incluir os seguintes atributos:

  • value: define o id do usuário. Você pode fazer uma chamada GET para {{HOST}}/admin/v1/Me para obter o valor "id".
  • displayName: define o nome para exibição do dispositivo
  • countryCode: define o código do país do número de telefone para o qual o texto SMS será enviado
  • phoneNumber: define o número de telefone para o qual o texto SMS será enviado

Exemplo de Solicitação

Este exemplo mostra o conteúdo do corpo da solicitação POST no formato JSON: 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
  ],
  "user": {
    "value": "c810ff4522eb437abac013291c1984d1"
  },
  "displayName": "Joe's Personal Phone",
  "countryCode": "+44",
  "phoneNumber": "1122334455",
  "authnFactors": [
    "SMS"
  ]
}

Exemplo de Resposta

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

{
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
    ],
    "user": {
        "value": "c810ff4522eb437abac013291c1984d1",
        "$ref": "https://example.identitycloud.com/admin/v1/Users/c810ff4522eb437abac013291c1984d1"
    },
    "displayName": "Joe's Personal Phone",
    "countryCode": "+44",
    "phoneNumber": "XXXXXXX455",
    "authnFactors": [
        "SMS"
    ],
    "meta": {
        "resourceType": "MyAuthenticationFactorEnroller",
        "location": "https://example.identitycloud.com/admin/v1/MyAuthenticationFactorEnroller"
    },
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179"
}

Na resposta, deviceId e requestId devem ser informados na próxima etapa.

Exemplos de Resposta de Erro

O exemplo a seguir mostra a mensagem de erro no formato JSON quando o userId é inválido. Você obtém um código de resposta HTTP 400. 
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error",
        "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error"
    ],
    "detail": "AuthenticationFactorEnroller.user references a User with ID 1fa35f74491d44ef5a7cc25bfdb1c8b1c that does not exist.",
    "status": "400",
    "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error": {
        "messageId": "error.common.validation.invalidReferenceResource"
    }
}

O exemplo a seguir mostra a mensagem de erro no formato JSON se um phoneNumber estiver incorreto. Você obtém um código de resposta HTTP 400.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error",
        "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error"
    ],
    "detail": "Your phone number +91123 is not valid.",
    "status": "400",
    "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error": {
        "messageId": "error.ssocommon.auth.invalidPhoneNumber",
        "additionalData": {
            "params": "+91123",
            "msgId": "error.ssocommon.auth.invalidPhoneNumber"
        }
    }
}

Etapa 2: Iniciar a Inscrição Self-Service Usando o OTP por SMS

Esta etapa solicita que o OTP seja enviado por SMS em uma solicitação POST para o ponto final /admin/v1/MyAuthenticationFactorInitiator. O cliente deve incluir os seguintes atributos:

requestId: recebido na resposta da Etapa 1

deviceId: recebido na resposta da Etapa 1

userName: nome de usuário do usuário

Exemplo de Solicitação

Este exemplo mostra o conteúdo do corpo da solicitação POST no formato JSON:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
  ],
  "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
  "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
  "userName": "jbloggs",
  "authFactor": "SMS"
}

Exemplo de Resposta

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

{
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
    "authFactor": "SMS",
    "userName": "jbloggs",
    "displayName": "Joe's Personal Phone",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
    ]
}

Um código OTP é enviado usando SMS para o dispositivo móvel do usuário. Na resposta, deviceId e requestId devem ser informados na próxima etapa.

2a. Iniciar a Solicitação de Inscrição Self-Service para Reenviar o OTP por SMS

Caso o usuário queira que o servidor "reenvie" o OTP, o mesmo payload mencionado na Etapa 2 deverá ser enviado ao servidor novamente.

Exemplo de Solicitação

Este exemplo mostra o conteúdo do corpo da solicitação POST no formato JSON:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
  ],
  "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
  "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
  "userName": "jbloggs",
  "authFactor": "SMS"
}

Exemplo de Resposta

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

{ 
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
    "authFactor": "SMS",
    "userName": "jbloggs",
    "displayName": "Joe's Personal Phone",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
    ]
}

Um código OTP é enviado usando SMS para o dispositivo móvel do usuário. Na resposta, deviceId e requestId devem ser informados na próxima etapa.

Etapa 3: Validar a Inscrição no Autoatendimento Usando o OTP

Esta etapa valida a inscrição de SMS de um usuário em uma solicitação POST para o ponto final /admin/v1/MyAuthenticationFactorValidator.

O cliente deve incluir os seguintes atributos:

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

Exemplo de Solicitação

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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
  ],
  "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
  "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
  "otpCode": "191224",
  "authFactor": "SMS",
  "scenario": "ENROLLMENT"
}

Exemplo de Resposta

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

{
    "authFactor": "SMS",
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
    "scenario": "ENROLLMENT",
    "status": "SUCCESS",
    "displayName": "Joe's Personal Phone",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
    ],
    "mfaStatus": "ENROLLED",
    "mfaPreferredDevice": "2b27b8c072d64b899d41c8470acea32a",
    "mfaPreferredAuthenticationFactor": "SMS",
    "securityQuestionsPresent": false,
    "devicesCount": 3,
    "emailFactorEnrolled": true
}
Na resposta, o atributo mfaStaus:"ENROLLED" indica que o usuário se inscreveu para a MFA. O atributo mfapreferredAuthenticationFactor indica o conjunto de fatores como o método preferencial. Neste caso, é SMS.
Observação

Esse valor poderá ser diferente se o primeiro fator inscrito for diferente do SMS.

Exemplos de Resposta de Erro

O exemplo a seguir mostra a mensagem de erro no formato JSON se o OTP estiver incorreto. Você obtém um código de resposta HTTP 401 e a inscrição falha.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error",
    "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error"
  ],
  "detail": "Invalid passcode.",
  "status": "401",
  "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error": {
    "messageId": "error.ssocommon.auth.invalidPasscode"
  }
}