Skip to content

oAuth2 / OIDC

Abgrenzung

Dieses Dokument wird sich nicht mit den allgemeinen Prinzipien von oAuth 2 & OIDC befassen. Dieses Thema wurde bereits mehrfach behandelt und eine eigene Dokumentation richtet am Ende mehr Schaden an als sie an Nutzen hat.

Wir sind weitestgehend Standardkonform und somit wird sich dieses Dokument nur mit den Ameise-Spezifischen Implementierungen beschäftigen, bzw. die Stellen aufgreifen in denen die OpenID Foundation Interpretationsspielraum lässt.

Wichtig

Wir empfehlen niemals die Authentifizierung selbst zu implementieren. Für (fast) jede Sprache gibt es zertifizierte Bibliotheken die regelmäßig aktualisiert werden. Eine eigene Implementierung wird in den Communities pauschal als unsicher angesehen. Sollte der Eindruck entstehen, dass keine der existierenden Bibliotheken den eigenen Use-Cases abdeckt, ist es das wahrscheinlichste, dass der Use-Case allgemein nicht durch oAuth2 / OIDC abgedeckt wird und sollte überdacht werden.

Konfiguration

Integration- / Testumgebung

Issuer / idP: https://auth.inte.dionera.dev
OIDC-Discovery: https://auth.inte.dionera.dev/.well-known/openid-configuration

Produktion

Issuer / idP: https://auth.dionera.com
OIDC-Discovery: https://auth.dionera.com/.well-known/openid-configuration

oAuth2 Clients

Die, den oAuth2-Clients allgemein zur Verfügung stehenden, technischen Möglichkeiten, werden in dem OIDC-Discovery-Dokument beschrieben.

Authentifizierung an den API's

Die Ameise API's erwarten den oAuth2-Access-Token als Bearer im Authorization-Header

Authorization: Bearer [oAuth2-Access-Token]

Autorisierung an den API's

Der User muss dem oAuth2 Client den Zugriff auf seine Ressourcen (scopes) gewähren, i.d.R stimmen diese mit der Aufgabe einer API überein. Welche scopes für welche API benötigt werden, wird in den API-Beschreibungen ersichtlich.

Client Urls

Als Protokoll für Client-Uris unterstützen wir ausschließlich https.
Eine Ausnahmen machen wir für folgende Hostnamen in der Integration- / Testumgebung:

  • localhost
  • 127.0.0.1
  • ::1

SPA - Empfehlung

Wir empfehlen für eine Single Page Application einen oAuth-Proxy zu verwenden, welcher zuständig ist den normalen authorization code flow abzuhandeln und den Access/Refresh Token serverseitig speichert.

App

Auch für Apps machen wir keine Ausnahme beim Protokoll. Die Client-Authorization-Method muss aber none sein.

Scopes

Da das OIDC-Discovery-Dokument nur die Basis OIDC-Scopes aufführt, stellen wir hier eine vollständige Liste zur Verfügung:

Integration- / Testumgebung

https://id.inte.dionera.dev/.well-known/scopes

Produktion

https://id.dionera.com/.well-known/scopes

Claims

Im OIDC-ID-Token, bzw. in der oAuth2-Userinfo Route, stehen, je nach gewährten scopes, neben den standardisierten Pflichtfeldern, folgende zur Verfügung:

claim scopes Beschreibung
sub Ameise-Mitarbeiter-ID (alphanum, utf-8, max 40chars, case insensitiv)
locale de-DE/AT je nach Land des Mandanten
name profile
given_name profile
family_name profile
gender profile male/female, leer bei juristischen Personen
picture profile Url zum Profilbild
picture_id profile ID des Profilbilds falls andere Formate gewünscht werden
address address Adressdaten
- street_address address
- postal_code address
- locality address
- country address de/at
email email
phone phone Mobilfunknummer
broker Daten des Vermittlers
- id (alphanum, utf-8, max 40chars, case insensitive)
- parent_id ID des übergeordneten Vermittlers
- root_id ID des Hauptvermittlers (boolean)
- is_root Dieser Vermittler ist ein Hauptvermittler
- name profile
- logo profile falls vorhanden
- logo_id profile Falls vorhanden und andere Formate für das Logo gewünscht werden
client Daten des Mandanten
- id (alphanum, latin1, max 40chars, case sensitiv)
- country de/at
ameise/permissions ameise/permissions Liste mit den Rechten aus der Ameise, z.B ['ameise', 'verwaltung', ...]
client_id deprecated
broker_id deprecated