API-Schlüssel

• Nicht definierter Typ

Training

A API-Schlüssel Ermöglicht es einer Anwendung oder Automatisierung, mit den Rechten eines zugehörigen Kontos auf immersive Dienste zuzugreifen. Es vermeidet die Aufforderung nach Passwort und MFA-Code bei jeder Programmausführung.

Dieses Tutorial erklärt, wie man Schlüssel in RestFrontage erstellt, aufruft, erweitert und löscht. Es ist für den Administrator gedacht Cerebrate. Beispiele für WebAPI-Aufrufe und Code-Authentifizierung werden in einem separaten Artikel behandelt.

Die Screenshots zeigen die RestFrontage-Oberfläche in einer Demo-Umgebung. Die gezeigten Schlüssel öffnen keinen Zugriff auf Ihre Umgebung.

1. Verständnis des Prinzips

1.1 Eine Identität für eine Anwendung

Eine Überwachungs-App, ein Import-Tool oder eine geplante Aufgabe muss auf Immersive zugreifen können, ohne darauf zu warten, dass jemand einen Code auf seinem Handy eingibt. Ein API-Schlüssel wird verwendet, um diesen automatisierten Zugriff zu authentifizieren.

Jeder Schlüssel ist assoziiert mit:

• a Anwendungsname, was es ermöglicht, seine Verwendung zu identifizieren;
• a Immersiver Account, deren Rechte es nutzt;
• a Gültigkeitsdauer, mit einem Start- und einem Enddatum;
• Ein Staat An oder aus.

Der Schlüssel gewährt nicht automatisch alle Rechte. Wenn das zugehörige Konto eine Ressource ansehen, aber nicht verändern kann, bleibt die Anwendung dieser Einschränkung unterworfen.

flowchart TD
    A["L’application présente son nom et sa clé API"] --> B["Vérifier la clé, ses dates et le compte associé"]
    B -->|Échec| R["Accès refusé"]
    B -->|Succès| D["Appliquer les droits du compte à la demande"]
    D -->|Droits insuffisants| F["Opération refusée"]
    D -->|Droits suffisants| G["Opération autorisée"]

1.2 Was hat das mit MFA zu tun?

MFA schützt interaktive Logins über Benutzername und Passwort. Der API-Schlüssel ist ein weiteres Authentifizierungsmittel, das für Programme gedacht ist: Für die Nutzung ist kein TOTP-Code erforderlich..

Daher ist es nicht notwendig, das Konto von MFA auszunehmen, damit eine Anwendung seinen API-Schlüssel verwenden kann. Der übliche Login dieses Kontos bleibt dem im Immersive gewählten MFA-Modus unterworfen.

1.3 Wählen Sie das verknüpfte Konto aus

Am besten verwenden Sie eine Dediziertes App-Konto, mit nur den notwendigen Rechten. In diesem Leitfaden, Werkstattbetreuung Benutzt API-Konto – Überwachung.

Der Anwendungsname ist weder ein Benutzer noch eine Berechtigungsgruppe. Es ist das zugehörige Konto, das die Rechte trägt. Die Zuordnung eines Schlüssels mit Cerebrate würde ihm Cerebrate-Rechte verleihen; diese Wahl sollte für Anwendungen reserviert sein, die ihn wirklich benötigen.

Das Konto muss weiterhin verfügbar sein: Es darf nicht deaktiviert, gelöscht, abgelaufen oder vorübergehend gesperrt werden. Ein noch gültiger Schlüssel umgeht die Nichtverfügbarkeit des Kontos nicht.

2. Open-Key-Management

Verbinden Sie sich mit RestFrontage mit Cerebrate, öffne Sicherheit, dann API-Schlüssel, erkennbar an ihrem Schlüsselsymbol. Die Adresse der Seite ist /Security/ApiKeys.

In der aktuellen Benutzeroberfläche sind diese Seite und ihre Verwaltungsoperationen Cerebrate vorbehalten.

Die Seite zeigt die Anzahl der Schlüssel und die Anzahl der aktiven Schlüssel an. Jede Zeile zeigt den Anwendungsnamen, das zugehörige Konto, die letzten Zeichen des Schlüssels, seine Gültigkeitsdauer und seinen Ursprung an. Die letzten Zeichen helfen, die Schlüssel zu unterscheiden; sie ersetzen nicht den vollen Wert.

Das Feld Finde eine App oder ein Konto Filtere die Liste. Klicke auf eine Zeile, um den Datensatz zu öffnen.

2.1 Verständnis von Zuständen

