Documentação do Oracle Cloud Infrastructure

Inscrevendo-se no MFA usando o Fator de SMS Usando o Self Service

Esse caso de uso fornece um exemplo passo a passo de uso da API REST de domínios de identidade para inscrição Self-Service na Autenticação Multifator (MFA) usando o Fator de SMS.

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-rest-clients no repositório GitHub de 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 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 de SMS

Esta etapa inicia a inscrição por 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 de 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

O exemplo a seguir 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, o deviceId e o requestId devem ser passados 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ê recebe 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ê recebe 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

O exemplo a seguir 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 especificados na próxima etapa.

2a. Iniciar a Solicitação de Inscrição de Autoatendimento para Reenviar OTP por SMS

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

Exemplo de Solicitação

O exemplo a seguir 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 especificados na próxima etapa.

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

Esta etapa valida a inscrição por SMS de um usuário em uma solicitação POST no 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 MFA. O atributo mfapreferredAuthenticationFactor indica o fator definido 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"
  }
}