Das ID Austria System stellt OpenID Connect (OIDC) gemäß der OpenID Connect Spezifikation bereit. Die nachfolgende Beschreibung zeigt eine Anbindung einer Anwendung mittels OIDC am ID Austria System. Detailierte Beschreibungen zu OpenID Connect stehen unter dem nachfolgenden Link zur Verfügung: OIDC Spezifikationen

ID Austria spezifische Eigenschaften für OIDC

• Vom ID Austria System wird ausschließlich der Authorization Code Flow (Response-Type: code) entsprechend der OIDC Spezifikation unterstützt
• Eine Authentifizierung des Service Provider / Client mittels client_secret ist verpflichtend.
• Das ID Austria System fordert als client_id eine URL welche im Kontext der Anwendung liegen muss.
• Im ID Austria System erfolgt die Anforderung von Attributen über das Applikationsregister des ID Austria und somit wird in diesem Zusammenhang empfohlen die Scopes openid und profile anzufragen.
• Zusätzlich zu den in OIDC spezifizierten Claims, welche im Scope „profile“ definiert sind, unterstützt das ID Austria System spezifische Claims. Diese Claims sind gemäß dem PVP2 Attribut-Profil umgesetzt und sind dem OIDC Scope „profile“ zugeordnet.
  Link zum PVP2 Attribut-Profil: PVP2 Attribut-Profil     (Draft folgt in Kürze)

OIDC Endpunkte am IDP

• Produktivsystem
  • OIDC Configurations Discovery: https://eid.oesterreich.gv.at/.well-known/openid-configuration
  • Authorization Endpoint: https://eid.oesterreich.gv.at/auth/idp/profile/oidc/authorize
  • Token Endpoint: https://eid.oesterreich.gv.at/auth/idp/profile/oidc/token
  • JWKs URI: https://eid.oesterreich.gv.at/auth/idp/profile/oidc/keyset
• Testsystem
  •  OIDC Configurations Discovery: https://eid2.oesterreich.gv.at/.well-known/openid-configuration
  • Authorization Endpoint: https://eid2.oesterreich.gv.at/auth/idp/profile/oidc/authorize
  • Token Endpoint: https://eid2.oesterreich.gv.at/auth/idp/profile/oidc/token
  • JWKs URI: https://eid2.oesterreich.gv.at/auth/idp/profile/oidc/keyset

Die OpenID Connect Anbindung im ID Austria System steht sowohl für klassische Browser basierte Anwendung als auch für Applikationen auf mobilen Geräten zur Verfügung.  (Native) Mobile Apps können somit via OIDC eine Anmeldung mittels ID Austria integrieren. Was für mobile Apps speziell zu beachten ist, ist im zweiten Abschnitt beschrieben.

Anmeldung mittels OIDC

Eine ID Austria Anmeldung mittels OIDC kann in sämtlichen Szenarien durchgeführt werden. Beispiele dafür sind:

• mit einem herkömmlichen Web-Browser auf einem PC/Laptop
• mit einer nativen App
• mit einem mobilen Browser auf einem Smartphone

Hinweis: Wird die ID Austria Anmeldung auf einem mobilen Gerät durchgeführt, ist der Prozessfluss der Authentifizierung für den Benutzer davon abhängig, ob die ID Austria App am Smartphone installiert und initialisiert ist. Ob die ID Austria App installiert ist, oder nicht, hat keine Auswirkungen auf den Prozessfluss der OIDC Implementierung beim SP.

Jede OIDC Anmeldung startet mit einem Authentifizierungsrequest an den IdP. Dieser wird üblicherweise direkt vom Client (Browser, App) als HTTP GET  oder HTTP POST Request an den IdP gesendet. Der Request erfolgt an den Authorization Endpoint des IDP.

Beispiel für einen Authentifizierungsrequest bei Verwendung des OIDC Authorization Code Flow:

https://eid.oesterreich.gv.at/auth/idp/profile/oidc/authorize?response_type=code
&client_id=https%3A%2F%2Fbeispielservice.at
&redirect_uri=https%3A%2F%2Fbeispielservice.at%2Fcb
&scope=openid+profile+eid&state=1234567890

