So richten Sie die Vonage Protection Suite für PingOne ein

Einführung

Die Vonage Protection Suite für PingOne ist ein selbstverwalteter, programmierfreier Konnektor, der auf der Vonage Cloud Runtime (VCR) basiert. Er lässt sich als benutzerdefinierter Benachrichtigungsanbieter direkt in Ihre PingOne-Umgebung integrieren und nutzt Vonage Verify, um Einmalpasswörter (OTPs) per SMS und Sprachansage zu versenden.

Vor dem Versand eines OTP kann der Connector über Identity Insights optionale Sicherheitsprüfungen durchführen, darunter die Überprüfung der Rufnummer und die Abfrage des Netzbetreibers. Während der OTP-Übermittlung bietet Vonage Fraud Defender einen zusätzlichen Schutz durch die Erkennung von SMS-Pumping, geografische Berechtigungen und Geschwindigkeitskontrollen.

Der Konnektor ist über den Vonage Cloud Runtime (VCR) Marketplace verfügbar. Dort können Sie ihn bereitstellen und die Integration in Ihre PingOne-Umgebung konfigurieren, ohne dass ein Eingriff seitens Vonage erforderlich ist.

Die Nutzung der Vonage Protection Suite für PingOne unterliegt den Vonage-Bedingungen Nutzungsbedingungen und Ergänzende Bestimmungen zu Steckverbindern.

Für wen dieser Leitfaden gedacht ist

Dieser Leitfaden gliedert sich nach den folgenden Rollen:

• Systemadministratoren und IT-Fachleute: Stellen Sie den Connector bereit und konfigurieren Sie ihn, richten Sie die PingOne-Integration ein, verwalten Sie Authentifizierungstoken und überwachen Sie die Zustellung der OTPs. Weiter zu Installations- und Konfigurationshandbuch (Administrator).
• Endnutzer: Erhalten Sie bei der PingOne-Authentifizierung Einmalpasswörter per SMS oder Sprachansage. Es ist keine Konfiguration erforderlich. Einen Überblick über den Authentifizierungsablauf finden Sie unter Erfahrungen mit der OTP-Zustellung.

Zweistufiges Sicherheitsmodell

Die Vonage Protection Suite für PingOne basiert auf einem zweistufigen Sicherheitsmodell:

Steckverbinder-Durchfluss

Das folgende Diagramm veranschaulicht, wie der Konnektor die Übermittlung des Einmalpassworts (OTP) zwischen PingOne und Vonage Verify handhabt. PingOne ist weiterhin für die Generierung und Validierung des OTP verantwortlich, während der Konnektor dieses per SMS oder Sprachnachricht übermittelt.

Voraussetzungen

Bevor Sie beginnen, vergewissern Sie sich, dass Sie die folgenden Informationen haben:

• Eine aktive PingOne-Umgebung, in deren Stückliste die Dienste „PingOne SSO“ und „PingOne MFA“ enthalten sind. Um zu überprüfen, welche Dienste enthalten sind, rufen Sie folgende Seite auf: Umgebung > Eigenschaften.
• Administratorzugriff auf die PingOne-Verwaltungskonsole mit Berechtigungen zur Konfiguration von Absendern, Benachrichtigungsrichtlinien, MFA-Richtlinien, Authentifizierungsrichtlinien und Webhooks.
• Ein Vonage API-Konto (können Sie sich kostenlos anmelden) sowie einen API-Schlüssel, den Sie in Ihrem API-Einstellungen im Vonage-Dashboard.
• Zugang zum Vonage Dashboard sowie Vonage Cloud Runtime mit einem „Advanced“-Abonnement.

Installieren und Konfigurieren des Connectors (Administrator)

Befolgen Sie als Administrator die Schritte in dieser Anleitung, um den Konnektor auf Vonage Cloud Runtime bereitzustellen, die Integration in PingOne zu konfigurieren und zu Verify, ob sie funktioniert.

Bereitstellen des Connectors auf Vonage Cloud Runtime

So stellen Sie eine neue Instanz der Vonage Protection Suite für PingOne bereit:

1. Melden Sie sich bei der Vonage Cloud Runtime Marketplace und klicken Sie auf das Vonage Protection Suite für Ping One Kacheln.

2. Wählen Sie im Menü auf der rechten Seite die Option API-Schlüssel für den Sie den Connector bereitstellen möchten. Wenn Ihr Account nur einen API-Schlüssel hat, wird dieser Schritt automatisch übersprungen.
3. Klicken Sie auf Eine neue Instanz bereitstellen.

4. Wählen Sie eine Region für die Instanz aus und geben Sie einen eindeutigen, prägnanten Instanznamen ein.

5. Wählen Sie Standard als Konfigurationstyp.
6. Klicken Sie auf Weiter.

7. Nehmen Sie folgende Einstellungen vor:

   • Vonage-Nummer (optional): Sofern konfiguriert, wird diese Nummer als Absender-ID für SMS verwendet. Geben Sie die Nummer im E.164-Format ohne das + Zeichen. Wenn Sie keine Zahl eingeben, verwendet der Konnektor die konfigurierte Markenname. Diese Einstellung gilt nicht für Sprachanrufe – die Anrufernummer wird von Vonage Verify zufällig ausgewählt.
   • Markenname (erforderlich): Geben Sie den Markennamen ein, um ihn in den Text der SMS-Nachricht aufzunehmen. Diese Einstellung gilt nicht für Sprachanrufe.
   • Fallback für Sprachanrufe (erforderlich): Aktivieren Sie diese Option, um die Zustellung per Sprachanruf erneut zu versuchen, falls die SMS-Zustellung fehlschlägt.

8. Klicken Sie auf Weiter um die Instanz bereitzustellen.

Konfigurieren Sie den Connector

Starten Sie nach der Bereitstellung des Konnektors dessen Verwaltungsapplication, um Sicherheitsrichtlinien zu konfigurieren und Authentifizierungstoken zu generieren.

Starten Sie die Admin-Anwendung

1. Gehen Sie zum Code bereitstellen Registerkarte und starten Sie die vorhandene Instanz.

