Identityprovider-APP

Identityprovider-APP

Hinweise zum Support bei der API-Programmierung

Bitte beachten Sie, dass Ihre Software über diese Schnittstelle auch Zugriff auf die von Ihren Kunden im d.3ecm abgelegten und konfigurierten Daten erhält und Eingriff in die Abläufe im d.3ecm-System nimmt. Gehen Sie daher bitte sorgfältig vor und achten Sie darauf, dass Ihre Anwendung Teil eines bestehenden Zusammenspiels unterschiedlicher Anwendungen ist. Die unsachgemäße Verwendung dieser Schnittstelle kann veränderte Programmabläufe und Datenverlust zur Folge haben.

Die Software-Entwicklung mit dieser Programmierschnittstelle ist eine Individualentwicklung. Der von Ihnen erzeugte Programmcode fällt nicht unter die Pflege- und Supportbedingungen der Produkte der d.velop AG. Unser Support unterstützt Sie gerne, Ihre Anfragen sind jedoch kostenpflichtig, sofern sich die Anfrage nicht auf einen Fehler in unseren Produkten zurückführen lässt.


Technische Hintergrundinformationen

Abhängigkeiten

Um die identity provider-App per API verwenden zu können, sind folgende Komponenten erforderlich:

  • d.ecs http gateway
  • d.ecs shell
  • d.ecs jstore Version 1.1 oder höher

Einleitung

In diesem Thema finden Sie allgemeine Informationen zu Identity Provider-App, dem Funktionsumfang sowie zu den Kenntnissen, die hilfreich beim Programmieren von Funktionen und Anpassungen sind.


Über die identity provider API

Diese Dokumentation beschreibt die einzelnen Schnittstellen, die es Ihnen ermöglichen, angepasste Funktionen (Customizing) für die Authentifizierung zu erstellen.


Funktionsumfang der identity provider-App

Die identity provider-App authentifiziert Benutzer über verschiedene Authentifizierungsverfahren wie z.B. die Windows-Authentifizierung (Kerberos) mit Benutzername und Passwort gegen unterschiedliche Systeme zur Benutzerverwaltung wie z.B. Active Directory (AD) und stellt hierüber die erforderlichen Benutzerinformationen für die Nutzung durch andere Apps bereit. Sie stellt eine API-Schnittstelle bereit, die die Authentifizierung für Apps erlaubt.


Voraussetzungen

Diese Dokumentation richtet sich an Administratoren eines d.3ecm-Systems und an Entwickler von Apps und Erweiterungen.

Sie sollten über folgende Kenntnisse verfügen, um die API nutzen zu können:

  • Sie sollten über gute Kenntnisse der d.3ecm-Architektur verfügen.
  • Sie sollten mit der Authentifizierung über die d.ecs identity provider-API im d.3ecm-Kontext vertraut sein.
  • Sie sollten über Kenntnisse in der Entwicklung webbasierter Apps verfügen und sicher im Umgang mit folgenden Detailthemen sein:
    • Hypertext Transfer Protocol (HTTP) (RFC 7230)
    • RESTful HTTP-Schnittstellen
    • JavaScript Object Notation (JSON) (RFC 7159)
    • Hypertext Application Language in Verbindung mit der JavaScript Object Notation (HAL+JSON)
    • UriTemplate (RFC 6570)
  • Sofern Sie eigene Benutzeroberflächen bereitstellen möchten, sollten Sie über Kenntnisse in HTML, CSS, Responsive Webdesign verfügen. Um ein einheitliches Look&Feel zu ermöglichen, ist es empfehlenswert, über Kenntnisse in der Verwendung des Frameworks DUX (d.velop user experience) zu verfügen.
  • Zusätzlich sind Kenntnisse in der Administration eines Webservers von Vorteil.


Verwenden der API-Funktionen

 Die identity provider-App stellt eine API-Schnittstelle zur Verfügung, die es Ihnen unter anderem erlaubt, folgende Aktionen auszuführen:


Hintergrund: Ablauf der Authentifizierung und Autorisierung

Anmelden (Login)

Diese Funktion führt eine Anmeldung aus einer App heraus durch. 