Status	Bedeutung
Aktiv	Der Schlüssel ist aktiviert, seine Gültigkeitsdauer ist im Gange und das zugehörige Konto ist verfügbar. Kontorechte gelten weiterhin für jede Transaktion.
Demnächst	Das Startdatum ist noch nicht erreicht. Der Schlüssel kann noch nicht verwendet werden.
Abgelaufen	Das Enddatum wurde erreicht oder überschritten. Der Schlüssel kann nicht mehr authentifiziert werden.
Behindert	Der Schlüssel ist nicht aktiviert. Er kann nicht benutzt werden.
Konto nicht verfügbar	Das verknüpfte Konto wird nicht gefunden, deaktiviert, gelöscht, abgelaufen oder vorübergehend gesperrt.

Der Status fasst die Situation zusammen, wenn die Liste geladen wird. Aktualisieren Sie die Seite nach einem externen Eingriff oder um eine gerade erreichte Frist zu überprüfen. Mehrere Ursachen können koexistieren; überprüfen Sie außerdem die Daten und das zugehörige Konto.

2.2 Zwei Ursprünge in derselben Liste

Ursprung	Verwaltung vom Standort aus möglich
Basissicherheit	Schlüssel, der aus dieser Schnittstelle erstellt wurde. Du kannst die Karte ansehen, den Wert anzeigen, wenn verfügbar, das Enddatum verlängern und löschen.
App-Einstellungen · Schreibgeschützt	Schlüssel, der in der Serverkonfiguration definiert ist. Sie können die Karte und den verfügbaren Wert ansehen. Das Ändern oder Löschen liegt in der Verantwortung des Bedieners in der Konfiguration.

Konfigurationsschlüssel werden nicht automatisch in standortverwaltete Schlüssel umgewandelt. Die beiden Ursprünge können koexistieren.

3. Erstellen Sie einen API-Schlüssel

3.1 Füllen Sie den Antrag aus und wählen Sie Ihr Konto aus

1. Klick Erstellen Sie einen API-Schlüssel.
2. In App-Name, geben Sie einen bekannten Namen ein, wie zum Beispiel Werkstattbetreuung.
3. Klicken Sie auf den Link Wähle einen Benutzer.
4. Im Suchfenster finden Sie das Konto, das Sie verknüpfen möchten, und wählen Sie es aus.
5. Überprüfen Sie, ob ihr Name in Verknüpftes Konto.

Wenn Sie dies auswählen, öffnet ein zweites Fenster, ohne die bereits eingegebenen Informationen zu verlieren. Der Link mit dem Kontonamen ermöglicht es Ihnen dann, vor der Erstellung einen weiteren Benutzer auszuwählen.

3.2 Setze Termine und Speicher

1. Überprüfen Sie die Beginn der Gültigkeit.
2. Wählen Sie das Ende der Gültigkeit, der nach dem Anfang liegt und in der Zukunft liegt.
3. Lass Schlüssel aktiviert auf einen Schlüssel geprüft, der während dieses Zeitraums benutzbar sein soll.
4. Klick Erstellung des Schlüssels.
5. Warte auf die Nachricht Der API-Schlüssel wurde gespeichert.

Die Daten sind in der Browser-Zeitzone. Wenn das Formular geöffnet wird, wird eine Frist von etwa einem Jahr vorgeschlagen; passen Sie es an die tatsächlichen Anforderungen des Antrags an. Um sich auf den zukünftigen Zugriff vorzubereiten, wählen Sie ein späteres Startdatum.

Der Schlüsselwert wird automatisch generiert, sodass Sie kein Passwort erfinden oder MFA für die Anwendung bereitstellen müssen.

4. Ansehen, ansehen und kopieren den Schlüssel

4.1 Offene Eigenschaften

Klicken Sie auf die Schlüsselzeile in der Liste. Die API-Schlüsseleigenschaften Zeigt den App-Namen, das zugehörige Konto, den Ursprungsstatus, den aktivierten Status und die Daten an.

Der Schlüssel ist standardmäßig versteckt, selbst wenn man zu seiner Form zurückkehrt. Die sichtbaren Punkte sind nicht sein Wert und erlauben keine Ableitung seiner Länge.

4.2 Ansehen und dann kopieren

1. Klick Show.
2. Warte, bis der Wert angezeigt wird. Während des Ladens ersetzt eine Animation den Button-Text.
3. Verwenden Sie dasKopier-Symbol rechts vom Feld, um den vollständigen Wert zu kopieren.
4. Füge es in den vom Client-Programm bereitgestellten geschützten Ort ein.
5. Klick Versteck dich Wenn du fertig bist.

