Dokumentation

MOA-ID (Identifikation)

Protokolle

Inhalt

1. Allgemeines
2. PVP 2.1
3. OpenID Connect
4. SAML 1

1. Referenzierte Spezifikation

1 Allgemeines

Dieses Kapitel behandelt jene Authentifizierungsprotokolle die vom Modul MOA-ID-Auth unterstützt werden. Wobei die Verwendung der Protokolle PVP 2.1 oder OpenID Connect empfohlen wird. Das Protokoll SAML 1, welches bis zur MOA-ID Version 1.5.1 verwendet wurde, wird jedoch ab der Version 2.0 nur mehr aus Kompatibilitätsgründen angeboten und nicht mehr aktiv weiterentwickelt.

1.1 Übersicht der Zugangspunkte

In diesem Abschnitt sind die Zugangspunkte der vom Modul MOA-ID-Auth unterstützten Protokolle kurz zusammengefasst. Eine detailierte Beschreibung der einzelnen Protokolle finden Sie in den anschließenden Unterkapiteln.

1.2 Übersicht der möglichen Attribute

Die nachfolgende Tabelle beinhaltet eine Liste aller Attribute die vom Modul MOA-ID-Auth an die Online-Applikation zurückgeliefert werden können, sofern diese nach der Authentifizierung zur Verfügung stehen. Alle Namen beziehen sich auf den Attributnamen im jeweiligen Protokoll. Detailinformationen zu den einzelnen Attributen finden Sie in der PVP 2.1 Spezifikation der der STORK Spezifikation.

2 PVP 2.1

Die PVP 2.1 Implementierung des Modules MOA-ID-Auth bezieht sich auf das S-Profil der PVP 2 Spezifikation. Das S - Profil von PVP 2 verwendet SAML WebSSO für die Authentifizierung von Benutzern mit Webbrowser. Dadurch wird die direkte Kommunikation des Browsers mit der Anwendung ermöglicht, was in Anwendungsfällen notwendig ist, wo Anwendungen nicht kompatibel mit dem Reverse - Proxy - Verfahren sind, datenschutzrechtliche Probleme bestehen oder SAML WebSSO als Industriestandard unterstützt werden soll.

Bevor PVP 2.1 als Authentifizierungsprotokoll verwendet werden kann muss das Modul MOA-ID-Auth entsprechend konfiguriert werden. Detailinformationen zur Konfiguration finden Sie hier.

2.1 Ablauf einer Anmeldung mittels PVP 2.1

Die nachfolgende Abbildung zeigt das Sequenzdiagramm eines Anmeldevorgangs mittels PVP 2.1 und des Modules MOA-ID-Auth als Identityprovider. Aus Gründen der Übersichtlichkeit wurden die Teile welche die Kommunikation mit der Bürgerkartenumgebung oder die Vollmachten-Auswahl betreffen bewusst nicht berücksichtigt.

2.2 Metadaten

Das Modul MOA-ID-Auth stellt für Service-Provider (Online-Applikationen) Metadaten bereit welche alle PVP 2.1 spezifischen Informationen der MOA-ID-Auth Instanz beinhalten. Diese Metadaten werden durch das Modul MOA-ID-Auth signiert, wodurch Service Provider die Authentizität der Metadaten verifizieren können. Ein Beispiel für Metadaten von MOA-ID-Auth finden sie hier. Die aktuellen Metadaten zu Ihrer MOA-ID-Auth Instanz können unter folgender URL abgerufen werden.

http://<host>:<port>/moa-id-auth/pvp2/metadata

bzw.

https://<host>:<port>/moa-id-auth/pvp2/metadata

Wollen Sie für Ihre Online-Applikation PVP 2.1 als Authentifizierungsprotokoll nutzen müssen für jede Online-Applikation Metadaten erstellt und durch den Service Provider signiert werden. Zusätzlich muss die URL auf die Metadaten und das entsprechende Signaturzertifikat zur Prüfung der Signatur in der online-applikationsspezifischen PVP 2.1 Konfiguration von MOA-ID-Auth hinterlegt sein. Ein Beispiel für online-applikationsspezifische Metadaten finden Sie hier.

Die nachfolgenden Anforderungen an die online-applikationsspezifischen Metadaten .

