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 müssen 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/Desktop 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

Beispielkonfigurationen für die üblichen CMI Client-Anwendungen können unter CMI Default Clients gefunden werden.