Der in dieser Aufnahme sichtbare Schlüssel gehört nur zur Demoumgebung, die für die Illustrationen verwendet wurde. Er wurde nach Abschluss der Aufnahmen gelöscht.

Das Kopier-Symbol erscheint nur, wenn der Schlüssel angezeigt wird. Wenn das Feld zu kurz ist, um den vollen Wert anzuzeigen, verwenden Sie dieses Symbol: Es kopiert den vollständigen Schlüssel. Versteck dich entfernt den Wert vom Bildschirm, löscht aber nicht, was bereits auf die Zwischenablage kopiert wurde.

4.3 Welche Informationen sollten an die Anwendung übermittelt werden?

Der Integrator benötigt die Adresse des immersiven Servers, die Anwendungsname und die vollständiger API-Schlüssel. Der Name entspricht x-app-name und der Schlüssel zu x-api-key in API-Exchanges.

Das Passwort des zugehörigen Kontos und die Codes seiner MFA-Anwendung sind für diesen Schlüsselzugriff nicht erforderlich. Anfragen und Verwaltung von Zugriffstoken werden im WebAPI-Artikel detailliert beschrieben.

5. Verlängerung der Gültigkeitsdauer

Für einen Originalschlüssel Basissicherheit, erlaubt die Verlängerung, denselben Wert zu behalten und das Enddatum zu verlängern.

1. Öffne die Schlüsselkarte.
2. In Erweitern zu, wähle ein Datum, das später als das aktuelle Ende liegt und in der Zukunft liegt.
3. Klick Erweitern.
4. Überprüfen Sie die Nachricht Das Enddatum wurde verlängert. und das neue Datum wurde angezeigt.

Die Erweiterung ändert weder den Anwendungsnamen, das zugehörige Konto noch den Wert des Schlüssels. Sie verkürzt die Gültigkeitsdauer nicht.

Ein abgelaufener Schlüssel kann auf ein zukünftiges Datum verlängert werden. Er wird wieder nutzbar, wenn er aktiviert wird, seine Gültigkeit den Anfang seiner Gültigkeit erreicht hat und das zugehörige Konto verfügbar ist. Eine Verlängerung reaktiviert ein deaktiviertes Konto nicht.

6. Einen Schlüssel in den AppSettings anzeigen

Lagerschlüssel App-Einstellungen · Schreibgeschützt Kommt aus der Serverkonfiguration.

Sie können deren Immobilien öffnen und deren Wert einsehen, wenn sie verfügbar sind. Das Angebot bietet kein Angebot an Erweitern, noch Löschen Sie diesen Schlüssel.

Um sie zu ändern, zu entfernen oder die Deadline zu verlängern, wenden Sie sich an die Person, die die Serverkonfiguration betreibt. Erstellen Sie keinen weiteren Schlüssel in der Annahme, dass er automatisch den AppSettings-Schlüssel ersetzt: Die beiden Zugriffe bleiben getrennt.

7. Einen Schlüssel löschen oder ersetzen

7.1 Entfernen Sie den Zugang, der nicht mehr benötigt wird.

1. Öffne die originale Schlüsselkarte Basissicherheit.
2. Klick Löschen Sie diesen Schlüssel.
3. Überprüfen Sie im Bestätigungsfenster den App-Namen und das Konto.
4. Klick Lösche den Schlüssel zur Bestätigung, oder auf Stornieren um den Zugang aufrechtzuerhalten.
5. Überprüfen Sie die Löschmeldung und das Verschwinden der Zeile aus der Liste.

Die Löschung ist Definitiv. Der damit erhaltene Schlüssel und die Token werden widerrufen: Sie erlauben keinen neuen Zugriff mehr. Daten, die bereits von der Anwendung abgerufen oder kopiert wurden, werden durch diese Aktion nicht gelöscht.

7.2 Einen Schlüssel ersetzen, ohne die beabsichtigte Nutzung zu unterbrechen

Für eine geplante Verlängerung kannst du einen neuen Schlüssel für dieselbe App und dasselbe Konto erstellen, mit einer Gültigkeitsdauer, die sinnvoll ist. Mehrere Schlüssel können für denselben App-Namen koexistieren.

flowchart TD
    A["Créer une nouvelle clé"] --> B["Configurer l’application avec la nouvelle clé"]
    B --> C["Vérifier un accès et les opérations nécessaires"]
    C --> D{"Le fonctionnement est-il confirmé ?"}
    D -->|Non| E["Corriger la configuration ou les droits"]
    E --> C
    D -->|Oui| F["Supprimer l’ancienne clé"]