2. Authentifizieren Sie sich mit den Vonage-Anmeldeinformationen, indem Sie auf die Schaltfläche Identität mit Vonage verifizieren Taste.

Registerkarte „Dashboard“

Die Dashboard Die Registerkarte bietet einen Echtzeit-Überblick über die OTP-Übermittlung und die Authentifizierungsaktivitäten.

Zähler

Die Zähler In diesem Abschnitt werden die folgenden Kennzahlen angezeigt:

• Gesamtzahl der SMS: Gesamtzahl der SMS-Versandversuche, einschließlich erfolgreicher und fehlgeschlagener Versuche.
• Erfolg mit SMS: Anzahl der erfolgreich zugestellten SMS.
• SMS blockiert: Anzahl der von Identity Insights oder Fraud Defender blockierten SMS-Zustellungen.
• Gesamtstimmenzahl: Gesamtzahl der Versuche, Sprachnachrichten zu übermitteln, einschließlich erfolgreicher und fehlgeschlagener Versuche.
• Erfolg mit der Stimme: Anzahl der erfolgreichen Sprachübermittlungen.
• Stimme gesperrt: Anzahl der blockierten Sprachübertragungen.

Jüngste OTP-Aktivitäten

Die Jüngste OTP-Aktivitäten In diesem Abschnitt werden die 10 letzten OTP-Zustellungen für alle Token angezeigt:

• Zeitstempel: Zeitpunkt, zu dem die Zustellung versucht wurde.
• Reiseziel: Die Zielrufnummer wurde unterdrückt.
• Kanal: Vertriebskanal, entweder SMS oder VOICE.
• Status: Lieferstatus, wie z. B. SUCCESS, FAILED, oder FLAGGED.
• Beschreibung: Ausführliche Begründung für einen Fehler oder eine Warnmeldung. Klicken Sie auf die Auge Symbol, um die Beschreibung anzuzeigen.
• Latenz: Für die Ausführung der Übertragung benötigte Zeit in Millisekunden.
• Token-Name: Name, der dem Token bei seiner Erstellung zugewiesen wurde.

Aktuelle Autorenereignisse

Die Aktuelle Autorenereignisse In diesem Abschnitt werden die 20 letzten erfolgreichen Verifizierungsvorgänge angezeigt, die von PingOne über den konfigurierten Webhook empfangen wurden (siehe den Konfigurieren eines PingOne-Webhooks für Verifizierungsereignisse) Abschnitt.

Der Anschluss zeichnet nur auf OTP Check Success Ereignisse. Fehlgeschlagene und nicht zusammenhängende Ereignisse werden nicht gespeichert.

In diesem Abschnitt werden folgende Informationen angezeigt:

• Zeitstempel: Zeitpunkt, zu dem PingOne die Veranstaltung veröffentlicht hat.
• Token-Name: Name, der dem Token bei seiner Erstellung zugewiesen wurde.
• Veranstaltung: PingOne-Ereignistyp, dargestellt als OTP Check Success.
• Ergebnis: Ergebnis der Überprüfung. Der Konnektor protokolliert nur Ereignisse mit einem SUCCESS Ergebnis.
• Benutzer: PingOne-Benutzerkennung.
• Korrelation: Referenz, die zur Zuordnung des Verifizierungsvorgangs zur ursprünglichen OTP-Übermittlung verwendet wird.

Registerkarte „Token“

Die Wertmarken Auf der Registerkarte werden alle generierten Token mit ihrem aktuellen Status angezeigt:

Ein Token kann einen der folgenden Status haben:

• Aktiv: Das Ticket ist gültig und kann verwendet werden.
• Nachfrist: Das Token wurde durch ein neueres Token ersetzt. Beide Token behalten während einer 24-stündigen Übergangsphase ihre Gültigkeit.
• Abgelaufen: Das Token ist abgelaufen.
• Aufgehoben: Das Token wurde manuell widerrufen und kann nicht mehr verwendet werden.

Token hinzufügen

Wenn Sie ein Token erstellen, nehmen Sie folgende Einstellungen vor:

• Token-Name: Ein für Menschen lesbarer Name, der zur Identifizierung des Tokens in der Admin-Application verwendet wird.
• Ablauf des Tokens: Der Zeitraum, für den das Token gültig bleibt. Zur Auswahl stehen 24 Stunden, 7 Tage, 30 Tage, 90 Tage oder Niemals. Kürzere Gültigkeitsdauern erhöhen die Sicherheit, erfordern jedoch eine häufigere Erneuerung der Token.

Ein Token drehen

Durch die Rotation eines Tokens wird ein neues Token mit demselben Namen und derselben Gültigkeitsdauer wie das ursprüngliche Token generiert. Für das ursprüngliche Token gilt eine 24-stündige Übergangsfrist, während der beide Tokens gültig bleiben. Nutzen Sie die Rotation, um Anmeldedaten regelmäßig ohne Ausfallzeiten zu erneuern.

Die vollständige Vorgehensweise zur Drehung finden Sie unter Verwalten und Wechseln eines Authentifizierungstokens.

Ein Token widerrufen

Durch das Widerrufen eines Tokens wird dieses sofort deaktiviert. Nutzen Sie diese Funktion, wenn ein Token kompromittiert wurde oder nicht mehr benötigt wird. Der Widerruf erfolgt sofort und ist unwiderruflich.

Registerkarte „Konfiguration“

Das Token dient zur Authentifizierung von Anfragen zwischen PingOne und dem Vonage-Konnektor. Das Konfiguration Die Registerkarte enthält die Einstellungen, die für jedes Token der Connector-Instanz gelten.

Ebene 1 – Einblicke in die Identität (vor OTP)

Einblicke in die Identität führt optionale Prüfungen durch, bevor der Konnektor ein OTP sendet. Der Konnektor führt je nach Ergebnis dieser Prüfungen die konfigurierte Aktion aus.

Jede aktivierte Überprüfung wird pro Anfrage in Rechnung gestellt. Numbers Format und Gültigkeit ist kostenlos. Ursprüngliche Netzbetreiber-Abfrage und Aktuelle Netzbetreiber-Abfrage werden pro Anfrage berechnet. Einzelheiten zu den Preisen finden Sie auf der Vonage-Preisseite.