• Das XML Attribut entityID im Element md:EntitiesDescriptor/md:EntityDescriptor (siehe Beispiel) den eindeutigen Identifier enthält der für diese Online-Applikation bei MOA-ID-Auth hinterlegt ist.
• Die Metadaten müssen ein Zertifikat zur Prüfung der Signatur am Authentifizierungsrequest beinhalten. Hierfür muss das XML Element md:EntitiesDescriptor/md:EntityDescriptormd:SPSSODescriptor/md:KeyDescriptor mit dem Attribut use="signing" vorhanden sein (siehe Beispiel).
• Die Metadaten müssen mindestens ein XML Element
  md:EntitiesDescriptor/md:EntityDescriptormd:SPSSODescriptor/md:AssertionConsumerService enthalten welches das gewünschte Binding und die URL zur Auslieferung der Assertion beinhaltet.
• Werden zusätzlich zum bereichsspezifischen Personenkennzeichen (bPK / wbPK) weitere Attribute durch den Service Provider benötigt müssen diese über die Metadaten angefordert werden.
  Hierfür steht das Element md:EntitiesDescriptor/md:EntityDescriptormd:SPSSODescriptor/md:AttributeConsumingService zur Verfügung wobie die als Kindelemente md:RequestedAttribute die einzelnen benötigten Attribute definieren (siehe Beispiel).

Zusätzlich unterstützt das Modul MOA-ID-Auth auch die Verschlüsselung PVP 2.1 Assertion mit einem vom Service-Provider definierten Zertifikat. Um diese Funktion zu nutzen muss in den Metadaten ein zweites XML Element md:EntitiesDescriptor/md:EntityDescriptormd:SPSSODescriptor/md:KeyDescriptor mit dem Attribut use="encryption" vorhanden sein (siehe Beispiel). In diesem Fall verwendet das Modul MOA-ID-Auth, dass in diesem Element hinterlegte Zertifikat zur Verschlüsselung der PVP 2.1 Assertion.

Hinweis: Fehlt im XML Element md:EntitiesDescriptor/md:EntityDescriptormd:SPSSODescriptor/md:KeyDescriptor das Attribut use wird das in diesem Element hinterlegte Zertifikat sowohl zur Prüfung der Signatur des Authentifizierungsrequest als auch zur Verschlüsselung der PVP 2.1 Assertion verwendet.

2.3 Zugangspunkte

Für die Kommunikation zwischen Service Provider und dem Modul MOA-ID-Auth stellt MOA-ID-Auth aktuell zwei PVP 2.1 spezifische Zugangspunkte zur Verfügung. Detailinformationen zu den beiden Zugangspunkten (Bindings) entnehmen finden Sie in der SAML2 Spezifikation.

• POST Binding: In diesem Fall erfolgt die Übertragung mittels http POST. Hierfür stellt MOA-ID-Auth den folgenden Zugangspunkt zur Verfügung.

https://<host>:<port>/moa-id-auth/pvp2/post

• Redirect Binding: In diesem Fall erfolgt die Übertragung mittels eines Redirects wobei die Daten als GET Parameter in der URL enthalten sind. Hierfür stellt MOA-ID-Auth den folgenden Zugangspunkt zur Verfügung.

https://<host>:<port>/moa-id-auth/pvp2/redirect

Hinweis: Die Zugangspunkte können auch direkt aus den von MOA-ID-Auth generierten Metadaten entnommen werden.

2.3.1 Authentifizierungsrequest

Der Authentifizierungsrequest wird vom Service Provider erstellt und an das Modul MOA-ID-Auth übermittelt. Zur Übertragung, muss je nach verwendetem Binding, einer der beiden Zugangspunkte und die entsprechende Kodierung der Parameter verwendet werden.

Folgende Minimalanforderungen an den Authentifizierungsrequest müssen erfüllt sein.

• Der Request muss durch den Service Provider signiert sein (sie Beispiel). Die Signatur wird durch das Modul MOA-ID-Auth mit Hilfe des in den Metadaten hinterlegten Zertifikats validiert. Schlägt die Signaturprüfung fehl oder ist keine Signatur vorhanden wird der Request abgewiesen und MOA-ID-Auth antwortet mit http Code 400 und der Fehlermeldung NO valid protocol request received!.
• Das der Wert des XML Element saml2p:AuthnRequest/saml2:Issuer muss den eindeutigen Identifier enthalten der für diese Online-Applikation bei MOA-ID-Auth hinterlegt ist (sie Beispiel).

