Identity

UNITED-PAGES kann als verteilter Authentifizierungs-Service genutzt werden. Die Authentifizierung bei einem PROVIDER kann von anderen Services (Webportal) verifiziert werden und somit ein eigenes Login-Verfahren (z.B.mit eigenen Passwörtern) obsolet machen.

In folgendem Beispiel möchte sich Alice via UNITED-PAGES beim Service xy-service.com anmelden (Parameter in https-Aufrufen müssen urlencoded übergeben werden. Nur zur besseren Lesbarkeit werden im folgenden {} verwendet, z.B. _mail={alice@amail.com} statt _mail=alice%40amail.com)

SERVICE:

  • auf der Startseite kann die Email-Adresse eingegeben werden, falls diese nicht bereits durch einen entsprechend parametrisierten Aufruf bekannt ist e.g.
    https://www.xy-service.com/login.html?member={alice@amail.com}&room={cal/bob@bmail.com?id=team}
  • auf der Startseite wird ein Button 'Login via UNITED-PAGES' angeboten. Falls die email-adresse durch den Aufruf bereits bekannt ist und es keine Alternative zu einem Login via UNITED-PAGES gibt kann auch dieser Schritt übersprungen werden
  • aus der Email-Adresse des Nutzers kann die Startseite seines PROVIDERs bestimmt werden e.g. falls amail.com UNITED-PAGES nicht unterstützt
    https://www.united-pages.com/unit
    (dort befindet sich z.B. index.html oder index.php)
  • optional kann intern ein Identifikator für den Login-Vorgang angelegt werden (e.g. alice123), intern gespeichert und als Parameter dem anschließenden callback mitgegeben werden
  • gemäß Namenskonvention muss die Startseite jedes Providers mit den Parametern _mail und _cb aufgerufen werden. Die Parameter innerhalb von _cb dürfen nicht _mail, _token oder _error enthalten e.g.
    https://www.united-pages.com/unit?_mail={alice@amail.com}&_cb={https://www.xy-service.com/up-login.html?id={alice123}&room={cal/bob@bmail.com?id=team1}}

PROVIDER:

  • nach korrektem Login wird intern eine tok-UNIT angelegt. Diese enthält einen automatisch generierten token-String (e.g. abc!!!213), das Ende der Gültigkeit (aktuelle Zeit + 1 Minute) und den HOST (e.g. www.xy-service.com) der callback-URL (e.g. in PHP ermittelt via: parse_url("https://https://www.xy-service.com/up-login.htm...", PHP_URL_HOST)). Durch zusätzliche Speicherung des HOST lässt sich bei der späteren Prüfung der Gültigkeit des token durch den Service sicherstellen, dass das token nicht durch einen anderen Service in Auftrag gegeben wurde. Abschließend wird die callback-URL aus _cb ergämzt um die Parameter _mail und _token aufgerufen e.g.
    https://www.xy-service.com/up-login.html?room={cal/bob@bmail.com?id=team1}&id={alice123}&_mail={alice@amail.com}&_token={abc!!!123}
  • ist der Login fehlgeschlagen wird der callback statt mit _token mit _error aufgerufen e.g.
    https://www.xy-service.com/up-login.html?room={cal/bob@bmail.com?id=team1}&id={alice123}&_mail={alice@amail.com}&_error=401

SERVICE:

  • durch das optionale Prüfen eines Identifikators kann sicher gestellt werden, dass der callback nur auf ursprüngliche Initiative des Service hin aufgerufen worden ist. Der Identifikator wurde im Beispiel im Parameter id mitgegeben.
  • die callback-Parameter _mail/_token können innerhalb des Gültigkeitszeitraums (1 Minute) durch Löschen der entsprechende tok-UNIT geprüft werden. Dadurch ist sichergestellt, dass ein token, das in falsche Hände gerät nicht erneut verwendet werden kann e.g.
    DELETE https://www.united-pages.com/unit/tok/alice/amail.com?_token={abc!!!123}&_service={www.xy-service.com}

UP-Provider

Token

Ein Token wird als tok-UNIT in UNITED-PAGES implementiert. Die Variable token hält dabei den eigentlichen Wert.

Variable DataType Semantik Example
token String(48) token-id der UNIT (random) abc123
service String(48) HOST of callback webservice www.xy-service.com
eat timestamp(RFC 3339) expiration at
default: time of creation + 60sec		 2020-12-31T12:00:33+01:00

Aus einer Email-Adresse und dem Wert der token-Variable kann die URL der tok-UNIT bestimmt werden, e.g.

  • Email: John.Doe@goohoo.com
  • token: abc123
  • URI: unit://tok/john.doe@goohoo.com?token=abc123
  • URL: https://.../tok/john.doe/goohoo.com?token=abc123

Eine tok-UNIT kann auch mit einem authentifizierten POST-request angelegt werden:

POST Example
URL https://www.united-pages.com/unit/tok/john.doe/goohoo.com
HTTP-Authentication User: john.doe@goohoo.com
Password: <PIN>

Body

{  "token":"159246",
"service":"www.xy-service.com", // HOST of service
"seconds":20" } // offset to localtime - default: 30 }
Response { "expiration":"2020-05-12T10:19:30+00:00" }

 

Eine tok-UNIT kann mit einem DELETE-request ohne Authentifizierung verifiziert werden

DELETE Example
URL https://www.united-pages.com/unit/tok/john.doe/goohoo.com?token=159246&service=www.xy-service.com
Response {}
Response-Status 200 (valid token,; if singular == true then tok-UNIT is deleted)
400 (no valid token; if expiration has passed then tok-UNIT is deleted)

Domain

Jeder UP-Provider muss für jede einzelne Email-Domäne für die er verantwortlich ist eine dom-UNIT bei united-pages.com registrieren (lassen) e.g.
https://www.united-pages.com/dom/goohoo.com
https://www.united-pages.com/dom/goohoo.de
https://www.united-pages.com/dom/goohoo.gov

Zwingend notwendig ist die Angabe des unit_path ohne den kein Zugriff auf UNITs erfolgen kann. Die login_url muss konfiguriert werden, wenn der UP-Provider das Ident-Verfahren für Webportale unterstützt.

Variable DataType Semantik Example
unit_path String(48) URL-prefix  für alle RESTful-)Webservice-Requests auf UNITs von Nutzern der Domain www.goohoo.com/up
login_url String(64) URL für Webportal-Login (muss die Variablen $user und $service enthalten) www.goohoo.com/login.html?user=$user&callback=$service

Für den Zugriff via GET-request wird lediglich die Email-Domäne an https://www.united-pages.com/dom ergänzt

GET Example
URL https://www.united-pages.com/dom/goohoo.com
Response { "unit_path":"www.goohoo.com/up", "login_url":"www.goohoo.com/login.html?user=$user&callback=$service" }

 

Webportal

Applikation

Damit ein Webportal von einer Applikation gestartet werden kann muss es einen URL bieten, der als Parameter eine Email und einen Token übergeben bekommt. Dieser URL muss in einer sce-UNIT (bei einem beliebigen UP-Provider) in der Variable url konfiguriert sein,

Variables Example
subject ...
description ...
url https.//www.servicexy.com/login.html?user=$email&tok=$token

Für den Aufruf des Webportals muss die Applikation die Platzhalter $email bzw. $token mit der Email-Adresse des Nutzers bzw. dem token aus der zuvor (mit obigem POST-request) angelegten tok-UNIT (http-encodiert) ersetzt werden e.g.
https://www.service.xy.com/login.html?email=john.doe%40gohoo.com&tok=159264

Browser

Damit ein Nutzer (nach Angabe seiner Email-Adresse) von einem Webportal auf die Login-Page seines UP-Providers umgeleitet werden kann, muss der UP-Provider des Nutzers bei united-pages.com eine entsprechende dom-UNIT für die Email-Domain des Nutzers registriert haben und dort login-url konfiguriert sein.

login_url seines UP-Providers e.g.
https://www.goohoo.com/login.html?user=john.doe%40gohoo.com&callback=159264

"login_url":"www.goohoo.com/login.html?user=$user&callback=$service"

 

 

Requirements

Folgende Voraussetzungen müssen bei den beteiligten Rollen erfüllt sein:

- Webservice

(1) Der Webservice muss eine sceLogin-URL bieten und dementsprechend als sce-UNIT konfiguriert werden (sce-URI)

- Nutzer

(2) der Nutzer muss bei UNITED-PAGES registriert sein

(3) der Nutzer muss eine UP-Application nutzen, die sce-UNITs unterstützt

(4) der Nutzer muss eine UP-Application nutzen, die die Berechtigung hat um eine tok-UNIT unter seinem Account anzulegen

Entweder muss die UP-Application über den beim UP-Provider vom Nutzer konfigurierten MasterPin Kenntnis haben (z.B. durch manuelle Einstellung bei der UP-Application) oder das UP-Portal des jeweiligen UP-Provider  wird eingebunden , d.h. der Nutzer logged sich bei seinem UP-Portal ein, das eine tok-UNIT anlegt und im Anschluss den Webservice aufruft

- UP-Provider

(6) der UP-Provider muss die tok-UNIT unterstützen

Eine tok-UNIT beinhaltet ein Token und ein Ablaufdatum. Der Token kann vom UP-Webserver generiert werden oder beim Anlegen übergeben werden. Das Ablaufdatum kann durch die Angabe einer Zeitspanne (in seconds) festgelegt werden (Default: 60 sec).

Login via UP-Application

Das Verfahren unter Nutzung einer UP-Application umfasst folgende Schritte:

1. Nutzer

wählt in der UP-Application die sce-UNIT des zu startenden Webservice aus