So konfigurieren Sie Identity Insights:

1. Umschalten auf „Identity Insights“ aktivieren an.
2. Wählen Sie eine oder mehrere der folgenden Prüfungen aus:

• Zahlenformat und Gültigkeit: Überprüft das Format der Telefonnummer und stellt fest, ob die Nummer erreichbar ist.
• Ursprüngliche Carrier-Abfrage: Gibt den Netzbetreiber an, dem die Nummer ursprünglich zugewiesen wurde. Bei dieser Überprüfung werden VoIP- und virtuelle Rufnummern gekennzeichnet.
• Aktuelle Netzbetreiber-Abfrage: Gibt den Netzbetreiber an, der die Nummer derzeit bedient. Diese Überprüfung dient zur Erkennung portierter Nummern.

Geografische Filter und Kanalfilter

Länder-Whitelist: Geben Sie ISO 3166-1 Alpha-2-Ländercodes ein (z. B. US, GB, DE). Es werden nur Numbers zugelassen, die diesen Ländern zugeordnet sind. Lassen Sie das Feld leer, um alle Länder zuzulassen.

Wenn eine Nummer markiert ist

Wählen Sie die Maßnahme aus, die ergriffen werden soll, wenn eine Zielnummer bei der Überprüfung als verdächtig markiert wird:

• OTP sperren: Das OTP wird nicht übermittelt. Das blockierte Ereignis wird in Jüngste OTP-Aktivitäten.
• Markieren und ausliefern: Das OTP wurde übermittelt, aber das Ereignis wird im Dashboard mit dem Status „Gelb“ gekennzeichnet.
• Nur Protokoll: Das Prüfergebnis wird protokolliert, es werden jedoch keine Maßnahmen ergriffen. Das OTP wird wie gewohnt übermittelt.

Ebene 2 – Fraud Defender (während der OTP)

Betrugsverteidiger bietet Schutz bei der OTP-Übermittlung, einschließlich Schutz vor SMS-Pumping, künstlich aufgeblähtem Datenverkehr und Datenverkehrs-Burst-Angriffen.

„Fraud Defender Advanced“ ist in „Verify“ enthalten und wird wie folgt angezeigt: Im Lieferumfang enthalten in der Konfiguration des Konnektors. Fraud Defender Premium ist als kostenpflichtiges Upgrade erhältlich. Wenden Sie sich an Ihren Account-Betreuer, um es zu aktivieren.

Im Vonage-Dashboard können Sie die folgenden Schutzmaßnahmen konfigurieren:

• Verkehrsregeln: Legen Sie Sperr- und Zulassungsregeln nach Land oder Präfix fest, um zu steuern, wohin OTPs gesendet werden dürfen (verfügbar mit Fraud Defender Standard, für alle Accounts enthalten).
• AIT-Schutz: Künstlich aufgeblähten SMS-Verkehr erkennen und blockieren. Folgende Schutzstufen stehen zur Verfügung: Keine, (nur Benachrichtigungen, keine Blockierung), Standard (blockiert risikoreichen Datenverkehr, warnt bei allem anderen) und Hoch (blockiert jeglichen potenziell betrügerischen Datenverkehr). Weiterlesen hier.
• SMS-Burst-Schutz: Länderspezifische Drosselungsgrenzen konfigurieren. Weitere Informationen hier.
• Volumenbezogene Warnmeldungen: Erhalten Sie Benachrichtigungen, wenn für ein Land ungewöhnliche Anstiege des Datenverkehrs festgestellt werden. Mehr erfahren hier.

Ratenbegrenzung konfigurieren

Der Connector begrenzt die Anzahl der OTP-Anforderungen, die für einen Benutzer innerhalb eines Zeitfensters von 10 Minuten gestellt werden können. Die Standardgrenze liegt bei fünf Anforderungen pro Benutzer alle 10 Minuten. Dies schützt vor Gebührenbetrug und wiederholten OTP-Anforderungen, die auf denselben Benutzer abzielen.

Zeitlimit für den Kanal konfigurieren

Die Kanal-Zeitüberschreitung legt fest, wie lange der Konnektor auf den ersten Übermittlungskanal wartet, bevor er zum nächsten Kanal übergeht. Sie können einen Wert zwischen 15 und 900 Sekunden festlegen.

Wenn Ausweichlösung für Sprachanrufe Ist diese Option aktiviert, ist dies das Zeitfenster, nach dessen Ablauf eine nicht zugestellte SMS den automatischen Sprachanruf auslöst.

Benutzerdefinierte OTP-Nachrichtenvorlagen

Standardmäßig verwendet der Konnektor die Standardvorlage für Vonage-OTP-Nachrichten für die Zustellung per SMS und Sprachnachricht.

Mit benutzerdefinierten OTP-Nachrichtenvorlagen können Sie diesen Standardtext durch einen eigenen Nachrichteninhalt ersetzen und so den Wortlaut und die Sprache der OTP-Benachrichtigung, die Ihre Endbenutzer erhalten, selbst bestimmen.

Nach der Konfiguration gilt die aktive Vorlage für alle OTP-Übermittlungen auf dieser Connector-Instanz.

Benutzerdefinierte Vorlagen aktivieren

Die Verwaltung benutzerdefinierter Vorlagen ist standardmäßig deaktiviert und muss für Ihren Vonage-Account aktiviert werden. Wenden Sie sich an Ihren Vonage-Kundenbetreuer oder den Vonage-Support, um diese Funktion zu aktivieren.

Nachdem die benutzerdefinierte Vorlagenverwaltung aktiviert wurde, können Sie Vorlagen in der Schablonen Bereich der Admin-Applications.

So aktivieren Sie eine Vorlage für diese Connector-Instanz:

1. Öffnen Sie die Konfiguration tab.
2. Unter Bevorzugte Vorlage, wählen Sie eine Vorlage aus.

Eine Vorlage konfigurieren

Benutzerdefinierte Vorlagen enthalten die folgenden Elemente:

