Authentifizierung
Dieser Abschnitt gibt Ihnen eine ausführliche Einführung in die Authentifizierung mit iCL Portal. Die gesamte Funktionalität des iCL Portals ist über REST-Dienste zugänglich. Für die Authentifizierung wird der OAuth 2.0 Bearer Token Standard verwendet: Um auf die gesicherten REST-Dienste zugreifen zu können, muss ein access_token vom Endpunkt /connect/token erworben und dann als HTTP-Header zu jeder nachfolgenden Anfrage hinzugefügt werden. (Details folgen)
iCL Portal arbeitet als OAuth 2.0 / OpenID Connect Server. Seine Konfiguration (Endpunkte, unterstützte Grant Types und Scopes) wird unter https://<Ihr.portal.url>/.well-known/openid-configuration veröffentlicht.
Der gesamte Datenverkehr zu den Token-Endpunkten MUSS über HTTPS gesichert werden, um die Authentifizierungsdaten Ihrer Benutzer nicht zu gefährden.
Aus Gründen der Abwärtskompatibilität nimmt iCL Portal Token-Anfragen weiterhin auch am alten Endpunkt /token entgegen. Neue Integrationen sollten /connect/token verwenden.
iCL Portal implementiert sein eigenes Berechtigungssystem und speichert dabei die bekannten Benutzer und ihre Berechtigungen in einer lokalen Datenbank (MSSQL). Benutzer können sich auf zwei Arten anmelden:
Von iCL Portal verwaltete Benutzer haben ihren Benutzernamen und ihr Passwort in der lokalen Datenbank von iCL Portal gespeichert und melden sich über das Anmeldeformular an.
Externe Identitätsanbieter (Microsoft Entra ID) werden pro Mandant in den Einstellungen von iCL Portal konfiguriert (siehe Konfigurieren Sie die Azure Entra ID Integration). Der Benutzer wird zu Microsoft weitergeleitet, um dort seine Anmeldedaten einzugeben, und wenn diese korrekt sind, wird er zum iCL Portal zurückgeleitet. In diesem Fall speichert iCL Portal nur den Benutzer, aber nicht das Passwort. Der Vorteil ist, dass ein Benutzer, sobald er bei Microsoft Entra ID angemeldet ist, zu iCL Portal navigieren kann, ohne sein Passwort erneut einzugeben. (Single-Sign-On)
Wenn ein nicht authentifizierter Benutzer über seinen Browser zum iCL Portal navigiert, wird er auf die Anmeldeseite weitergeleitet, auf der er aus allen konfigurierten Authentifizierungsmechanismen wählen kann:
Externe Identitätsanbieter sind für die interaktive Anmeldung im Browser gedacht. Um von einem anderen System aus auf die REST-API zuzugreifen, verwenden Sie den Client Credentials-Flow.
Unterstützte Grant Types
Der Token-Endpunkt /connect/token unterstützt die folgenden OAuth 2.0 Grant Types:
| grant_type | Verwenden Sie ihn für |
|---|---|
| client_credentials | Empfohlen für Integrationen. Ein Dienstclient authentifiziert sich mit einer Client-ID und einem Client-Secret, die zu einem Benutzer von iCL Portal gehören. Siehe Dienstclient-Anmeldung. |
| password | Die Anmeldung mit Benutzername und Passwort (Resource Owner Password Credentials-Flow). Veraltet — verwenden Sie stattdessen den Client Credentials-Flow. |
| refresh_token | Das Abrufen eines neuen Access Tokens, ohne sich erneut anzumelden. Ein Refresh Token wird nur ausgestellt, wenn der Scope offline_access angefordert wurde. Siehe Access Token erneuern. |
| authorization_code | Die interaktive Anmeldung der iCL Apps (z.B. iCL Portal, iCL Filler) über /connect/authorize. Er erfordert einen in iCL Portal registrierten Client und ist daher nicht für Integrationen gedacht. |
Alle Parameter werden form-url-kodiert im Body der HTTP-Anfrage übertragen (Content-Type: application/x-www-form-urlencoded). Denken Sie daran, die Werte zu URL-kodieren, z.B. Passwörter oder Client-Secrets, die +, /, = oder @ enthalten.
Benutzeranmeldung mit Passwort (Resource Owner Password Credentials flow)
Der Password Grant ist veraltet. Verwenden Sie für neue Integrationen den Client Credentials-Flow.
Damit eine Client-Anwendung einen Benutzer mit seinem Passwort authentifizieren kann, muss sie die erforderlichen Authentifizierungsparameter gemäß dem OAuth 2.0 Password Grant an den Endpunkt /connect/token senden.
Parameter:
| Name | Typ | Erforderlich? | Beschreibung |
|---|---|---|---|
| grant_type | string | erforderlich | muss "password" sein. |
| username | string | erforderlich | der Benutzername oder die E-Mail-Adresse des Benutzers. |
| password | string | erforderlich | das Passwort des Benutzers im Klartext. (daher darf der Token-Endpunkt nicht mit unsicherem http, sondern nur mit https verwendet werden) |
| tenancyName | string | optional | der Name des Mandanten, zu dem der Benutzer gehört. Geben Sie ihn immer an, außer der Benutzer ist ein Host-Benutzer. |
| client_id | string | optional | der Client, für den das Token angefordert wird. Standardwert ist iCLPortalApp. |
| scope | string | optional | durch Leerzeichen getrennte Liste von Scopes. Fügen Sie offline_access hinzu, um zusätzlich ein Refresh Token zu erhalten. |
Beispiel
POST https://dev.iclportal.com/connect/token HTTP/1.1
Host: dev.iclportal.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=admin&password=Pass%40word%21&tenancyName=Default&scope=offline_access
Wenn alles gut geht, antwortet der Server mit 200 OK und sendet ein JSON-Objekt, das den access_token enthält. Standardmäßig ist ein Access Token 45 Minuten gültig (expires_in wird in Sekunden angegeben). Der refresh_token wird nur zurückgegeben, wenn der Scope offline_access angefordert wurde.
HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
{
"access_token": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZDQkMtSFM1MTIiLCJraWQiOiI...",
"token_type": "Bearer",
"expires_in": 2700,
"refresh_token": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZDQkMtSFM1MTIiLCJraWQiOiI..."
}
Dieser access_token muss dann dem HTTP-Header jeder nachfolgenden Anfrage mit dem Header-Namen "Authorization", vorangestellt mit "Bearer ", hinzugefügt werden:
GET https://dev.iclportal.com/api/contenttypes HTTP/1.1
Host: dev.iclportal.com
Accept: application/json
Authorization: Bearer eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZDQkMtSFM1MTIiLCJraWQiOiI...
Wenn etwas schief geht (z.B. wenn der Benutzer ein falsches Passwort angegeben hat), antwortet der Server mit HTTP 400 bad request. Eine genauere Fehlerinformation finden Sie im JSON-Objekt im Body der Antwort:
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
{"error":"invalid_grant","error_description":"Invalid username or email address"}
Dienstclient-Anmeldung (Client Credentials-Flow)
Für Dienstclients sollten Sie den Client Credentials flow verwenden, um ein Access Token zu erhalten.
Erstellen Sie dazu einen Dienstbenutzer mit den entsprechenden Berechtigungen, der für die Authentifizierung von API-Anfragen verwendet wird.
Gehen Sie dann zu den Einstellungen dieses Benutzers, öffnen Sie die Registerkarte OAuth API-Tokens und klicken Sie auf Neu erstellen.
{
"clientId":"fd52e53d-9b5f-405c-8084-052c8dfe08ac",
"clientSecret":"cjfdRtrCHKYaLALOvHV/JFhSpId/gtksoSLw1XPkkAo="
}
Dann können Sie diese Informationen verwenden, um ein Access Token zu erhalten. Das Client-Secret ist Base64-kodiert und enthält meist Zeichen wie /, + und =. Es muss daher im Request-Body URL-kodiert werden:
POST https://dev.iclportal.com/connect/token HTTP/1.1
Host: dev.iclportal.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=fd52e53d-9b5f-405c-8084-052c8dfe08ac&client_secret=cjfdRtrCHKYaLALOvHV%2FJFhSpId%2FgtksoSLw1XPkkAo%3D
Alternativ können Sie Client-ID und Secret statt im Request-Body auch in einem Authorization: Basic Header senden.
Wenn Ihre Anfrage erfolgreich ist, erhalten Sie eine Antwort wie diese:
HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
{
"access_token": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZDQkMtSFM1MTIiLCJraWQiOiI...",
"token_type": "Bearer",
"expires_in": 2700
}
Das Access Token handelt im Namen des Benutzers, für den die Client Credentials erstellt wurden, und hat daher genau dessen Berechtigungen. Wenn es abläuft, fordern Sie einfach mit den Client Credentials ein neues an.
Access Token erneuern
Wenn Sie den Scope offline_access angefordert haben, enthält die Token-Antwort zusätzlich ein refresh_token. Damit erhalten Sie ein neues Access Token, ohne das Passwort des Benutzers erneut zu senden. Übergeben Sie dieselbe client_id, mit der das ursprüngliche Token angefordert wurde (iCLPortalApp, wenn Sie im Password-Flow keine angegeben haben), und, falls dieser Client eines hat, sein client_secret:
POST https://dev.iclportal.com/connect/token HTTP/1.1
Host: dev.iclportal.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&client_id=iCLPortalApp&refresh_token=eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZDQkMtSFM1MTIiLCJraWQiOiI...
Die Antwort hat dasselbe Format wie oben und enthält ein neues access_token und ein neues refresh_token. Verwenden Sie immer das zuletzt erhaltene Refresh Token.
Ist das Refresh Token nicht mehr gültig (z.B. weil es abgelaufen ist oder der Benutzer deaktiviert wurde), antwortet der Server mit HTTP 400 und dem Fehler invalid_grant.