Finde beide Schlüssel anhand ihrer Daten und letzten Zeichen, damit du den richtigen löschen kannst. Der neue Schlüssel deaktiviert den alten Schlüssel nicht automatisch.

8. Lösung gemeinsamer Herausforderungen

8.1 Das ausgewählte Konto ist deaktiviert

Die Erstellung wird abgelehnt und eine Nachricht weist auf das betroffene Konto hin. Im folgenden Beispiel, Eric T. ist behindert.

Wähle ein aktives Konto, das für die App geeignet ist. Wenn du wirklich möchtest, dass das ausgewählte Konto reaktiviert wird, mach es zuerst auf der Benutzerkarte und beginne dann, es neu zu erstellen. Aktiviere ein deaktiviertes Konto nicht freiwillig wieder, nur damit die Nachricht verschwindet.

Ein Validierungsfehler erzeugt den Schlüssel nicht. Das Formular behält die eingegebenen Informationen, um eine Korrektur zu ermöglichen.

8.2 Der Schlüssel existiert, aber die App greift nicht auf die Daten zu.

Überprüfen Sie nacheinander den Status des Schlüssels, seine Daten, das zugehörige Konto, den Anwendungsnamen und den vollständigen kopierten Wert. Überprüfen Sie außerdem, ob die Anwendung den korrekten Immersive Server verwendet.

Wenn die Authentifizierung erfolgreich ist, aber eine Operation abgelehnt wird, überprüfen Sie die Die Rechte des assoziierten Kontos an der angeforderten Ressource. Das Erstellen eines neuen Schlüssels für dasselbe Konto gewährt ihm keine weiteren Rechte.

8.3 Weitere Botschaften und Situationen

Lage	Maßnahmen werden ergriffen
Abgelaufenes Konto	Überprüfe, ob die Nutzung in der Benutzerdatei verlängert werden sollte, oder wähle ein anderes aktives Konto aus.
Enddatum abgelehnt	Wenn du sie erstellst, wähle ein zukünftiges Ende, das später als der Anfang liegt. Für eine Erweiterung wähle auch ein Datum nach dem aktuellen Ende des Schlüssels.
Der Wert dieses alten Schlüssels ist nicht erhalten geblieben	Der bestehende Schlüssel ist weiterhin nutzbar, aber sein Wert kann nicht erneut angezeigt werden. Wenn er verloren geht, erstellen Sie einen neuen Schlüssel, aktualisieren Sie die Anwendung und entfernen Sie den alten.
Der Schlüssel kann auf diesem Server nicht entschlüsselt werden	Lassen Sie die Serverschutzschlüssel vom Betreiber überprüfen. Dieser Konsultationsfehler ändert für sich genommen den API-Zugriff nicht.
Dieser Schlüssel wurde geändert oder gelöscht	Schließen Sie die Karte und aktualisieren Sie die Liste, bevor Sie von vorne beginnen. Eine weitere Intervention könnte ihren Status verändert haben.
Die Registrierung konnte nicht bestätigt werden	Aktualisieren Sie die Liste und prüfen Sie das Ergebnis, bevor Sie es erneut versuchen, um eine doppelte Erstellung zu vermeiden.
Der Kopier-Button erscheint nicht	Zuerst klicken Show. Der Knopf fehlt absichtlich, wenn der Schlüssel versteckt ist.

Für neue Schlüssel, die konsultiert werden können, behält der Server einen geschützten Wert bei, der es ermöglicht, sie erneut anzuzeigen. Der Betreiber muss während Backups und Serverwechsel die notwendigen Schutzelemente aufrechterhalten. Für diesen Punkt sind keine neuen Passwörter vom Benutzer erforderlich.

9. Überprüfe die Indienststellung

Bevor Sie einem Antrag einen Schlüssel geben, überprüfen Sie diese Punkte:

• Der Name der App ist erkennbar.
• Das verknüpfte Konto ist aktiv und hat nur die notwendigen Rechte.
• die Gültigkeitsdauer entspricht der beabsichtigten Nutzung;
• Die App verwendet den richtigen Server, den richtigen Namen und den richtigen Schlüssel.
• Der Zugriff und die erwarteten Abläufe wurden über die App überprüft.
• Der Schlüssel wird an einem geschützten Ort aufbewahrt und sein Ablaufdatum wird erfasst.
• Die alten Schlüssel, die nicht mehr benötigt wurden, wurden nach dem Austausch entfernt.