• Vorlage: Ein benannter Container. Der Name ist eine für Menschen lesbare Bezeichnung für die Vorlage. Wenn Ist Standard Wenn diese Option ausgewählt ist, wird die Vorlage verwendet, sofern keine bevorzugte Vorlage konfiguriert ist.
• Auszug: Ein Nachrichtentext, der einem Übermittlungskanal und einer Ländereinstellung zugeordnet ist. Konfigurieren Sie beim Erstellen eines Fragments den Übermittlungskanal (SMS oder Sprachanruf), die Ländereinstellung und den Text (einen Nachrichtentext mit Platzhaltern). Weitere Informationen hier.

Im Text der Nachricht können die folgenden Platzhalter verwendet werden:

• ${code}: Erforderlich. Das OTP, das der Benutzer eingeben muss.
• ${brand}: Für die Connector-Instanz konfigurierter Markenname.
• ${time-limit}: Numerische Gültigkeitsdauer des OTP.
• ${time-limit-unit}: Einheit für die Ablaufdauer, z. B. Minuten.

Zum Beispiel:

Your ${brand} verification code is ${code}. Valid for ${time-limit} ${time-limit-unit}.

Die Zeichenbeschränkungen entsprechen den üblichen SMS-Kodierungsregeln:

• GSM-7 (Standard-Latein): 160 Zeichen pro einzelner SMS, 153 pro Teil bei verketteten SMS.
• UCS-2 (Arabisch, Chinesisch, Kyrillisch usw.): 70 Zeichen pro einzelner SMS, 67 pro Teil bei verketteten SMS.

Vorlagen gelten instanzweit: Eine bevorzugte Vorlage gilt für alle Tokens auf der VCR-Instanz. Einzelne Tokens verfügen nicht über eigene Vorlagenüberschreibungen.

Unterstützte Sprachen

Fragmente werden anhand des Locale-Feldes (z. B. en-us) zugeordnet. Wenn die Locale in der Verify-Anfrage nicht angegeben ist, versucht Vonage, diese anhand der Vorwahl der Telefonnummer zu ermitteln, oder greift andernfalls auf „en-us“ zurück. Siehe die für SMS- und Sprachanruf-Fragmente verfügbaren Locales hier.

Markierte Orte default+custom verfügen über von Vonage erstellte Standardnachrichten und unterstützen benutzerdefinierte Anpassungen. Markierte Ländereinstellungen custom only erfordern ein benutzerdefiniertes Fragment – dafür gibt es keine integrierte Vonage-Nachricht.

Was passiert, wenn keine benutzerdefinierte Vorlage vorhanden ist?

Wenn keine bevorzugte Vorlage festgelegt ist (oder „Keine“ ausgewählt wurde), wird die in Vonage integrierte Standardvorlage für den Kanal und die Ländereinstellung verwendet. Vonage wendet folgende Reihenfolge für die Ausweichvorlagen an:

1. Fragment, das der angeforderten Sprachumgebung in der bevorzugten Vorlage entspricht.
2. Fragment in der Standardvorlage der Instanz, das der Ländereinstellung entspricht.
3. Die von Vonage integrierte Standardnachricht für diese Ländereinstellung und diesen Kanal.
4. Die von Vonage integrierte englische (en-us) Meldung, wenn keine passende Ländereinstellung gefunden wird.

Für die mit custom only, es gibt keine integrierte Ausweichlösung von Vonage: Es ist ein benutzerdefiniertes Fragment erforderlich, andernfalls schlägt die Zustellung für diese Spracheinstellung fehl.

Die generierten Details aufzeichnen

Nachdem Sie die Sicherheitsrichtlinien konfiguriert und ein Authentifizierungstoken generiert haben, notieren Sie sich die folgenden Werte. Sie benötigen diese bei der Konfiguration von PingOne:

• URL des Absender-Endpunkts: Der einzige Endpunkt, der sowohl für die SMS- als auch für die Sprachübermittlung verwendet wird. Der Übermittlungskanal wird im Anfragetext angegeben.
• Ziel-Webhook-URL: Der Endpunkt, der für PingOne-Verifizierungsereignisse verwendet wird.
• Authentifizierungstoken: Die Anmeldeinformationen, die PingOne jeder Anfrage beifügt.
• Name des Auth-Headers: Nur erforderlich bei Verwendung des Authentifizierungsschemas „Custom Header“. Der Standardwert lautet x-ping1-auth.
• Vorlagen für den Request-Body: Die im Dialogfeld zur Token-Generierung angezeigten SMS- und Sprachvorlagen.

PingOne konfigurieren

Nachdem Sie den Connector bereitgestellt und ein Authentifizierungstoken generiert haben, konfigurieren Sie PingOne so, dass die Zustellung von OTPs über den Vonage-Connector erfolgt.

Vonage als benutzerdefinierten Benachrichtigungsanbieter hinzufügen

1. Melden Sie sich bei der PingOne-Verwaltungskonsole an und vergewissern Sie sich, dass Sie sich in der richtigen Umgebung befinden.
2. Gehe zu Einstellungen > Absender.
3. Klicken Sie auf die + Symbol zum Hinzufügen eines Absenders.

4. Für Absendertyp, wählen Sie SMS/Sprache.
5. Für Anbietertyp, wählen Sie Benutzerdefinierter Anbieter.

6. Konfigurieren Sie den Anbieter anhand der Werte, die Sie in der Die generierten Details aufzeichnen Schritt.

• Name: Geben Sie einen aussagekräftigen Namen ein, zum Beispiel Vonage Protection Suite.
• Authentifizierung: Auswählen Inhabertoken und geben Sie das Authentifizierungstoken als „Bearer“-Wert ein. Der Konnektor unterstützt außerdem die Authentifizierung über HTTP Basic, OAuth2-Client-Credentials und benutzerdefinierte Header. Wenn Sie Benutzerdefinierte Kopfzeile, geben Sie den Namen des Auth-Headers als Header-Schlüssel und das Authentifizierungstoken als Header-Wert ein.

