Zum Hauptinhalt springen

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 /token erworben und dann als HTTP-Header zu jeder nachfolgenden Anfrage hinzugefügt werden. (Details folgen)

Hinweis

Der gesamte Datenverkehr zu den Token-Endpunkten MUSS über HTTPS gesichert werden, um die Authentifizierungsdaten Ihrer Benutzer nicht zu gefährden.

iCL Portal implementiert sein eigenes Berechtigungssystem und speichert dabei die bekannten Benutzer und ihre Berechtigungen in einer lokalen Datenbank (MSSQL). Für die Authentifizierung unterstützt es derzeit die formularbasierte Authentifizierung, WS-Federation und die Authentifizierung über Salesforce als OAuth-Authentifizierungsserver.

Formularbasierte Authentifizierung bedeutet, dass Benutzer und Kennwörter von iCL Portal in seiner lokalen Datenbank verwaltet werden und der Benutzer sich über ein benutzerdefiniertes Anmeldeformular anmeldet:

Bei der WS-Federation-basierten Authentifizierung wird der Benutzer zu einem bestimmten ADFS-Authentifizierungsserver (Active Directory Federation Services oder Azure Active Directory) weitergeleitet. Dort muss er seine Anmeldedaten eingeben, und wenn diese korrekt sind, wird er zum iCL Portal weitergeleitet. In diesem Fall speichert iCL Portal nur den Benutzernamen, aber nicht die Passwörter. Um dieses Authentifizierungssystem zu verwenden, muss iCL Portal so konfiguriert werden, dass es dem ADFS-Endpunkt vertraut und umgekehrt. Der Vorteil der WS-Federation-Authentifizierung ist, dass ein Benutzer, sobald er bei ADFS angemeldet ist, zu iCL Portal navigieren kann und automatisch authentifiziert wird. (Single-Sign-On)

Die Salesforce-Authentifizierung funktioniert ähnlich wie WS-Federation, folgt aber vollständig dem OAuth-Standard. Dennoch müssen Sie iCL Portal so konfigurieren, dass es Ihrer Salesforce-Umgebung vertraut und umgekehrt. Der Vorteil der Salesforce-Authentifizierung ist, dass ein Benutzer, sobald er in Salesforce angemeldet ist, zu iCL Portal navigieren kann und automatisch authentifiziert wird. (Einzelanmeldung)

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:

Benutzeranmeldung mit Passwort (Resource Owner Password Credentials flow)​

Die formularbasierte Authentifizierung wird von Haus aus unterstützt und muss nicht explizit konfiguriert werden. Damit sich eine Client-Anwendung authentifizieren kann, muss sie die erforderlichen Authentifizierungsparameter gemäß dem OAuth 2.0 password_grant-Flow an den Endpunkt /token senden. Die Parameter werden form-url-kodiert im Körper der HTTP-Anfrage übertragen.

Parameter:

NameTypeRequired?Description
grant_typestringrequiredmuss "Passwort" sein.
BenutzernameZeichenfolgeerforderlichnur alphanumerische Zeichen.
passwordstringrequireddas Passwort des Benutzers im Klartext. (daher darf der Endpunkt /token nicht mit unsicherem http, sondern nur mit https verwendet werden)
tenancyNamestringrequiredder Name des Mandanten, zu dem der Benutzer gehört. Er ist normalerweise auf "default" voreingestellt, kann aber bei der Erstinstallation von iCL Portal konfiguriert werden.

Beispiel​