2. UP-Application

die UP-Application startet einen GET-request auf die sce-UNIT  (sofern nicht im Cache)

Method GET
sce-URL https://www.united-pages.com/unit/sce/all/upservices.com?service=xy
Response { "urla":"https://www.xyportal.com/login.html?token=$token&email=$email", ... }

3. UP-Application

Die UP-Application legt beim UP-Provider des Nutzers eine neue tok-UNIT an

Method POST
tok-URL https://api.goohoo.com/upage/tok/john.doe/goohoo.com

Body

- if token not set, it will be generated and returned
- if seconds not set, default is 60

{ "token":"ttt123", "seconds":30 }

HTTP-Authenication

- username is email of user
- password is MasterPin of user

username: john.doe@goohoo.com
password: xxx

Response

- expiration is internal time of webserver plus seconds

{ "expiration":"2020-12-31 15:12:20" }

4. UP-Application

Die UP-Application ersetzt die Parameter in der sceLogin-URL ($email, $token) und startet den Webservice

webservice-URL
(http-encoded)		 https://www.xyportal.com/start.html?token=ttt123&email=john.doe%40goohoo.com"

5. Webservice

Der Webservice führt die Authentifikation durch Aufruf eines DELETE-request durch

Method DELETE
tok-URL https://api.goohoo.com/up/tok/john.doe/goohoo.com?token=ttt123

Der DELETE-Request auf eine tok-UNIT benötigt (im Gegensatz zu allen anderen UNIT-Typen) keine (HTTP-)Authentifizierung. Das token kann im Body aber (wie in obigem Beispiel) auch als Parameter übergeben werden, da es nur einmalig genutzt werden kann. Dies ist nach einem erfolgreichen DELETE-request(ResponseStatus = 200) garantiert. Der DELETE-request auf ein ungültiges token (ResponseStatus != 200) hat keine weiteren Auswirkungen.

6. Webservice

Im Falle einer positiven Response (200) erfolgt ein Login ohne Passwort-Abfrage.

Login via UP-Portal

Das Verfahren unter Nutzung eines UP-Provider-Portals umfasst folgende Schritte.

1. Nutzer

der Nutzer ruft eine upLogin-URL seines UP-Provders auf, die wiederum als callback-Parameter eine sceLogin-URL des Kundenportals enthält

upLogin-URL
(callback not HTTP-encoded for better readability)

https://www.united-pages.com/login.html?user=john.doe%40goohoo,com&
callback=https://www.servicexy.com/start.html?token=ttt123&email=john.doe@goohoo.com

 

2. Nutzer

Der Nutzer bekommt die Login-Seite seines UP-Provider-Portals und gibt sein Passwort ein

3. UP-Provider-Portal

Autentifizierung des Nutzers (Prüfung des Passworts)

4. UP-Provider-Portal

Anlegen einer tok-UNIT

5. UP-Provider-Portal

Aufruf der callback-URL mit entsprechender Email-Adresse und Zugriffstoken

6. Kundenportal

Das Kundenportal führt die Authentifikation durch Aufruf eines DELETE-request durch (siehe oben)

7. Kundenportal

Das Kundenportal öffnet sich dem Nutzer ohne weitere Eingabe eines Passworts

 

 

 

 

 

 

 

  1. ein USER wählt einen URL-link eines Kundenportals aus, der durch GET-request einer sce-UNIT erhalten wurde e.g.
    GET https://www.../sce/service/united-pages.com?id=xy -> { "url_a":"https://www.servicexy.com/login.html?user=$email&pw=$token" }
  2. enthält eine URL die Platzhalter $email und $token bedeutet das, dass das Ident-Verfahren von UNITED-PAGES beim Aufruf unterstützt wird. Dann legt die Applikation durch einen authentifizierten POST-Request (Public-Key-Verfahren) unter Angabe der sce-URI bei seinem UP-Provider ein temporäres Token(in Form einer tok-UNIT) an. Als Antwort wird eine Token-ID (token) zurückgegeben e.g.
    POST https://www.../tok/john.doe/goohoo.com?sce=service%40united-pages.com?id=xy -> { "token":"abc123" }
  3. unmittelbar danach ersetzt die Applikation die Platzhalter in der URL und ruft diese auf e.g.
    https://www.servicexy.com/login.html?user=john.doe%40goohoo.com&pw=abc123
  4. das Kundenportal kann aus der Email und der Token-ID die URL der entsprechenden tok-UNIT ableiten, die Gültigkeit durch GET-request verifizieren und mit der Antwort zudem überprüfen, ob der Token für den eigenen Service generiert wurde e.g.
    GET https://www.../tok/john.doe/goohoo.com?token=abc123 -> { "service":"sce/service@united-pages.com?id=xy", ... }

*HTTP-Encodierung

Wert HTTP-Encodierung
@ %40
= %3D
? %3F
/ %2F
& %26