7. SMS-Versand konfigurieren:

   1. Stellen Sie die Anfragemethode auf POST.
   2. Fügen Sie die URL des OTP-Zustellungsendpunkts ein.
   3. Wählen Sie „Raw JSON“ als Format für den Request-Body aus.
   4. Fügen Sie die Vorlage für den SMS-Anfragetext ein. Die Vorlage verwendet dynamische Variablen von PingOne, darunter ${to} für die Empfängernummer, ${otp} für den generierten Passcode und ${message} Den vollständigen Text der Nachricht finden Sie hier:

{
 "phoneNumber": "${to}",
 "message": "${message}",
 "otpCode": "${otp}",
 "locale": "${locale}",
 "userId": "${user.username}",
 "channel": "sms"
}

Anmerkung: Um eine Test-SMS oder eine Sprachnachricht zu versenden, ändern Sie die Werte in den folgenden Feldern:

8. Sprachausgabe konfigurieren:

   1. Stellen Sie die Anfragemethode auf POST.
   2. Fügen Sie dieselbe URL für den OTP-Zustellungsendpunkt ein.
   3. Fügen Sie die Vorlage für den Hauptteil der Sprachanfrage unter Verwendung derselben dynamischen Variablen ein:

{
"phoneNumber": "${to}",
"message": "${message}",
"otpCode": "${otp}",
"locale": "${locale}",
"userId": "${user.username}",
"channel": "voice"
}

9. Fügen Sie die Telefonnummern hinzu, die als Absender-IDs verwendet werden sollen, und wählen Sie die entsprechenden SMS- oder Sprachfunktionen aus.
10. Prüfen Sie die Pluszeichen für Zahlen damit die Telefonnummern das vom Konnektor erwartete E.164-Format verwenden.

11. Klicken Sie auf Speichern Sie.

Weitere Informationen finden Sie unter Konfigurieren eines benutzerdefinierten Benachrichtigungsanbieters für PingOne.

Den Anbieter „Vonage“ mit einer Benachrichtigungsrichtlinie verknüpfen

1. Gehen Sie in der PingOne-Verwaltungskonsole zu Benutzererfahrung > Benachrichtigungsrichtlinien.
2. Bearbeiten Sie die Standard Richtlinie oder klicken Sie auf + Richtlinie hinzufügen um eine neue Richtlinie zu erstellen.
3. Unter SMS-Anbieter, wählen Sie Ihren benutzerdefinierten Vonage-Anbieter aus der Dropdown-Liste aus.
4. Unter Sprachdienstleister, wählen Sie Ihren benutzerdefinierten Vonage-Anbieter aus der Dropdown-Liste aus.
5. Konfigurieren Sie die Priorität der Anbieter und gegebenenfalls die länderspezifischen Routing-Regeln nach Bedarf.
6. Klicken Sie auf Speichern Sie.

Weitere Informationen finden Sie unter Benachrichtigungsrichtlinien.

Aktivieren Sie SMS und Sprachnachrichten in den MFA-Einstellungen und der MFA-Richtlinie

MFA-Einstellungen konfigurieren

1. Gehe zu Authentifizierung > MFA.
2. Öffnen Sie MFA-Einstellungen indem Sie auf die Zahnrad Symbol.
3. Satz MFA-Status für neue Benutzer zu Aktiviert, daher wird MFA für neu angelegte Benutzer automatisch aktiviert.
4. Klicken Sie auf Speichern Sie.

MFA-Richtlinie konfigurieren

Nachdem der Anbieter „Vonage“ einer Benachrichtigungsrichtlinie zugewiesen wurde, stehen die Optionen „SMS“ und „Sprache“ in der MFA-Richtlinie zur Verfügung.

1. Gehe zu Authentifizierung > MFA > MFA-Richtlinien.
2. Bearbeiten Sie die Standard-MFA-Richtlinie indem Sie auf die Bleistift Symbol oder eine neue Richtlinie erstellen.
3. Unter Zulässige Authentifizierungsmethoden, wählen Sie SMS und Stimme.
4. Unter Benachrichtigungsrichtlinie, wählen Sie die Benachrichtigungsrichtlinie aus, die Sie in der Den Anbieter „Vonage“ mit einer Benachrichtigungsrichtlinie verknüpfen Schritt.
5. Klicken Sie auf Speichern Sie.

Weitere Informationen finden Sie unter:

• Konfigurieren einer MFA-Richtlinie
• MFA-Einstellungen konfigurieren

MFA in einer Authentifizierungsrichtlinie vorschreiben

Konfigurieren Sie eine Authentifizierungsrichtlinie, die nach der Anmeldung eine MFA erfordert, um den OTP-Versandprozess auszulösen:

1. Gehe zu Authentifizierung > Authentifizierung.
2. Den bestehenden Eintrag bearbeiten Multi_Factor Richtlinie auswählen oder eine neue Richtlinie hinzufügen.
3. Bitte bestätigen Sie, dass Anmeldung ist mit Benutzername und Passwort konfiguriert.
4. Füge einen zweiten Schritt vom Typ Mehrfaktor-Authentifizierung.
5. Wählen Sie die MFA-Richtlinie aus, die Sie in der MFA-Richtlinie konfigurieren Schritt.
6. Weisen Sie die Authentifizierungsrichtlinie den Applications zu, die eine telefonbasierte MFA erfordern.

Weitere Informationen finden Sie unter Hinzufügen eines Schritts zur Multi-Faktor-Authentifizierung.

Konfigurieren eines PingOne-Webhooks für Verifizierungsereignisse

Der benutzerdefinierte Benachrichtigungsanbieter übernimmt die Zustellung des OTP, während der Webhook das Ergebnis der Verifizierung an den Connector zurückgibt. PingOne generiert und validiert das OTP.

Wenn ein Benutzer den richtigen Code eingibt, protokolliert PingOne das Ergebnis der OTP-Prüfung als Audit-Ereignis und sendet es asynchron an die Event-Webhook-URL. Der Konnektor empfängt dieses Ereignis zusammen mit der ursprünglichen OTP-Zustellung, wodurch die Aktuelle Autorenereignisse Anzeige und Bereitstellung einer lückenlosen Transparenz des Konvertierungsprozesses.