POST https://dev.iclportal.com/token HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Content-Length: ...
Accept: */*
Origin: https:// dev.iclportal 
X-Requested-With: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Referer:  https://dev.iclportal.com/Account/Login
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8

grant_type=password&username=admin&password=Pass@word!&tenancyName=Default

Wenn alles gut geht, antwortet der Server mit 200 OK und sendet ein JSON-Objekt, das den access_token enthält.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 718
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

{"access_token":"TizVr8StFXx8GueUbGdD9j0V0_jeGT2LMzxZjc8Kw6UOZ2Muy8rZ2guLJCymeU9dJis5lNYPe8HIbh3vfqjZTPa9UvLI4Ixtw6QrSrohQhMpo-ua1Adh5sXSCFWT-FFY-hz_Pp22aXqoAvvDG9cRWwjc3jMUhPrgNq7Xfvj6Xo9B3a-KthzdpET16sQ5I6sjczEdbHUR39a7Z36MQ2_eSpOwWEP2CEN3W1aiS0TDw1AEaBZltyn4fPazdc-Rkn2XwW0Fn26DqL-bY1knbwuyz5JLbNPIno-XUOlz6fSn7e3XPgFefAUGxpU--xyYPspKH0kXO1S6a-_WSdR0qF3euS55P6i-KuPpJNWRAtkR6Xors4NUtRB8hm_V9AbsTW_6F59IZD4kRj77nJxS_4xqDy2VroO0bHh-xLpSFnQ7Aj_uCCu62_wqKjiNRA468bWONXkJOQcEgv6b3fg__ZphtqDS4zvbO0BoY1AZsWdDDHA","token_type":"bearer","expires_in":1799,"userName":"admin","roles":"Admin,Admin","emailConfirmed":"true","as:client_id":"",".issued":"Tue, 29 Dec 2015 14:34:41 GMT",".expires":"Tue, 29 Dec 2015 15:04:41 GMT"}

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/account/userinfo?_=1451399681904 HTTP/1.1
Host: dev.iclportal.com 
Connection: keep-alive
Accept: */*
X-Requested-With: XMLHttpRequest
Authorization: Bearer TizVr8StFXx8GueUbGdD9j0V0_jeGT2LMzxZjc8Kw6UOZ2Muy8rZ2guLJCymeU9dJis
5lNYPe8HIbh3vfqjZTPa9UvLI4Ixtw6QrSrohQhMpo-ua1Adh5sXSCFWT-FFY-hz_Pp22aXqoAvvDG9cRWwjc
3jMUhPrgNq7Xfvj6Xo9B3a-KthzdpET16sQ5I6sjczEdbHUR39a7Z36MQ2_eSpOwWEP2CEN3W1aiS0TDw1A
EaBZltyn4fPazdc-Rkn2XwW0Fn26DqL-bY1knbwuyz5JLbNPIno-XUOlz6fSn7e3XPgFefAUGxpU--xyYPspKH0kXO1S6a-_WSdR0qF3euS55P6i-KuPpJNWRAtkR6Xors4NUtRB8hm_V9AbsTW_6F59IZD4kRj77
nJxS_4xqDy2VroO0bHh-xLpSFnQ7Aj_uCCu62_wqKjiNRA468bWONXkJOQcEgv6b3fg__ZphtqDS4z
vbO0BoY1AZsWdDDHA
Referer: https://dev.iclportal.com

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-cache
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

{"error":"invalid_grant","error_description":"Usernamd or password are incorrect"}

Dienstclient-Anmeldung (Client Credentials-Flow)​

Für Dienstclients sollten Sie den Client Credentials flow um ein Token für den Zugriff 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.

Kopieren Sie das Token - es ist ein einfaches json-Dokument:
{
  "clientId":"fd52e53d-9b5f-405c-8084-052c8dfe08ac",
  "clientSecret": "cjfdRtrCHKYaLALOvHV/JFhSpId/gtksoSLw1XPkkAo="
}

Dann können Sie diese Informationen verwenden, um ein Access Token zu erhalten:


POST https://dev.iclportal.com/token HTTP/1.1
Host: dev.iclportal.com

grant_type=client_credentials&client_id=fd52e53d-9b5f-405c-8084-052c8dfe08ac&client_secret=cjfdRtrCHKYaLALOvHV/JFhSpId/gtksoSLw1XPkkAo=

Wenn Ihre Anfrage erfolgreich ist, erhalten Sie eine Antwort wie diese:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 718
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