• response_type: Der Response Typ muss mit „code“ angegeben werden da vom ID Austria System nur der Authorization Code Flow unterstützt wird.
• client_id: Der eindeutige Identifikator der SP Applikation, die am ID Austria System registriert sein muss. Das ID Austria System fordert als client_id eine URL welche im Kontext der Anwendung liegen muss.
• scope: Definiert in OIDC das Set von Identitätsinformationen welche vom IDP angefordert werden. Im ID Austria System erfolgt die Anforderung von Attributen über das Applikationsregister des ID Austria und somit wird in diesem Zusammenhang empfohlen die Scopes openid und profile anzufragen.
  Hinweis: Zulässige Parameter für scope und response_type siehe Abschnitt Registrierung
• redirect_uri: Die Redirect URI definiert die Client-Callback URI an welche das ID Austria System die Authentication Response an den SP ausliefern soll. Hierfür sind ausschließlich http(s) URLs zulässig.
• state: Optionaler jedoch empfohlener Parameter als CSFR / XSRF Schutz um den State zwischen Request und Callback beizubehalten.

Hinweis: Der folgende OpenID Connect Authentifizierungsrequestparameter wird nicht unterstützt:

• request_uri: Das aktive Abholen eines Authentifizierungsrequests beim Service-Provider (OpenID Connect requests to be passed by reference) wird vom ID-Ausria-System nicht unterstützt und führt zum Abbruch des Anmeldevorgangs.
• response_mode=form_post: Der Response Mode form_post , welcher in OAuth 2.0 Form Post Response Mode definiert ist, wird vom ID-Ausria-System nicht unterstützt und führt zum Abbruch des Anmeldevorgangs.

Anschließend antwortet der IdP dem Client mit einer Auswahl an Möglichkeiten zur Authentifizierung (ID Austria via VDA oder ggf. eIDAS, wenn vom SP konfiguriert), wie in Abbildung 1 dargestellt.

Nach einer erfolgreichen Authentifizierung am IdP, antwortet dieser dem Client mit einer (erfolgreichen) Authentication Response, die den Authorization Code gemäß dem OIDC Authorization Code Flow beinhaltet.

Beispiel für eine erfolgreiche Authentication Response vom IdP:

HTTP/1.1 302 Found
Location: https://beispielservice.at/cb?code=QXV0aEhhbmRsZXIxfDIwMjA...&state=af0ifjsldkj

Der Authorization Code wird im Anschluss (üblicherweise vom SP Backend Service) in einem Token-Request an den Token-Endpoint des IdP gesendet, zusammen mit einem registrierten Client-Secret.

Beispiel für einen OIDC Token-Request:

POST https://eid.oesterreich.gv.at/auth/idp/profile/oidc/token
HTTP/1.1

Im Body des Post Requests werden die Parameter ‚code‘, ‚grant_type‘, ‚client_secret‘, ‚redirect_uri‘ und die ‚client_id‘ übermittelt. Die Verwendung eines ‚client_secrets‘ ist auf jeden Fall verpflichtend und unabhängig davon ob der Flow mit PKCE (RFC7636) abgesichert wurde oder nicht.

code=QXV0aEhhbmRsZXIxfDIwMjAtMDMtMzAgMTM6NTk....
&grant_type=authorization_code
&client_secret=secret
&redirect_uri=https://beispielservice.at/cb
&client_id=274582323476.beispielservice.at

Nach erfolgreicher Validierung des Authorization Codes durch den IdP, antwortet dieser mit einer OIDC Successful Token Response, die das OIDC idToken enthält. Dieses idToken liefert die angeforderten Attribute (Claims) in Form eines JSON Web Tokens.

Das vom IDP übertragene idToken ist immer mit einer JWS Signatur versehen und somit durch das ID Austria System signiert. Zusätzlich kann das idToken auch mittels eines am ID Austria SP Registrierungssystem (IDA-SPR) hinterlegten Verschlüsselungszertifikat verschlüsselt werden. Im Falle einer zusätzlichen Verschlüsselung des idToken ist dieses entsprechend der OIDC Spezifikation zuerst signiert und anschließend verschlüsselt.

Beispiel für ein OIDC Successful Token Response vom IdP
die vollständige Response inklusive JWS Signatur finden sie hier:

{
    "access_token": "ABlzaGliYm9sZXRoLWRhdGFzZWFsZXItZW5jU.....",
    "token_type": "Bearer",
    "expires_in": "600",
    "scope": "openid profile",
    "id_token": "eyJraWQiOiI4M2EzYzVmZDNlNWQ3YmZjMDI0NDNi....."
}

Beispiel für dekodiertes mit JWS signiertes OIDC idToken:
die vollständige idToken ohne JWS Signaturteil finden sie hier:

{
  "at_hash" : "eFoCYhxqGK5O8kDvqPd1uQ",
  "aud" : "https://eid.egiz.gv.at/eidpilot_q_oidc",
  "auth_time" : 1678892052,
  "exp" : 1678895653,
  "iat" : 1678892053,
  "iss" : "https://eid2.oesterreich.gv.at",
  "sub" : "IFOQP3T5XYLMSDOQAEGMF52MWGMWBPXN",
  "birthdate" : "1983-06-04",
  "urn:pvpgvat:oidc.eid_ccs_url" : "https://hs-abnahme.a-trust.at/securitylayer2",
  "urn:pvpgvat:oidc.pvp_version" : "2.2",
  "urn:pvpgvat:oidc.eid_citizen_qaa_eidas_level" : "http://eidas.europa.eu/LoA/high",
  "urn:pvpgvat:oidc.eid_online_identity_link" : 
...
  "given_name" : "XXXŐzgür",
  "sid" : "_8dbfcf553c7f9b6d10bd068bacc6405b",
  "urn:pvpgvat:oidc.eid_identity_status_level" : "http://eid.gv.at/eID/status/testidentity",
  "urn:pvpgvat:oidc.bpk" : "ZP-MH:KQMY8Sl9WsmBxrYrYOiFS2VkLyo=",
  "family_name" : "XXXTüzekçi"
}

Die oben dargestellte JWS Signatur beinhaltet den:

• JWS Signaturheader mit Informationen zum Signaturalgorithmus, …
• PayLoad welche die Attribute des Benutzer und weitere Authentifizierungsmerkmale beinhaltet
• JWS Signaturwert

Hinweis: Der sub Claim liefert einen transienten Identifier und ist somit nicht zur Wiedererkennung von Personen geeignet. Zur Wiedererkennung muss der bPK Claim verwendet werden.

Verwendung von OIDC in nativen Apps

Die Verwendung von OIDC ist grundsätzlich in allen Varianten ähnlich, d.h. unabhängig davon ob OIDC in einem Browser-basierten Flow verwendet wird oder in einem App2App Szenario bei der Integration der ID Austria Anmeldung in einer nativen App. Jedoch gilt es für das App2App Szenario folgende Punkte zu beachten:

Wird OIDC in eine native App integriert, kann als Rücksprungadresse (redirect_uri) ebenfalls ein URL Scheme angegeben werden, sodass nach der Anmeldung ein unmittelbarer Rücksprung in die App erfolgt. Es sind jedoch ausschließlich http(s) URLs zulässig.

Beispiel: https://beispielservice.at/cb

Bei der Verwendung von OIDC in nativen Apps empfiehlt RFC8252 die Verwendung des Code Authorization Flows. Da das ID Austria System jedoch die Verwendung von Client-Secrets als verpflichtend definiert ist eine Verwendung von PKCE (RFC7636) nicht zwingend vorgesehen.

Hinweis: Eine Verwendung von PKCE (RFC7636) in nativen Apps wird jedoch durch den IDP technisch unterstützt.

Weitere Details zur Verwendung von OIDC in mobilen Applikationen finden sich auch in den Hintergrundinformationen.

Fehlercodes

Im Folgenden werden Fehlercodes beschrieben, die bei einer OIDC-Authentifizierungsanfrage von einer externen App an die aufrufende App mit URL-Abfrageparametern zurückgeworfen werden können. Basierend auf den OpenID Connect Konventionen in dieser Form:

• state mit dem gleichen Wert wie in der Anfrage
• error ist immer invalid_request
• error_description enthält ein Format %s (%s): %s mit den folgenden Werten in der Reihenfolge:
  • Der Name der Top-Level-Ausnahme
  • Der Name der detaillierten Ausnahme
  • Die Nachricht der Top-Level-Ausnahme.

Beispiel: AuthenticationException (UserCancellationException): Benutzer hat Vorgang abgebrochen

Im Folgenden sind die Fehler aufgelistet, welche behandelt werden können. Eine App muss nicht zwingend auf jeden Fehler eingehen. Es wird empfohlen, zumindest zwischen Fehler, die vom Benutzer in der App Digitales Amt (DA) gelöst werden müssen, und temporären Fehler während des Authentifizierungsprozesses zu unterscheiden und dem Benutzer entsprechend darauf hinzuweisen (bspw. „Bitte die Digitales Amt App öffnen um den Fehler zu beheben“ oder „Bitte später noch einmal probieren„)