Die Konfiguration des Webhooks ist optional und wird vom Kunden aktiviert:

1. Vergewissern Sie sich in der PingOne-Verwaltungskonsole, dass Sie sich in der richtigen Umgebung befinden.
2. Gehe zu Integrationen > Webhooks.
3. Klicken Sie auf Webhook hinzufügen.
4. Geben Sie einen Namen ein, zum Beispiel Vonage Verification Events.
5. Für Ziel-URL, geben Sie die URL des Ereignis-Webhooks ein, die Sie im Die generierten Details aufzeichnen Schritt. Der Endpunkt akzeptiert HTTPS POST Anfragen.
6. Für Format, wählen Sie Format der Ping-Aktivität. Dies ist das generische JSON-Format, das von der PingOne-API für Audit-Aktivitäten verwendet wird, und es ist das richtige Format für den Vonage-Endpunkt.
7. Unter Veranstaltungstypen, suchen und auswählen OTP-Prüfung erfolgreich. Der Konnektor nutzt dieses Ereignis, um eine erfolgreiche Überprüfung zu bestätigen. Andere Ereignistypen werden ignoriert und sicher quittiert, sodass die Auswahl weiterer Ereignisse unnötige Daten mit sich bringt.
8. Verwenden Sie optional Zusätzliche Bedingungen um Ereignisse nach Tags, Applications oder Zielgruppen einzugrenzen. Grenzen Sie den Umfang so ein, dass nur die relevanten Verifizierungsereignisse gesendet werden, um unnötige Daten zu vermeiden.
9. Optional können Sie eine Nutzlastgrenze nach Größe in KB oder nach Anzahl der Ereignisse. Wenn Sie kein Limit für die Datenmenge festlegen, fügt PingOne bis zu 500 Ereignisse in jede Datenmenge ein.
10. Speichern Sie den Webhook und aktivieren Sie ihn.

Weitere Informationen finden Sie unter:

• Einen Webhook erstellen oder bearbeiten
• Ereignisse in der Audit-Berichterstattung

Verify the connection of the connector

Nachdem Sie den benutzerdefinierten Benachrichtigungsanbieter und den Webhook in PingOne konfiguriert haben, Verify, ob die Verbindung zwischen PingOne und dem Vonage-Konnektor aktiv ist:

1. Gehen Sie in der PingOne-Verwaltungskonsole zu Einstellungen > Absender.
2. Öffnen Sie den benutzerdefinierten Anbieter „Vonage“.
3. Verwenden Sie die integrierte Testfunktion, um eine Test-SMS an eine echte Telefonnummer zu senden.
4. Bestätigen Sie, dass Sie die SMS erhalten haben.
5. Vergewissern Sie sich im Connector-Dashboard, dass die Testübermittlung unter Jüngste OTP-Aktivitäten mit einer SUCCESS Status.
6. Gehen Sie in PingOne zu Integrationen > Webhooks und überprüfen Sie, ob der Vonage-Webhook aktiviert ist und ordnungsgemäß funktioniert.

Testen Sie die Integration

Verifyen Sie vor der Inbetriebnahme den gesamten Authentifizierungsablauf von Anfang bis Ende mit einem Testbenutzer.

Bevor Sie beginnen

Stellen Sie sicher, dass Sie über eines der folgenden Elemente verfügen:

• An application under Verbindungen > Applications mit der MFA-fähigen Authentifizierungsrichtlinie, die von der MFA in einer Authentifizierungsrichtlinie vorschreiben Schritt. Alternativ können Sie das PingOne-Self-Service-Portal nutzen.
• Ein Testbenutzer unter Verzeichnis > Benutzer mit aktivierter MFA und einer Telefonnummer, auf der SMS-Nachrichten und Anrufe empfangen werden können.

Test mit einem Browser

Dies ist die empfohlene Prüfmethode.

1. Öffnen Sie ein privates oder Inkognito-Browserfenster.
2. Rufen Sie die PingOne-Autorisierungs-URL für Ihre Testanwendung auf:

https://auth.pingone.com/{environmentId}/as/authorize?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope=openid

Ersetzen Sie {environmentId}, {clientId}und {redirectUri} mit den Werten aus den Registerkarten „Übersicht“ und „Konfiguration“ der Applications.

3. Geben Sie auf der PingOne-Anmeldeseite den Benutzernamen und das Passwort des Testbenutzers ein.
4. Wenn PingOne den Benutzer zur MFA auffordert, wählen Sie „SMS“ oder „Anruf“. Falls der Testbenutzer noch keine Telefonnummer für die MFA registriert hat, fordert PingOne ihn auf, die Registrierung abzuschließen. Geben Sie die Telefonnummer ein, wenn Sie dazu aufgefordert werden.
5. Warten Sie, bis Vonage das OTP über den von Ihnen konfigurierten benutzerdefinierten Anbieter übermittelt hat.
6. Geben Sie das OTP auf dem PingOne-Bildschirm ein.
7. Nach erfolgreicher Überprüfung werden Sie mit einem Autorisierungscode an die Redirect-URI der Anwendung weitergeleitet.

Test über das PingOne-Self-Service-Portal

1. Rufen Sie das PingOne-Self-Service-Portal für Ihre Umgebung auf:

https://apps.pingone.com/{environmentId}/myaccount/

2. Ersetzen Sie {environmentId} mit Ihrer PingOne-Umgebungs-ID.
3. Melden Sie sich mit den Zugangsdaten des Testnutzers an.
4. Wenn PingOne den Benutzer zur MFA auffordert, führen Sie die MFA-Überprüfung durch.
5. Vonage übermittelt das OTP.

Ergebnisse bestätigen

Verify nach Abschluss des Authentifizierungsvorgangs die Ergebnisse im Vonage-Dashboard und im Connector-Dashboard:

Vonage Dashboard