{"access_token":"TizVr8StFXx8GueUbGdD9j0V0_jeGT2LMzxZjc8Kw6UOZ2Muy8rZ2guLJCymeU9dJis5lNYPe8HIbh3vfqjZTPa9UvLI4Ixtw6QrSrohQhMpo-ua1Adh5sXSCFWT-FFY-hz_Pp22aXqoAvvDG9cRWwjc3jMUhPrgNq7Xfvj6Xo9B3a-KthzdpET16sQ5I6sjczEdbHUR39a7Z36MQ2_eSpOwWEP2CEN3W1aiS0TDw1AEaBZltyn4fPazdc-Rkn2XwW0Fn26DqL-bY1knbwuyz5JLbNPIno-XUOlz6fSn7e3XPgFefAUGxpU--xyYPspKH0kXO1S6a-_WSdR0qF3euS55P6i-KuPpJNWRAtkR6Xors4NUtRB8hm_V9AbsTW_6F59IZD4kRj77nJxS_4xqDy2VroO0bHh-xLpSFnQ7Aj_uCCu62_wqKjiNRA468bWONXkJOQcEgv6b3fg__ZphtqDS4zvbO0BoY1AZsWdDDHA","token_type":"bearer","expires_in":1799,"userName":"admin","roles":"Admin,Admin","emailConfirmed":"true","as:client_id":"",".issued":"Tue, 29 Dec 2015 14:34:41 GMT",".expires":"Tue, 29 Dec 2015 15:04:41 GMT"}

Verwendung von Salesforce zur Authentifizierung​

Um Salesforce als Authentifizierungsanbieter zu verwenden, muss es im iCL Portal und in Salesforce konfiguriert werden:

Zugriff auf das iCL Portal​

Damit sich eine Client-Anwendung mit Salesforce authentifizieren kann, muss sie zunächst alle konfigurierten Authentifizierungsanbieter vom iCL Portal über den Endpunkt /api/account/eternalLogins abrufen.

GET  https://dev.iclportal.com/api/account/externalLogins?returnUrl=%2F&generateState=false HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Accept: */*
X-Requested-With: XMLHttpRequest`

Vergessen Sie nicht die Parameter "returnUrl=%2F" und "generateState=false", sonst antwortet der Server mit "404 Not Found". Da die returnurl nur angibt, wohin der Browser nach erfolgreicher Authentifizierung des Benutzers umgeleitet werden soll, können Sie %2f stehen lassen.

Der Server antwortet mit allen derzeit konfigurierten Authentifizierungsanbietern im HTTP-Body:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8

[{"name":"Salesforce","url":"/api/account/ExternalLogin?provider=Salesforce&response_type=token&client_id=self&redirect_uri=https%3A%2F%2Fdev.iclportal.com%2F&state=SOMELONGSTRING","state":"SOMELONGSTRING","imageUri":null,"imageClass":null}]

Dann muss das zurückgegebene Feld "url" als Endpunkt der GET-Anfrage verwendet werden, um ein Access Token zu erhalten. (/api/account/ExternalLogin)

GET  https://dev.iclportal.com/api/account/ExternalLogin?provider=Salesforce&response_type=token&client_id=self&redirect_uri=https%3A%2F%2Fdev.iclportal.com%2F&state=SOMELONGSTRING HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8

If all goes well, Salesforce will respond with a HTTP 302 redirect to the base-url of iCL Portal, providing the “access_token” as a URL fragment:
HTTP/1.1 302 Found
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Location: https://dev.iclportal.com/#access_token=rqwfbZ63BNv9s0hUBp9mOYNh2s2Kq2MQQaPMms4Covei-AWm4KLWitfZU8I4BPGBCvCsKN1loGcVNv0VUKSlW4V8HrhF6Ab8BfrLrw7JsEk0cAeArFp3LQ0BNdgzB5bObOZDdw-CoHiFcWLTU79eVR5RU3R9FNBhGdPNgm4b33ZXSQoe0tsjX91a_-wdqcz_c14qysbyX6EzDxBiAO4_WXL2lkXUdjdBPf6fvUKljmHFwKuLPd0xt08EFfPTmRmmJ0TGhb_iOG2dllt3VHwoZCFjRANcUjF1_RNNVbwkKLdpn8aUrq9tTdgBnzL77BBJqm042Sxl4F8nBRvT5YKKGefAjSQ-VSqChYIc1kcgqkPygHIOaLMAiLl2ihcmK4pK3iRJPRsTcFXx5GLfYU4fERLXHkRu9AdQJuLYcMD-vMkgMn5Oh-usXQdSc7sWGRx1WR267j3hYvutrf2YOUEUt41Hh0AA6rapNKcZiMdf3-I&token_type=bearer&expires_in=1800&state=sOTC7dRVB4KdB_UnFZYJz3QzyTuMucJNcS-Hg_l9EL81