Führen Sie ein Redirect auf die URI /identityprovider/login aus und beachten Sie hierbei, dass die URI in Kleinbuchstaben zu verwenden ist.

Diese Ressource hat einen gültigen Query-Parameter:

ParameterBeschreibung
redirect

Dies ist ein Pflichtparameter, der den Pfad und Query-Anteil der eigenen URI enthält.

Sofern die Anmeldung erfolgreich war, führt die identity provider-App ein Redirect zurück an diese URI durch.

Wichtig

Beim Aufruf der URI /identityprovider/login wählt die identity provider-App je nach Konfiguration eine beliebige Authentifizierungsmethode. Apps dürfen diese URI daher nicht selbst aufrufen, sondern müssen dies dem Browser überlassen. Clientanwendungen, die sich anmelden möchten, müssen ein Browsercontrol verwenden und eine Redirect-URI definieren, die sie im Browsercontrol verwenden können.

Wenn lediglich ein API-Key verwendet wird, darf die URI /identityprovider/login?basic=true verwendet werden, während der API-Key als Passwort übergeben wird.

Validieren der Anmeldung (Validate)

Sie können mit der Funktion Validate sicherstellen, ob eine Anfrage eine Anmeldung enthält, um eine korrekte Anmeldung sicherzustellen.

Validieren der erforderlichen Informationen:

  • Prüfen Sie, ob der Authorization-Header festgelegt ist.
  • Prüfen Sie, ob der Header ein Bearer-Token enthält.
  • Wenn kein Bearer-Token vorhanden ist, prüfen Sie zusätzlich, ob das Cookie AuthSessionId vorhanden ist.
  • Ist beides nicht vorhanden, führen Sie aus der App ein Redirect auf die Login-Ressource durch.
Request
   GET /identityprovider/validate[?allowExternalValidation=true]

Mit der Angabe von allowExternalValidation=true als Query-Parameter weisen Sie die identity provider-App an, auch externe Benutzer zu überprüfen, die nicht über die Provider von d.ecs identity provider bekannt sind, sich aber via OpenID Connect (alternative Anmeldung) angemeldet haben. Das zurückgegebene SCIM User Object enthält dann bei diesen Benutzern lediglich eine E-Mail-Adresse und die besondere Gruppenzugehörigkeit zur Gruppe mit der ID 3E093BE5-CCCE-435D-99F8-544656B98681.

Response(s)
Ungültiges Token, kein Token.HTTP Status: 401 Unauthorized
Gültiges Token eines externen Benutzers: allowExternalValidation=falseHTTP Status: 403 Forbidden
Gültiges Token.

HTTP Status: 200 OK

Content-Type:
application/hal+json

<JSON SCIM User object>


Mit dieser GET-Anforderung wird der Inhalt des Tokens oder Cookies wahlweise als Token oder Cookie an den Identityprovider übermittelt. Ob der Inhalt als Bearer-Token oder Cookie weitergegeben wird, hängt nicht davon ab, wie es ursprünglich empfangen wurde. Sie können als Entwickler Ihre persönliche Präferenz im Code definieren.

Damit nicht bei jeder Anforderung (Request) der Validate-Endpunkt aufgerufen werden muss, sollten Sie die Antwort zwischenspeichern.

Verwenden Sie für das Caching SCIM User Object. Die identity provider-App sendet dann den CacheControl-Header und legt darin MaxAge fest. 

Diese Angabe sollte dazu verwendet werden, die Antwort für die angegebene Anzahl Sekunden zu speichern. AuthSessionId ist dabei der Schlüssel für diese Information. Um den Cache einfacher zu verwalten, können Sie den Teil bis zum kaufmännischen Und-Zeichen (&) als Schlüssel verwenden. Dieser Teil des Tokens ist statisch und bleibt bei einem Benutzer immer gleich.

Hinweis

Beachten Sie jedoch, dass Sie nicht nur diesen Teil vergleichen dürfen. Sie müssen vielmehr immer das komplette Token vergleichen.

