Authentifizierung & Authorisierung

Die Authentifizierung erfolgt ausserhalb der API ausschliesslich über einen STS. Die API nimmt lediglich ein bereits gelöstes Bearer Token über den Header («Authorization») entgegen und validiert dieses über den konfigurierten STS.

Das Config UI und Swagger melden sich über den Authorization Code Flow mit PKCE am STS an. Beide sind Public Clients ohne Client Secret. Der Implicit Flow wird nicht verwendet.

Alternativ kann in Swagger unter «Authorize» ein beim STS bezogenes Bearer Token eingefügt werden. Achtung! Vor dem Token muss zwingend Bearer (mit Leerzeichen) stehen.

Swagger: Bearer Token einfügen

Falls die Validierung des Tokens erfolgreich ist, wird dem Benutzer die Authorisierung zu allen Controllern und Endpunkten der API gewährleistet. Die funktionale Berechtigung der API erfolgt durch die Benutzerrechte auf Basis bestehender Standardgruppen aus dem CMI Server. Alle Änderungen in CMI selbst werden mit dem Benutzer des übergebenen Tokens ausgewiesen.

Beispiel Client-Konfiguration

In dieser Anleitung wird eine Beispiel Client-Konfiguration für den STS-3 beschrieben. Die CMI API selbst braucht den Client nur für das Config UI und für den Login in Swagger. Beide verwenden den Authorization Code Flow mit PKCE.

{
  "ClientId": "<Client-ID (Bsp.: cmi-api-configui)>",
  "RequireClientSecret": false,
  "RequirePkce": true,
  "AccessTokenLifetime": 3600,
  "AllowedGrantTypes": [
    "authorization_code"
  ],
  "RedirectUris": [
    "regex:^<Protokoll>://<Server>:<Port>/<Mandant>/.*$"
  ],
  "PostLogoutRedirectUris": [
    "regex:^<Protokoll>://<Server>:<Port>/<Mandant>/.*$"
  ],
  "AllowedScopes": [
    "metatool",
    "openid",
    "profile"
  ],
  "AllowedCorsOrigins": [
    "<Protokoll>://<Server>:<Port>"
  ]
}

Protokoll, Server und Port beziehen sich auf die CMI API. Läuft die CMI API auf dem Default-Port (443 bei https, 80 bei http), entfällt :<Port> überall, weil der Browser den Default-Port nicht mitsendet.

RequireClientSecret
- false: Der Client ist ein Public Client ohne ClientSecrets. Config UI und Swagger senden kein Client Secret.
RequirePkce
- true: Erzwingt PKCE. Config UI und Swagger senden PKCE (S256).
AllowedGrantTypes
- authorization_code ist nötig.
- implicit ist nicht zulässig. Bei bestehenden Clients ist implicit zu entfernen.
RedirectUris und PostLogoutRedirectUris
- Das Muster deckt drei Ziele ab: das Config UI (/<Mandant>/), den Swagger-Redirect (/<Mandant>/swagger/oauth2-redirect.html) und den Swagger-Redirect einer Gruppe (/<Mandant>/groups/<Gruppenname>/swagger/oauth2-redirect.html).
- Das Muster ist direkt nach Server und Port verankert und auf den Pfad des Mandanten beschränkt. Ein Präfix-Muster ohne Pfadgrenze wie ^(https://server:443).* lässt fremde Ziele zu (z.B. https://server:443@evil.example/) und ist bei einem Public Client nicht zulässig.
- Punkte im Servernamen sind zu escapen (server\.example\.ch, im JSON mit doppeltem Backslash server\\.example\\.ch).
- Beispiel auf dem Default-Port: regex:^https://server/<Mandant>/.*$
AllowedCorsOrigins
- Ist nötig, weil Config UI und Swagger den Token-Request aus dem Browser senden.
- Beispiel auf dem Default-Port: https://server
AllowAccessTokensViaBrowser
- Wird beim Authorization Code Flow nicht verwendet. Bei bestehenden Clients kann der Wert entfernt oder auf false gesetzt werden.

Beispiel Token-Request

Um die CMI API verwenden zu können (API Requests) muss ein gültiges Token vorhanden sein. Hier ist ein STS-Client für den Grant-Type client_credentials.

Der OpenID-Client wird nicht für die API selbst benötigt, sondern vom aufrufenden System, das die API verwenden möchte.

{
  "ClientId": "<Client-ID (Bsp.: cmi-api-tokenrequest)>",
  "AccessTokenLifetime": 3600,
  "AllowedGrantTypes": [
    "client_credentials"
  ],
  "ClientSecrets": [
    {
      "value": "<Client-Secret SHA512 Encrypted>"
    }
  ],
  "AllowedScopes": [
    "metatool",
    "openid",
    "profile"
  ],
  "ClientCredentialsBackendUser": {
    "username": "<CMI-User>",
    "password": "<CMI-User Passwort>"
  }
}

Wenn der Client im STS konfiguriert ist, so kann mit dem folgenden Curl-Request ein Token bezogen werden:

curl --location --request POST '<Protokoll>://<Sts-Server>/<Mandant>/identity/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=metatool' \
--data-urlencode 'client_secret=<Client-Secret als Plain-Text>' \
--data-urlencode 'client_id=<Client-ID>'