Einen Beispielrequest finden Sie hier.

Hinweis: Detailinformationen finden Sie im Abschnitt Spezifikationen in der PVP 2.1 Spezifikation und der SAML2 Spezifikation.

2.3.2 Authentifizierungsresponse

Nach erfolgreicher Authentifizierung antwortet das Modul MOA-ID-Auth mit einer PVP 2.1 Assertion. Zur Übertragung der Assertion erfolgt an das in den Metadaten der Online-Applikation angegebene AssertionConsumerService (siehe Metadaten).

3 OpenID Connect

OpenID Connect ist ein Authentifizierungsprotkoll welches auf dem OAuth 2.0 Protokoll aufbaut. Dieses Protokoll erlaubt Online-Applikationen die Identifizierung und Authentifizierung von Benutzern, mit Hilfe des Modules MOA-ID-Auth. Der Vorteil von OpenID Connect im Vergleich zu auf SAML basierten Protkollen (PVP 2.1, SAML 1) ist der einfachere Aufbau der einzelnen Protokollnachrichten. Zusätzlich existieren einige frei Verfügbare Bibliotheken für unterschiedliche Programmiersprachen, welche OpenID Connect implementieren.

Bevor OpenID Connect in Kombination mit dem Modul MOA-ID-Auth verwendet werden kann muss das Modul MOA-ID-Auth konfiguriert werden. Detailinformationen zur Allgemeinen Konfiguration und zur online-applikationsspezifischen Konfiguration finden Sie im jeweiligen Abschnitt des Kapitels Konfiguration. TODO!

Die nachfolgende Beschreibung gibt einen kurzen Überblick zur Verwendung des Protkolls OpenID Connect in Kombination mit dem Modul MOA-ID-Auth. Detailinformationen zu OpenID Connect entnehmen Sie bitte der aktuellen OpenID Connect Spezifikation

3.1 Ablauf einer Anmeldung mittels OpenID Connect

Die nachfolgende Abbildung zeigt das Sequenzdiagramm eines Anmeldevorgangs mittels OpenID Connect und des Modules MOA-ID-Auth als Identityprovider. Aus Gründen der Übersichtlichkeit wurden die Teile welche die Kommunikation mit der Bürgerkartenumgebung oder die Vollmachten-Auswahl betreffen bewusst nicht berücksichtigt.

1. Der Benutzer verbindet sich zu einem Web-Portal (Service Provider) über das die Online-Applikation erreichtbar ist. Nach der Betätigung eines Login-Buttons wird der Anmeldevorgang ausgelöst.
2. Der Service Provider generiert den AuchCode Request und sendet diesen über den Browser an das Modul MOA-ID-Auth.
3. MOA-ID-Auth validiert den AuthCode Request.
4. MOA-ID-Auth leitet die BenutzerIn oder den Benutzer zur Bürgerkartenauswahl
   1. Die BenutzerIn oder der Benutzer Authentifiziert sich mit der gewählten Methode.
5. Nach erfolgreicher Authentifizierung erzeugt MOA-ID-Auth die AuthCode Response.
   1. Die AuthCode Response wird mittels Redirect an den Service Provider retourniert.
6. Der Service Provider validiert die AuthCode Response.
7. Der Service Provider generiert den AccessToken Request und sendet diesen an MOA-ID-Auth zum Abholen der Benutzerdaten.
8. MOA-ID-Auth validiert den AccessToken Request
9. MOA-ID-Auth generiert die AccessToken Response
   1. Retournierung der AccessToken Response an den Service Provider
10. Validieren der AccessToken Response
    1. Wird die Validierung gültig abgeschlossen kann die BenutzerIn oder der Benutzer am Service Provider angemeldet werden.

3.2 Zugangspunkte

Zur Verwendung von OpenID Connect stellt das Modul MOA-ID-Auth zwei Zugangspunkte zur Kommunikation mit der Online-Applikation zur Verfügung. Diese Zugangspunkte bezeichnen die URLs unter welchen das Modul MOA-ID-Auth die entsprechenden OpenID Connect Nachrichten entgegennimmt.