1. Gehen Sie im Vonage-Dashboard zu Protokolle > SMS-Protokolle oder Sprachprotokolle.
2. Vergewissern Sie sich, dass das Einmalpasswort an die Telefonnummer des Testnutzers gesendet wurde.
3. Überprüfen Sie den Lieferstatus, die Übertragungszeit und die Informationen zum Netzbetreiber.

Connector-Dashboard

1. Vergewissern Sie sich, dass die Lieferung in Jüngste OTP-Aktivitäten.
2. Wenn Sie den PingOne-Webhook konfiguriert haben, stellen Sie sicher, dass ein OTP Check Success Das Ereignis erscheint in Aktuelle Autorenereignisse.

Ein erfolgreicher Test bestätigt den folgenden End-to-End-Ablauf:

PingOne > Vonage connector > SMS or voice delivery > user enters the OTP > PingOne validates the OTP > verification event returned to Vonage

Verwalten und Wechseln eines Authentifizierungstokens

Das Authentifizierungstoken sichert die Kommunikation zwischen Ihrer PingOne-Umgebung und dem Vonage-Konnektor. Als bewährte Sicherheitsmaßnahme können Sie das Token in der Admin-Application oder programmgesteuert mithilfe der Token-Management-API aktualisieren.

Durch das Erneuern eines Tokens wird ein neues Token generiert und eine 24-stündige Übergangsfrist für das vorherige Token ausgelöst. Während dieses Zeitraums bleiben beide Tokens gültig, sodass Sie die PingOne-Konfiguration aktualisieren können, ohne die OTP-Bereitstellung zu unterbrechen.

Ein Token im Admin-Panel rotieren

1. Melden Sie sich mit Ihrem Vonage-Admin-Account im Admin-Panel an.
2. Öffnen Sie die Token-Liste.
3. Suchen Sie das Symbol, das Sie drehen möchten.
4. Klicken Sie auf Drehen.
5. Klicken Sie auf Bestätigen Sie.
6. Ihr neues Token wird angezeigt. Kopieren Sie das neue Token und bewahren Sie es sicher auf. Das neue Token wird nur einmal angezeigt.
7. Vergewissern Sie sich, dass das neue Token in der Token-Liste angezeigt wird. Das alte Token ist mit Rotated Status und bleibt während der 24-stündigen Nachfrist gültig. Nach Ablauf der Nachfrist erlischt er.

Ein Token über die API rotieren

Sie können Authentifizierungstoken auch programmgesteuert mithilfe der Token-Management-API rotieren.

Die OpenAPI-Spezifikation und die Postman-Sammlung stehen als Referenz in der Artikel in der Knowledge Base zur Vonage Protection Suite für PingOne > Schritt 6 > Ein Token rotieren – über die API.

Authentifizierung

Die Endpunkte der Token-Management-API verwenden die HTTP-Basic-Authentifizierung. Fügen Sie bei jeder Anfrage Ihren Vonage-API-Schlüssel und Ihr API-Geheimnis ein, getrennt durch einen Doppelpunkt und Base64-kodiert:

Basic base64(API_KEY:API_SECRET)

Token-Liste abrufen

Bevor Sie ein Token rotieren, rufen Sie dessen UUID über den Endpunkt „List Tokens“ ab:

GET /admin/tokens

Der Endpunkt gibt eine Zuordnung der mit der Connector-Instanz verknüpften Token zurück. Jeder Eintrag enthält die Token-ID, den Namen, den Status, die Claims und die Nutzungszähler.

Das Token drehen

Bei der Token-Rotation wird ein neues Token mit denselben Ansprüchen und einem neuen Zeitstempel ausgegeben, und es beginnt die 24-stündige Karenzfrist für das vorherige Token, nach deren Ablauf dieses ungültig wird.

Senden Sie eine Anfrage an den Rotations-Endpunkt:

POST /admin/rotate-token

Geben Sie im Request-Body die UUID an, die von GET /admin/tokens:

{
"id": "<token-uuid>"
}

Ersetzen Sie "<token-uuid>" mit der UUID des Tokens, das Sie rotieren möchten.

Eine erfolgreiche Anfrage gibt ein 200 OK Antwort, die das neu signierte Token und dessen Kennung enthält. Der Token-Wert wird nur einmal zurückgegeben.

Die URL des OTP-Übermittlungsendpunkts, die URL des Ereignis-Webhooks und der Name des Authentifizierungs-Headers ändern sich nicht, wenn Sie ein Token rotieren. Sie können diese Werte wie folgt abrufen:

GET /admin/config

Das vollständige Antwortschema finden Sie in der OpenAPI-Spezifikation.

PingOne nach dem Wechseln eines Tokens aktualisieren

Nachdem Sie ein Token rotiert haben, aktualisieren Sie die Anmeldedaten in PingOne:

1. Gehe zu Einstellungen > Absender.
2. Bearbeiten Sie den benutzerdefinierten Anbieter „Vonage“.
3. Ersetzen Sie im Abschnitt „Authentifizierung“ die vorhandenen Anmeldedaten durch das neue Token:

• Wenn Sie die Bearer-Token-Authentifizierung verwenden, aktualisieren Sie den Wert „bearer“.
• Wenn Sie das Authentifizierungsschema „Benutzerdefinierter Header“ verwenden, aktualisieren Sie den Wert des benutzerdefinierten Headers.

4. Wenn sich der Webhook mithilfe des Tokens authentifiziert, gehen Sie zu Integrationen > Webhooks, öffnen Sie den Vonage-Webhook und aktualisieren Sie dessen Anmeldedaten.

Wird PingOne nicht aktualisiert, schlägt die Zustellung des OTP fehl, sobald das alte Token ungültig wird (nach Ablauf der 24-stündigen Nachfrist).

Fehlersuche

Sollte die Zustellung oder Überprüfung des OTP nicht wie erwartet funktionieren, führen Sie bitte die folgenden Überprüfungen durch:

