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

ServiceAccount

Um die M2M-Kommunikation zu unseren oAuth2-API's zu ermöglichen unterstützen wir den urn:ietf:params:oauth:grant-type:jwt-bearer grant type gemäß RFC7521.

Ein ServiceAccount ist ein JSON-Dokument welches von uns bereit gestellt wird und alle Informationen enthällt die benötigt werden um einen Access-Token abzuholen.

Dokument

Attribut Beschreibung
version zB. v1
id
issuer
token_endpoint
audience
grant_type urn:ietf:params:oauth:grant-type:jwt-bearer
sub Ameise-Mitarbeiter-ID (alphanum, utf-8, max 40chars, case insensitiv)
scope freigegebene scopes (string[], zB. ["ameise.imports"])
jwk PrivateKey im JSONWebKey-Format
client_id
client_secret
created_at DateTime
expires_at DateTime
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
client Daten des Mandanten
- id (alphanum, latin1, max 40chars, case sensitiv)

Beispiel

(Platzhalter überwiegend aus dem ServiceAccount-Dokument)

Generiere ein JWS {jws}:

Header

{
  "alg": "ES512"
}

Payload

{
  "iss": "{issuer}",
  "sub": "{sub}",
  "aud": "{audience}",
  "iat": {UNIX_TIME_NOW()},
  "exp": {UNIX_TIME_NOW() + 5},
  "jti": "{UuidV4()}"
}

Signatur

ECDSASHA512(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  {jwk}
)

POST {token_endpoint}
Authorization: Basic {base64UrlEncode({client_id}:{client_secret})}
Content-Type: application/x-www-form-urlencoded

grant_type={grant_type}&assertion={jws}&scope={urlencode(scopes.join(" "))}

{"access_token":"IuDkPPqXKc6S90kMa9CL3amXxdeDXSwtMfUsH-Z_dHA.1DrDozmfeVIYcN3VdOaX4xHcM4Z-Tv8TR6iKAP3eJ4o","expires_in":3600,"scope":"scope1 scope2","token_type":"bearer"}

Warnung: Um nicht zu riskieren gesperrt zu werden, cache den Access-Token gemäß expires_in!

Warnung: Denke rechtszeitig daran das ein ServiceAccount abläuft!

Warnung: Ein ServiceAccount sollte nur für eine Applikation verwendet werden!