Der Teil hinter dem kaufmännischen Und-Zeichen (&) ist bei jeder Sitzung anders. Bei einem Cache, der eine einfache 1:1 Speicherung unter dem statischen Teil des Tokens durchführt, wird ein Wechsel des Browsers somit zu einem Erneuern der Cachedaten führen, da der komplette Tokenvergleich fehlschlägt.


Verwenden des SCIM-Protokolls zur Authentifizierung

Zur weiteren Authentifizierung und für weitere Funktionen stellt der d.ecs identity provider die Informationen des Benutzers nach dem SCIM-Protokoll in der Version 1.0 und 1.1 bereit. Das System for Cross-domain Identity Management (SCIM) Protokoll ist ein herstellerunabhängiger Standard und wurde entwickelt, um die Benutzerauthentifizierung in cloudbasierten Anwendungen und Diensten zu vereinfachen. 

Die Basisadresse (URI) des SCIM-Protokolls ist dabei /identityprovider/scim. Prüfen Sie zunächst, ob ein gültiges Token übergeben wurde, um auf die SCIM-Ressource zugreifen zu können.

Darunter stellt der Identityprovider die beiden SCIM-Ressourcen users und groups nur lesend bereit:

Verwenden Sie /identityprovider/scim/users, um alle Benutzer aufzulisten.

Verwenden Sie /identityprovider/scim/Groups, um alle Gruppen aufzulisten.

Hinweis

Weitere Informationen zum SCIM-Protokoll finden Sie unter der folgenden Adresse: http://www.simplecloud.info/specs/draft-scim-core-schema-00.html (in englischer Sprache)

 

Authentifizieren einer App mit Requests außerhalb des Benutzerkontextes

Apps können sich auch authentifizieren, wenn Anforderungen (Requests) erforderlich sind, die nicht im Kontext eines angemeldeten Benutzers stattfinden (z.B. Hintergrundbatches). Sie müssen für diese App in der identity provider-App einen Benutzer auswählen und für diesen Benutzer einen API-Key erzeugen.
Dieser API-Key kann von der App dazu verwendet werden, eine Session-ID mithilfe der identity provider-App zu ermitteln, die anschließend an die jeweilige App gesendet wird. 

Die Authentifizierung mithilfe des API-Keys erfolgt zunächst über bearer-Token. Schreiben Sie den API-Key in den Authorization-Header mit dem Schema Bearer und legen Sie den Accept-Header auf application/json fest. Die Login-Route von d.ecs identity provider gibt dann ein DTO mit AuthSessionId und Expire zurück. Sie können die ID AuthSessionId bis zum angegebenen Ablaufdatum in Expire zur weiteren Authentifizierung verwenden. Zu diesem Zweck befüllen Sie den Authorization-Header mit dem Schema Bearer mit der zuvor zurückgegebenen ID unter AuthSessionId und rufen Sie die gewünschte Ressource auf.

Beispiel in C#
   private class AuthSessionInfoDto
{
   	public string AuthSessionId { get; set; }
	public DateTime Expire { get; set; }
}
    
public static void AuthTest()
{
	var myApiKey = "<API key of your user>";
	var baseUri = "https://<URL of your computer>";
    using (var client = new HttpClient() { BaseAddress = new Uri(baseUri) })
    {
		//Use d.ecs identity provider to convert the API key into AuthSessionID
    	client.DefaultRequestHeaders.Authorization=new AuthenticationHeaderValue("Bearer",myApiKey);
        client.DefaultRequestHeaders.Add("Accept", "application/json");
        var result = client.GetAsync("/identityprovider/login").Result;
        result.EnsureSuccessStatusCode();
        var authSessionInfo=JsonConvert.DeserializeObject<AuthSessionInfoDto>(result.Content.ReadAsStringAsync().Result);
        
      	//Set the determined AuthSessionId as Bearer token and retrieve the according resource
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", authSessionInfo.AuthSessionId);
        client.DefaultRequestHeaders.Add("Accept", "application/hal+json");
        result = client.GetAsync("/customapp").Result;  
        result.EnsureSuccessStatusCode();
        var content = result.Content.ReadAsStringAsync().Result;
        Console.WriteLine(content);
	}
}