Skip to content

Clients

Die Client-Konfiguration erfolgt pro Mandant und wird unter dem Schlüssel Clients als Liste geführt. Jeder Client benötigt eine eindeutige ClientId. Die Client ID kann grundsätzlich frei gewählt werden, jedoch verwenden einige Client-Anwendungen eine hart codierte Client ID, so dass nicht in jedem Fall eine freie Wahl besteht. Weitere Eigenschaften werden je nach Client-Anwendung benötigt. Grundsätzlich können die Eigenschaften der Client-Klasse des Duende IdentityServers verwendet werden. Nachfolgend werden die von CMI verwendeten Einstellungen aufgeführt.

{
  "Tenants": {
    "mandant": {
      "Clients": [
        {
          "ClientId": "webAppClient",
          [...]
        },
        {
          "ClientId": "metatool",
          [...]
        }
      ]
    }
  }
}

Standard Client Identifier

Clients sollten bei einer Anmeldung ihre ClientId mitteilen. Auf Basis der ClientId kann der STS weitere Entscheidungen treffen. Im CMI Umfeld werden folgende ClientId's verwendet:

  • metatool (Rich Client)
  • * webAppClient (CMI Schule, CMI Sitzung, Zusammenarbeit Dritte, Dossierbrowser und weitere, siehe Diverse Web Clients
  • appClient (Android und IOS Apps)
  • pushServiceClient (Push Service für den Web Client, dieser Client ist in der Dokumentation des Push Services ausgeführt)
  • webdav (WebDav Service für den Web Client, dieser Client ist in der Dokumentation des WebDav Services ausgeführt)
  • * webClient (CMI Web Client)

* Die Client ID webAppClient ist überladen. Viele Web-Komponenten verwenden diese Client ID hartcodiert. Das macht es schwierig, spezifische Konfigurationen für bestimmte Web-Komponenten zu machen. Der CMI Web Client verwendet standardmässig diese Client ID, durch eine Konfiguration kann jedoch eine andere Client ID verwendet werden. Siehe CMI Web Client.

Übliche Client-Eigenschaften

Die folgende Auflistung erläutert die üblichen Eigenschaften, die für einen Client konfiguriert werden. In den folgenden Kapiteln werden jedoch auch Beispiele für konkrete Clients aufgeführt.

  • ClientId: Identifier des verwendeten Clients.
  • AccesTokenLifetime: Zeitspanne in Sekunden, während der das Access Token des CMI STS gültig ist.
  • AllowedGrantTypes: Liste der erlaubten Grant Types (Standard: implicit).
  • AllowAccessTokensViaBrowser: Spezifiziert, ob die Client-Anwendung Tokens via Browser beziehen darf.
  • RedirectUris: Liste von URIs, auf welche nach erfolgreichem Login weitergeleitet werden darf.
  • PostLogoutRedirectUris: Liste von URIs, auf welche nach erfolgtem Logout weitergeleitet werden darf.
  • AllowedCorsOrigins: Liste von Origins, welche auf die CMI STS Ressourcen zugreifen dürfen. Siehe Cross Origin Ressource Sharing (CORS).
  • AllowOfflineAccess: Spezifiziert, ob der betroffene Clients Refresh Tokens beziehen kann (via dem offline_access-Scope).
  • AllowedScopes: Liste von erlaubten Scopes. Siehe Scopes und Ressourcen.

Client Secrets

Clients die ein Client-Secret benötigen, verwenden einen SHA-512 Hash des Secrets. Die Secrets werden in einer Liste in ClientSecrets konfiguriert.

Ein Secret beinhaltet folgende Eigenschaften:

  • Value (erforderlich): SHA-512 Hash des Secrets.
  • Description (optional): Eine frei wählbare Beschreibung des Secrets.
  • Expiration (optional): Ein Ablaufdatum für das Secret (ISO 8601 Format).
{
    "tenants": {
        "mandant": {
            "Clients": [
                {
                  "ClientId": "clientId",
                  "ClientSecrets": [
                      {
                          "value": "bd2b1aaf7ef4[...]ca4696b2ad6fe2b2",
                          "description": "The SHA-512 Hash of the Secret's Value"
                      }
                  ]
                }
            ]
        }
    }
}

Redirect Uris

Für jeden Client müssen Redirect Uris konfiguriert werden.

RedirectUris enthält eine Liste von zulässigen URIs, an die Token oder Autorisierungscodes zurückgegeben werden würfen.

PostLogoutRedirectUris enthält eine Liste von zulässigen URIs, zu denen nach dem Abmelden umgeleitet werden soll. Weitere Informationen können unter OIDC Connect-Sitzungsverwaltungsspezifikation abgerufen werden.

Folgende Schemes dürfen nicht verwendet werden: javascript:, data:, mailto:, ftp:, blob:, about:, ssh:, tel:, view-source:, ws: und wss:.

Neben einer Uri darf auch ein Regex-Ausdruck angegeben werden. Um anzuzeigen, dass es sich um ein Regex-Ausdruck handelt, musst der Präfix regex: verwendet werden. Der Regex-Ausdruck muss in jedem Fall mit einem Circumflex ^ beginnen.

Achtung: Die Verwendung eines Regex-Ausdrucks kann ein Sicherheitsrisiko darstellen. Regex-Ausdrücke können unabsichtlich so konstruiert werden, dass Redirect Uris erlaubt sind, die nicht vorgesehen sind. Ein Angreifer kann dies nutzen, um einen Client auf eine manipulierte Seite weiterzuleiten. Für produktive Konfigurationen sollten explizite Uris verwendet werden.

Hinweis: Bei Regex-Ausdrücken wird die Scheme-Einschränkung nicht zuverlässig geprüft. Es wird empfohlen, diese Schemes dennoch nicht zu verwenden.

Um einen ReDos-Angriff zu vermeiden, ist die Evaluierungszeit des Regex-Ausdrucks auf fünf Sekunden limitiert. Es wird die Standard-NFA-Regex-Engine von .NET verwendet. Der ECMA-262 Standard wird nicht verwendet. Folgende Regex-Optionen sind aktiviert:

  • IgnoreCase
  • CultureInvariant

Explizite Uris und Regex-Ausdrücke dürfen gemischt verwendet werden:

{
  "Clients": [
        {
          "ClientId": "webAppClient",
          "RedirectUris": [
                "regex:^https\:\/\/(develop|stage)\.emmenheim.ch\/(.*)",
                "regex:^https\:\/\/(develop|stage)\.emmenheim.ch\/(.*)",
                "https://localhost:4200/#/security/signin?_\u0026",
                "https://localhost:4200/assets/silent_refresh.html",

          ],
          "PostLogoutRedirectUris": [
                "regex:^https\:\/\/(develop|stage)\.emmenheim\.ch\/(.*)",
                "regex:^https\:\/\/(develop|stage)\.emmenheim\.ch\/(.*)",
                "http://localhost:4200/#/security/signout",
                "http://localhost:4200/#/security/signout?"
          ]
          // ...
        }
  ]
}

Grant Types / Protocol Flows

Mit der Eigenschaft AllowedGrantTypes werden die erlaubten Grant Types festgelegt, die ein Client durchführen darf. Grundsätzlich werden alle Grant Types vom CMI STS unterstützt, die das Duende IdentityServer Framework anbietet.

Mögliche Werte für AllowedGrantTypes sind:

Flow Kommentar
client_credentials
implicit
authorization_code inkl. PKCE (RFC 7636, Proof Key for Code Exchange)
hybrid Kombination aus Code und Implicit Flow.
password Achtung: Die neueste OAuth 2.0 Security Best Current Practice verbietet diesen Grant vollständig.
urn:ietf:params:oauth:grant-type:device_code Nicht von CMI getestet.
delegation Dies ist kein offizieller OAuth Flow.
urn:ietf:params:oauth:grant-type:jwt-bearer On-Behalf-Of; Dies ist kein offizieller OAuth Flow.

CMI Clients

Dieses Kapitel enthält Beispielkonfigurationen für die üblichen CMI Client-Anwendungen. Es wird der Beispielmandant emmenheim verwendet.

Desktop Client

Für den Desktop Client kann folgende Client-Konfiguration als Ausgangslage verwendet werden:

{
    "ClientId": "metatool",
    "AccessTokenLifetime": 43200,
    "AllowedGrantTypes": ["implicit"],
    "ProtocolType": "oidc",
    "AllowAccessTokensViaBrowser": true,
    "RedirectUris": ["oob://metatool/callback"],
    "PostLogoutRedirectUris": ["oob://metatool/logout"],
    "AllowOfflineAccess": true,
    "AllowedScopes": [
        "openid",
        "profile",
        "metatool"
    ]
}

Desktop Client im "nicht interaktiven" Modus

Der Desktop Client kann mittels Argumente gestartet werden. Dafür wird der Password Grant Type verwendet. Folgende Client-Konfiguration kann als Ausgangslage verwendet werden:

{
    "ClientId": "nonInteractiveDesktopClient",
    "AccessTokenLifetime": 43200,
    "AllowedGrantTypes": ["password"],
    "ClientSecrets": [
        {
            "value": "<Sha512 Hash des Secrets>"
        }
    ],
    "AllowedScopes": [
        "openid",
        "profile",
        "metatool"
    ]
}

Der Client kann dann folgendermassen gestartet werden:

.\cmi.client.main.exe -user=<Benutzername> -pw=<Passwort> -stsclientid=nonInteractiveDesktopClient -stsclientsecret=<ClientSecret als Plain-Text>

Diverse Web Clients

Es gibt diverse Web Client Anwendungen, die die Client ID webAppClient verwenden. Die folgende nicht abschliessende Liste verschafft einen Überblick:

  • CMI Mail
  • CMI Sitzungen
  • Dossierbrowser und Zusammenarbeit Dritte
  • CMI Schule
  • Dossierjournal

Achtung: Der CMI Web Client (welcher den Desktop Client ersetzten wird) verwendet aus Kompatibilitätsgründen mit dem CMI STS 2 diese Client ID per Default ebenfalls. Wird der CMI Web Client mit dem CMI STS 3 zusammen betrieben, wird empfohlen diese Client ID per Konfiguration zu überschreiben. Siehe dazu CMI Web Client.

Für diese Client-Anwendungen kann folgende Client-Konfiguration als Ausgangslage verwendet werden:

{
    "ClientId": "webAppClient",
    "AccessTokenLifetime": 14400,
    "AllowedGrantTypes": ["implicit"],
    "AllowAccessTokensViaBrowser": true,
    "AllowOfflineAccess": true,
    "AllowedScopes": [
        "openid",
        "profile",
        "metatool"
    ],
    "RedirectUris": [
        // CMI Mail, Dossierjournal
        "https://mail.emmenheim.ch/#/security/signin?_\u0026",
        "https://dossierjournal.emmenheim.ch/#/security/signin?_\u0026",
        // Mobile Clients
        "https://emmenheim.ch/sitzungsvorbereitung/emmenheim/#/auth/sts?login\u0026",
        "https://emmenheim.ch/dossierbrowser/emmenheim/#/auth/sts?login\u0026",
        "https://emmenheim.ch/zusammenarbeitdritte/emmenheim/#/auth/sts?login\u0026",
        // CMI Schule
        "https://schule.emmenheim.ch/#/mandant/schule.emmenheim.ch/auth/sts?mandant=schule.emmenheim.ch\u0026",
        "https://schule.emmenheim.ch/#/mandant/emmenheim/auth/sts?mandant=emmenheim\u0026"
    ],
    "AllowedCorsOrigins": [
        "https://mail.emmenheim.ch",
        "https://dossierjournal.emmenheim.ch",
        "https://webdav.emmenheim.ch",
        "https://emmenheim.ch",
        "https://schule.emmenheim.ch"
    ],
    "PostLogoutRedirectUris": [
        "https://mail.emmenheim.ch/#/security/signout",
        "https://emmenheim.ch/sitzungsvorbereitung/emmenheim/#/auth/sts?logout",
        "https://emmenheim.ch/dossierbrowser/emmenheim/#/auth/sts?logout",
        "https://emmenheim.ch/zusammenarbeitdritte/emmenheim/#/auth/sts?logout",
        "https://schule.emmenheim.ch/emmenheim/#/loggedOut"
    ]
}

App Clients

Für die Android und IOS App von Dossierbrowser und CMI Sitzungen wird die Client ID appClient verwendet.

{
    "ClientId": "appClient",
    "AllowedGrantTypes": ["implicit"],
    "ProtocolType": "oidc",
    "AllowAccessTokensViaBrowser": true,
    "AccessTokenLifetime": 43200,
    "RedirectUris": [
      // Uris fur die mobilen Clients "CMI Sitzungen" / Dossierbowser (IOS und Android)
      "https://emmenheim.ch/mobileclients/proxy/emmenheimsv/view/auth.html#/sts?login\u0026",
      "https://emmenheim.ch/sitzungsvorbereitung/emmenheim/view/auth.html#/sts?login\u0026"
      "https://emmenheim.ch/mobileclients/proxy/emmenheimdb/view/auth.html#/sts?login\u0026",
      "https://emmenheim.ch/dossierbrowser/emmenheim/view/auth.html#/sts?login\u0026",
    ],
    "AllowedCorsOrigins": ["https://emmenheim.ch"],
    "PostLogoutRedirectUris": [
      "file:///android_asset/www/view/auth.html#/sts?logout",
      "http://localhost:8080/www/view/auth.html#/sts?logout"
    ],
    "AllowOfflineAccess": true,
    "AllowedScopes": [
      "openid",
      "profile",
      "metatool"
    ]
}

CMI Web Client

Bei CMI Web Client handelt es sich um eine Web-Anwendung, die den Desktop Client langfristig ersetzt.

Für diese Client-Anwendungen kann folgende Client-Konfiguration als Ausgangslage verwendet werden:

{
    "ClientId": "webClient",
    "AccessTokenLifetime": 3600,
    "AllowedGrantTypes": ["implicit"],
    "AllowAccessTokensViaBrowser": true,
    "AllowOfflineAccess": true,
    "AllowedScopes": [
        "openid",
        "profile",
        "metatool"
    ],
    "RedirectUris": [
        "regex:^https\:\/\/webclient\.emmenheim\.ch\/\#\/security\/signin(.*)"
        "https://webclient.emmenheim.ch/assets/silent_refresh.html",
    ],
    "AllowedCorsOrigins": [
        "https://webclient.emmenheim.ch"
    ],
    "PostLogoutRedirectUris": [
        "https://webclient.emmenheim.ch/#/security/signout"
    ]
}

Achtung: Der CMI Web Client verwendet standardmässig die Client ID webAppClient um mit dem CMI STS 2 kompatibel zu sein. Im Kontext vom CMI STS 3 sollte diese Client ID nicht verwendet werden. Die Datei config.json des CMI Web Clients kann angepasst werden, damit die Client ID webClient verwendet wird. jsonc { "security": { "authority": "...", "client_id": "webclient", // overwrite der Client ID "automaticSilentRenew": true // silent refresh aktivieren }, //[...] }

Silent Refresh:

Wenn das Access-Token abgelaufen ist, leitet der CMI Web Client den Benutzer zurück auf den CMI STS um, damit sich der Benutzer erneut anmelden kann.

Der CMI Web Client ist in der Lage das Access-Token vor dem Ablauf durch ein neues Access-Token zu ersetzten, ohne dass der Benutzer eine Aktion ausführen muss. Dazu sind folgende Konfigurationen erforderlich:

  • Der Client muss folgende Redirect-Uri erlauben: https://<Basis Url des Web Clients>/assets/silent_refresh.html
  • Die AccessTokenLifetime ann heruntergesetzt werden, sollte 180 Sekunden jedoch nicht unterschreiten.
  • Beim Web Client muss in der Datei config.json die Option security.automaticSilentRenew auf true gesetzt sein.
  • Je nach Hosting-Szenario ist es erforderlich, dem Web Client das Einbetten des CMI STS in einem IFrame zu erlauben. Dazu muss der Web Client in die frame-ancestors Quellen in der CSP-Konfiguration hinzugefügt werden.

Hinweis: Der Silent Refresh erfordert, dass der Browser über eine gültiges CMI STS Session-Cookie verfügt. Ist diese Session abgelaufen, wird kein Silent Refresh mehr durchgeführt. Der Benutzer wird dann zum CMI STS umgeleitet, sobald das Access-Token abgelaufen ist. Aus diesem Grund sollte das Session-Cookie deutlich länger gültig sein, als die AccessTokenLifetime. Siehe Cookie-Lifetime, um das Session-Cookie zu konfigurieren.

Hinweis: "Silent Refresh"-Versuche werden nach dem ersten Fehler (Timeouts, 5XX-Status) abgebrochen und nicht wiederholt.

Push Service

Die Dokumentation zum Push Service enthält weitere Informationen darüber, wie dieser mit dem CMI STS zusammenarbeitet. Beim CMI STS kann der fix benannte Client pushServiceClient wie folgt hinterlegt werden:

{
    "ClientId": "pushServiceClient",
    "AccessTokenLifetime": 3600,
    "AllowedGrantTypes": ["client_credentials"],
    "ProtocolType": "oidc",
    "AllowAccessTokensViaBrowser": false,
    "AllowOfflineAccess": true,
    "ClientSecrets": [
        {
            "value": "<Sha512 Hash des Secrets>"
        }
    ],
    // ClientCredentialsBackendUser wird unter folgenden Bedingungen benötigt:
    // Push Service Version < 3.0 oder CMI Server Version < 23.
    // Ansonsten kann der Block 'ClientCredentialsBackendUser' entfernt werden
    "ClientCredentialsBackendUser": {
        "username": "pushServiceAdmin",
        "password": "<Passwort des technischen CMI Benuters>"
    },
    "AllowedScopes": [
        "push-api",
        "metatool"
    ]
}

Push Service 3.0 / CMI Server Service Release ab 23

Das Access Token wird mit Scope push-api gelöst, auf dessen Basis der CMI Server ab Release 23 die Autorisierung vornimmt. Der technische Benutzer in CMI Server wird nicht mehr benötigt. - Eintrag ClientCredentialsBackendUser kann aus der CMI STS Client-Konfiguration entfernt werden - Ein technischer Benutzer (i.d.R. mit dem Benutzernamen pushServiceAdmin) beim CMI Server wird nicht benötigt und kann entfernt werden

Push Service 2.0 / CMI Server Service Release bis und mit 22

Dabei muss ein technischer Benutzer beim CMI Server angelegt werden. Dessen Benutzername und Passwort wird bei ClientCredentialsBackendUser hinterlegt. Wenn der Push Service das korrekte Client Secret kennt, stellt der CMI STS ein Access Token mit den Claims des technischen Benutzers für den Push Service aus.

WebDav Service

Die Dokumentation zum WebDav Service enthält weitere Informationen darüber, wie dieser mit dem CMI STS zusammenarbeitet. Beim CMI STS kann der Client webdav wie gefolgt hinterlegt werden:

{
    "ClientId": "webdav",
    "AccessTokenLifetime": 43200,
    "AllowAccessTokensViaBrowser": true,
    "AllowedGrantTypes": [
        "delegation",
        "implicit"
    ],
    "RedirectUris": [
        "https://emmenheim.ch/webdav/account/callback"
    ],
    "AllowedScopes": [
        "openid",
        "profile",
        "metatool"
    ],
    "ClientSecrets": [
        {
            "value": "<Sha512 Hash des Secrets>"
        }
    ]
}

Siehe auch Delegation Grant für weitere Informationen zum Grant Type delegation. Wenn der WebDav Service das korrekte Client Secret kennt, kann er bestehende Access Tokens durch ein anderes Access Token ersetzen.