• Verify the connector credentials: Stellen Sie sicher, dass die URL des OTP-Zustellungsendpunkts, die URL des Ereignis-Webhooks, das Authentifizierungsschema und das Authentifizierungstoken in PingOne mit den Werten aus dem Dialogfeld zur Token-Generierung übereinstimmen.
• Überprüfen Sie die Benachrichtigungsrichtlinie: Stellen Sie sicher, dass in der Benachrichtigungsrichtlinie der benutzerdefinierte Anbieter „Vonage“ als SMS- und Sprachdienstanbieter ausgewählt ist und dass die MFA-Richtlinie mit dieser Benachrichtigungsrichtlinie verknüpft ist. Überprüfen Sie die Priorität der Anbieter, falls mehrere Anbieter konfiguriert sind.
• MFA-Konfiguration: Stellen Sie sicher, dass SMS und Sprachanrufe in der MFA-Richtlinie aktiviert sind, dass die MFA-Richtlinie mit der Authentifizierungsrichtlinie verknüpft ist und dass die MFA für den Benutzer aktiviert ist.
• Das Dashboard überprüfen: Überprüfen Sie im Connector-Dashboard Folgendes: Jüngste OTP-Aktivitäten für FAILED oder FLAGGED Ereignisse. Klicken Sie auf das Beschreibungssymbol, um die Fehlerdetails anzuzeigen.
• Ergebnisse von „Identity Insights“ prüfen: Falls der Konnektor den OTP blockiert, prüfen Sie, ob Identity Insights die Zielnummer markiert hat. Passen Sie zu Testzwecken gegebenenfalls die Aktion „Wenn Nummer markiert ist“ an (Blockieren > Markieren und zustellen oder nur protokollieren).
• Überprüfen Sie das Zahlenformat: Vergewissern Sie sich, dass die Pluszeichen für Zahlen Die Einstellung in der Konfiguration des benutzerdefinierten Anbieters entspricht dem vom Konnektor erwarteten E.164-Format.

Ausführliche Informationen zur End-to-End-Verfolgung von Anfragen, zu Protokollspeicherorten und zum Support finden Sie unter Artikel in der Knowledge Base zur Vonage Protection Suite für PingOne.

Der gesamte OTP-Lebenszyklus – Verfolgung einer einzelnen Anfrage

Ausführliche Anweisungen zur Nachverfolgung einer OTP-Anfrage über PingOne, Vonage Cloud Runtime und Vonage Verify finden Sie in der Artikel in der Knowledge Base zur Vonage Protection Suite für PingOne.

Referenz zu Fehlercodes und Identitätsinformationen

Wenn eine OTP-Anfrage blockiert wird, fehlschlägt oder markiert wird, können Sie den strukturierten Fehler im Dashboard unter Jüngste OTP-Aktivitäten Abschnitt. Klicken Sie auf die Auge Symbol neben einem BLOCKED, FAILED, oder FLAGGED Ereignis, um die Fehlerdetails anzuzeigen.

Anschluss-Fehlercodes

Zu den Verbindungsfehlern können gehören:

• errorCode: Der Fehlercode des Steckers.
• errorSummary: Eine für Menschen verständliche Beschreibung des Fehlers.
• errorId: Die Anfragekorrelations-ID dient dazu, die Anfrage in den Connector-Protokollen zu finden, und kann dem Vonage-Support mitgeteilt werden.
• errorCauses: Details zu den Feldern, bei denen die Validierung fehlgeschlagen ist.

Identity Insights-Untercodes

Wenn die Fehlermeldung Folgendes enthält Identity Insight flagged: <reasons>die reasons Das Feld enthält einen oder mehrere der folgenden Untercodes. Es können mehrere Gründe angegeben werden, wenn mehr als eine Prüfung dieselbe Nummer markiert.

Weitere Ressourcen zur Fehlerbehebung

Ausführliche Anweisungen zur Nachverfolgung einer OTP-Anfrage in den einzelnen Phasen des Zustellungs- und Verifizierungsprozesses finden Sie unter Artikel in der Knowledge Base zur Vonage Protection Suite für PingOne. Der Artikel enthält außerdem eine Kurzübersicht über die Navigationspfade von PingOne.

Brauchen Sie Hilfe?

Wenn Sie das Problem mit Hilfe des obigen Abschnitts zur Fehlerbehebung nicht beheben können, wenden Sie sich an Vonage Hilfe-Center. Wählen Sie bei der Einreichung einer Anfrage das Formular mit dem Titel Verwendung von Vonage-Konnektoren und wählen Sie dann Ihren Anschluss aus > Verwendung der Vonage Protection Suite für PingOne Das Ticket wird also direkt an den PingOne Connector-Support weitergeleitet.

Was Sie angeben sollten (für eine schnellere Klärung)

Erfahrungen mit der OTP-Zustellung

Endbenutzer müssen den Konnektor nicht konfigurieren. Nachdem ein Administrator die Einrichtung in der Connector installieren und konfigurieren In diesem Abschnitt übernimmt der Vonage-Konnektor die Übermittlung des OTP auf transparente Weise. Aus Sicht des Endnutzers bleibt der Authentifizierungsablauf identisch mit seiner bisherigen PingOne-Erfahrung:

1. Der Benutzer startet einen Authentifizierungsablauf in einer durch PingOne geschützten Anwendung, beispielsweise bei der Anmeldung, der MFA-Registrierung oder dem Self-Service-Zugriff auf einen Account.
2. PingOne fordert den Nutzer auf, sich per Telefon zu Verify.
3. Der Benutzer wählt aus SMS oder Stimme.
4. Der Vonage-Konnektor übermittelt das OTP über „Vonage Verify“ an das Telefon des Benutzers.
5. Der Benutzer gibt das OTP in der PingOne-Benutzeroberfläche ein.
6. PingOne überprüft das OTP und schließt die Authentifizierung ab.

Der Vonage-Konnektor läuft während dieses gesamten Vorgangs im Hintergrund. Wenn Ausweichlösung für Sprachanrufe Wenn diese Funktion aktiviert ist und die SMS-Zustellung fehlschlägt, versucht der Konnektor erneut, die Nachricht per Sprachanruf zu übermitteln, ohne dass der Benutzer etwas tun muss.

Weitere Lektüre

• Einblicke in die Identität
• Betrugsverteidiger
• Artikel in der Knowledge Base zur Vonage Protection Suite für PingOne