Mit dem SMS-Faktor per Selfservice bei MFA anmelden

Dieser Anwendungsfall enthält ein schrittweises Beispiel für die Verwendung der REST-API für Identitätsdomains für die Selfservice-Registrierung bei der Multifaktor-Authentifizierung (MFA) mit SMS Factor.

Laden Sie die Collection der Anwendungsbeispiele für die Authentifizierung von Identitätsdomains und die globale Variablendatei aus dem Ordner idcs-rest-clients im Repository idm-samples GitHub herunter, und importieren Sie sie dann in Postman.

Als Voraussetzung müssen Sie ein ME-Token abrufen, bevor Sie diese Schritte ausführen. Informationen zum Abrufen eines ME-Tokens finden Sie unter Zugriffstoken mit Authentifizierungs-API generieren.

Hinweis

Bei diesen Schritten wird davon ausgegangen, dass relevante Faktoren von MFA mit Einstellungen für die Multifaktor-Authentifizierung konfigurieren aktiviert sind.

Step1: Selfservice-Registrierung mit dem SMS-Faktor erstellen

Dieser Schritt initiiert die SMS-Registrierung bei einer POST-Anforderung an den Endpunkt /admin/v1/MyAuthenticationFactorEnroller. Der Client muss die folgenden Attribute enthalten:

  • value: Definiert die Benutzer-ID. Sie können einen GET-Aufruf an {{HOST}}/admin/v1/Me durchführen, um den Wert "id" abzurufen.
  • displayName: Definiert den Anzeigenamen für das Gerät
  • countryCode: Definiert die Landeskennzahl der Telefonnummer, an die der SMS-Text gesendet wird
  • phoneNumber: Definiert die Telefonnummer, an die der SMS-Text gesendet wird

Anforderungsbeispiel

Das folgende Beispiel zeigt den Inhalt des POST-Anforderungstextes im JSON-Format:

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

Antwortbeispiel

Das folgende Beispiel zeigt den Inhalt des Antworttextes im JSON-Format:

{
    "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"
}

In der Antwort müssen deviceId und requestId im nächsten Schritt übergeben werden.

Fehlerantwortbeispiele

Das folgende Beispiel zeigt die Fehlermeldung im JSON-Format, wenn die userId ungültig ist. Sie erhalten einen 400 HTTP-Antwortcode.
{
    "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"
    }
}

Das folgende Beispiel zeigt die Fehlermeldung im JSON-Format, wenn eine phoneNumber falsch ist. Sie erhalten einen 400 HTTP-Antwortcode.

{
    "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"
        }
    }
}

Schritt 2: Selfservice-Registrierung mit OTP per SMS initiieren

Dieser Schritt fordert an, dass das OTP in einer POST-Anforderung über SMS an den Endpunkt /admin/v1/MyAuthenticationFactorInitiator gesendet wird. Der Client muss die folgenden Attribute enthalten:

requestId: in der Schritt-1-Antwort empfangen

deviceId: in der Schritt-1-Antwort empfangen

userName:-Benutzername des Benutzers.

Anforderungsbeispiel

Das folgende Beispiel zeigt den Inhalt des POST-Anforderungstextes im JSON-Format:

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

Antwortbeispiel

Das folgende Beispiel zeigt den Inhalt der Antwort im JSON-Format:

{
    "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"
    ]
}

Ein OTP-Code wird per SMS an das Mobilgerät des Benutzers gesendet. In der Antwort müssen deviceId und requestId im nächsten Schritt übergeben werden.

2a. Initiieren der Selfservice-Anmeldeanforderung zum erneuten Senden von OTP per SMS

Wenn der Benutzer möchte, dass der Server das OTP erneut sendet, muss dieselbe Payload wie in Schritt 2 erneut an den Server gesendet werden.

Anforderungsbeispiel

Das folgende Beispiel zeigt den Inhalt des POST-Anforderungstextes im JSON-Format:

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

Antwortbeispiel

Das folgende Beispiel zeigt den Inhalt der Antwort im JSON-Format:

{ 
    "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"
    ]
}

Ein OTP-Code wird per SMS an das Mobilgerät des Benutzers gesendet. In der Antwort müssen deviceId und requestId im nächsten Schritt übergeben werden.

3. Schritt: Selfservice-Anmeldung mit OTP validieren

Dieser Schritt validiert die SMS-Registrierung eines Benutzers in einer POST-Anforderung an den Endpunkt /admin/v1/MyAuthenticationFactorValidator.

Der Client muss die folgenden Attribute enthalten:

  • otpCode: den vom Benutzer auf seinem Gerät empfangenen Code
  • requestId: in der Schritt-2-Antwort empfangen
  • deviceId: in der Schritt-2-Antwort empfangen

Anforderungsbeispiel

Das folgende Beispiel zeigt den Inhalt der POST-Anforderung im JSON-Format:

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

Antwortbeispiel

Das folgende Beispiel zeigt den Inhalt der Antwort im JSON-Format:

{
    "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
} 
In der Antwort gibt das Attribut mfaStaus:"ENROLLED" an, dass sich der Benutzer für MFA registriert hat. Das Attribut mfapreferredAuthenticationFactor gibt den Faktor an, der als bevorzugte Methode festgelegt ist. In diesem Fall ist es SMS.
Hinweis

Dieser Wert kann sich unterscheiden, wenn sich der erste registrierte Faktor von SMS unterscheidet.

Fehlerantwortbeispiele

Das folgende Beispiel zeigt die Fehlermeldung im JSON-Format, wenn OTP falsch ist. Sie erhalten einen HTTP-Antwortcode von 401, und die Registrierung ist nicht erfolgreich.

{
  "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"
  }
}