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 identidade e do arquivo de variáveis globais da pasta idcs-rest-clients no repositório GitHub idm-samples e importe-os para o Postman.

Como uma etapa de pré-requisito, você deve obter um token ME antes de seguir essas etapas. Consulte Gerando Token de Acesso Usando 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 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"
  }
}