• AuthCode-Request: https://<host>:<port>/moa-id-auth/oauth2/auth
  Unter dieser URL wird der Authn Request entgegengenommen. Dieser Request startet den Authentifizierungsvorgang an der Online-Applikation. Hier finden Sie Detailinformationen zum Request und zur Response.
• AccessToken-Request: https://<host>:<port>/moa-id-auth/oauth2/token
  Unter dieser URL können nach erfolgreicher Authentifizierung die eigentlichen Authentifizierungsdaten am Modul MOA-ID-Auth abgeholt werden. Hier finden Sie Detailinformationen zum Request und zur Response.

3.3 Beschreibung der Nachrichten

Dieser Abschnitt beschreibt die einzelnen OpenID Connect spezifischen Nachrichten, welche zwischen der Online-Applikation und dem Modul MOA-ID-Auth während eines Authentifizierungsvorgangs ausgetauscht werden. Hierbei wird auch auf das Sequenzdiagramm aus Abschnitt 3.1 Bezug genommen.

3.2.1 AuthCode Request

Der AuthCode Request ist die Authentifizierungsanfrage einer Online-Applikation für eine BenutzerIn oder einen Benutzer. Folgende Parameter müssen mit dem AuthCode-Request mitgesendet werden, wobei für die Übertragung der Parameter sowohl http GET als auch http POST verwendet werden kann.

Nachfolgend ein Beispiel für einen OpenID Connect Authentifizierungsrequest an das Modul MOA-ID-Auth.

<form method="get" action="https://demo.egiz.gv.at/demoportal_moaid-2.0/oauth2/auth">
  <input type="hidden" value="code" name="response_type">
  <input type="hidden" value="https://demo.egiz.gv.at/demoportal-openID_demo" name="client_id">
  <input type="hidden" value="https://demo.egiz.gv.at/demoportal-openID_demo/securearea.action" name="redirect_uri">
  <input type="hidden" value="profile eID eID_gov mandate" name="scope"> 
  <input type="hidden" value="1152547590" name="state">
  <input type="submit" value="OpenID Connect login">
</form>

3.2.2 AuthCode Response

Das Ergebnis des AuthCode Requests wird an die redirect_uri der Online-Applikation gesendet. Die nachfolgenden Parameter werden dabei übergeben.

Nochfolgend ein Beispiel für eine AuthCode Response.

https://demo.egiz.gv.at/demoportal-openID_demo/securearea.action?state=1425782214234&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7 

3.2.3 AccessToken Request

Mit dem AccessToken Request können vom Service Provider der Online-Applikation die Anmeldedaten an der MOA-ID-Auth Instanz abgeholt werden. Für die Abholung müssen folgende Parameter mit dem AccessToken Request an MOA-ID-Auth übertragen werden, wobei für die Übertragung der Parameter sowohl http GET als auch http POST verwendet werden kann.

Nachfolgend ein Beispiel für einen AccessToken Request

<form method="POST" action="https://demo.egiz.gv.at/demoportal_moaid-2.0/oauth2/token">
  <input type="hidden" value="authorization_code" name="grant_type">
  <input type="hidden" value="https://demo.egiz.gv.at/demoportal-openID_demo" name="client_id">
  <input type="hidden" value="https://demo.egiz.gv.at/demoportal-openID_demo/securearea.action" name="redirect_uri">
  <input type="hidden" value="0adf1ec7-c2a6-4fd3-897c-456d0fb7b5cc" name="client_secret"> 
  <input type="hidden" value="4/P7q7W91a-oMsCeLvIaQm6bTrgtp7" name="code">
</form>

3.2.4 AccessToken Response

Die AccessToken Response beinhaltet ein signiertes JSON-Token welches alle angeforderten (Parameter scope im AuthCode Request) und vorhandenen Authentifizierungsdaten beinhaltet. Dieses JSON-Token ist mit einer JSON Web Signatur von MOA-ID-Auth signiert, wobei die Signatur alle angeforderten Daten einschließt. Details zur Konfiguration des Signatur Zertifikats finden Sie hier.

Nachfolgend ein Beispiel für einen AccessToken Response

{
	"access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid eID"
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
               yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
               NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
               fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
               AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
               Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
               NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
               QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
               K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
               XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
} 

3 SAML 1

A Referenzierte Spezifikation