Oracle Cloud Infrastructure - Dokumentation

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-Faktor.

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

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

In diesem Anwendungsfall gibt es drei Schritte. Jeder Schritt enthält Anforderungs- und Antwortbeispiele:
Hinweis

Bei diesen Schritten wird davon ausgegangen, dass relevante Faktoren von MFA mit Multifactor-Authentifizierungseinstellungen konfigurieren aktiviert werden.

Step1: Selfservice-Anmeldung mit dem SMS-Faktor erstellen

Dieser Schritt initiiert die SMS-Registrierung in 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-Anforderungsbodys 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 Antwortbodys 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.

Beispiele für Fehlerantworten

Das folgende Beispiel zeigt die Fehlermeldung im JSON-Format, wenn 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: Self-Service-Anmeldung mit OTP per SMS starten

Dieser Schritt fordert an, dass das OTP in einer POST-Anforderung per 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-Anforderungsbodys 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. Selfservice-Anmeldeanforderung starten, um OTP per SMS erneut zu senden

Wenn der Benutzer möchte, dass der Server das OTP erneut sendet, sollte dieselbe Payload wie in Step{ENT:amp};2 angegeben erneut an den Server gesendet werden.

Anforderungsbeispiel

Das folgende Beispiel zeigt den Inhalt des POST-Anforderungsbodys 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: Self-Service-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: der vom Benutzer auf seinem Gerät empfangene 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 wurde. In diesem Fall ist es SMS.
Hinweis

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

Beispiele für Fehlerantworten

Im folgenden Beispiel wird die Fehlermeldung im JSON-Format angezeigt, wenn OTP falsch ist. Sie erhalten einen HTTP-Antwortcode 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"
  }
}