cmi-webapi-forms

Diese Komponente ist zurzeit für verschiedene Aufgaben vorgesehen. Es werden Formulardaten von Anthrazit und JaxForms entgegengenommen und daraus Geschäfte oder Posteingänge im CMI generiert. Zudem gibt es für die PhZh separate Funktionen für die Erstellung von Posteingängen. Neu sind im CmiController auch generische Endpunkte definiert für die Kommunikation mit dem CMI Server Service. In Zukunft sollten nur noch diese verwendet werden.

Inhaltsverzeichnis

• Allgemeine Informationen
• Technische Informationen
• Installation & Konfiguration
• Troubleshooting / Mögliche Fehlerquellen

Allgemeines

• Status: Freigegeben
• Technische Ansprechperson: Milan Bursac, Benjamin Schäublin, Micha Aepli, Abdu Almaz
• Nur für speziellen Kunden: PhZh, Anthrazit und JaxForms sind Kundenprojekte / CmiController kann für alle Kunden verwendet werden.

Strategische Einordnung

Zurzeit sind verschiedene Controller als Kundenprojekt implementiert:

• AnthrazitController
• JaxFormsController
• PhZhController
• BurgergemeindeController

Diese sollten nach Möglichkeit nicht mehr verwendet werden. Neu soll der CmiController für die Kommunikation mit dem CMI Server Service genutzt werden.

Technisches

webapi.forms ist ein Windows-Service der einen Webservice mit diversen Endpunkten startet.

Eigenschaften

Die Komponente erfüllt folgende Eigenschaften:

• Stateless: Als stateless REST Service implementiert (wurde nicht getestet)
• Skalierbar/Multiinstanzfähig: Ja (wurde nicht getestet)
• Mehrmandantenfähig: nein, es kann nur ein CMI Server Service hinterlegt werden
• Proxyfähig: Ja, kann im appsettings.json definiert werden

Abhängigkeiten

• AnthrazitController

Service	Version	Anbindung	Protokoll	Standardports	Verfügbarkeit	Fehlertoleranzklasse
Anthrazit Formular	?	on request	HTTP/S	?	muss	Absturz
CMI Server Service	?	on request	HTTP/S	10003,10004	muss	Reconnect

• JaxFormsController

Service	Version	Anbindung	Protokoll	Standardports	Verfügbarkeit	Fehlertoleranzklasse
Jax Forms Formular	?	on request	HTTP/S	?	muss	Absturz
CMI Server Service	?	on request	HTTP/S	10003,10004	muss	Reconnect

• CmiController

Service	Version	Anbindung	Protokoll	Standardports	Verfügbarkeit	Fehlertoleranzklasse
CMI Server Service	19.8	on request	HTTP/S	10003,10004	muss	Reconnect

Fehlertoleranz

Wenn der CMI Server Service nicht erreichbar ist, können die Requests nicht erfolgreich abgesetzt werden. Die API gibt dann einen Error zurück.

Wenn im JaxForms oder Anthrazit ein Request abgesetzt wird, muss das CMI Forms API erreichbar sein.

Technologie Stack

Folgende Technologien werden eingesetzt:

• ASP.NET Core 8.0

Installation

Informationen zur Installation der Komponente.

Systemvoraussetzungen

Das Kapitel zeigt, welche Komponenten auf dem System installiert sein müssen.

Betrieb via IIS:

• ASP.NET Core 8.0 Runtime
• IIS Feature Rewrite Module

Betrieb als Windows Service: Keine

Installationsanleitung

Vollständige Anleitung zur Installation der Komponente inklusive benötigter Services.

Entwicklerhinweise

Für Neuentwicklungen nur noch den CmiController verwenden.

Konfigurationsmöglichkeiten

Folgende Konfigurationen sind möglich und können in der Konfigurationsdatei appsettings.json gesetzt werden.

ApiConfiguration

"ApiConfiguration": {
    "UseClientTokens": false,
    "IpWhitelist": "::1;127.0.0.1",
    "WriteDownJson": false,
    "PathToJsonFolder": "C:\\Forms\\Json",
    "CorsAllowedOrigins": "http://localhost:4200;http://localhost:5000"
}

• UseClientTokens: Wenn true wird erwartet, dass jeder Request bereits ein Bearer Token vom STS enthält. Dieses Token wird dann mittels cmi-common-webapi-core validiert.

• IpWhitelist: Die IP's werden Semikolon separiert aufgelistet. Mit einem * werden alle IP's akzeptiert.

• WriteDownJson: Gibt an, ob die eingegangenen Formulare in Text-Dateien abgespeichert werden oder nicht.

• PathToJsonFolder: Pfad zum Ordner, unter welchem die eingegangenen Formulare abgespeichert werden.

• CorsAllowedOrigins: Die Origins werden Semikolon separiert aufgelistet. Mit einem * werden alle Origins akzeptiert.

ServerService

"ServerService": {
    "StsBaseUrl": "{STS_BASE_URL}/{TENANT}",
    "ClientId": "{CLIENT_ID}",
    "ClientSecret": "{CLIENT_SECRET}",
    "AcrValues": "tenant:cmi_ag_local",
    "PrivateUrl": "http://localhost:10003",
    "User": "admin",
    "Password": "123",
    "CheckInComment": "First Check-In",
    "DocumentVersion": "Zwischenversion"
}

• StsBaseUrl (ehemals StsTokenEndpoint): Basis URL des Security Token Service (STS) eines Mandanten.

• ClientId: Client-Id für die Authentifizierung (Im STS konfiguriert)

• ClientSecret: Client-Secret für die Authentifizierung (Im STS konfiguriert)

• AcrValues: Name des Tenants. Dem Mandanten-Namen muss tenant: vorangestellt werden

• PrivateUrl: URL zum CMI Server Service. Die URL muss auf dem Owin-Privateport gerichtet sein

• User: (legacy) Name des technischen CMI Benutzers

• Password: (legacy) Passwort des technischen CMI Benutzers

• CheckInComment: CheckIn-Kommentar für die erstellten Dokumente

• DocumentVersion: Dokument-Version für die erstellten Dokumente. (Mögliche Werte: Unbekannt, Zwischenversion, Hauptversion, Schlussversion)

Serilog

Serilog bietet eine Diagnoseprotokollierung der Applikation für Dateien. Weiterführende Informationen finden Sie unter GitHub-Serilog.

"Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Debug",
        "System": "Debug"
      }
    },
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "C:\\temp\\logs\\forms\\forms-log.log",
          "rollingInterval": "Day"
        }
      },
      { 
        "Name": "Console" 
      }
    ]
}

• MinimulLevel: Minimum der Protokollereignisebenen. (Mögliche Werte: Verbose, Debug, Information, Warning, Error, Fatal)

• Path: Der Pfad zum Logging File

JaxForms

"JaxForms": {
    "ApiUrl": "https://cmi.jaxforms.com/formservice/services/rest",
    "token": "4c72b3c4-cb86-4a57-a9e4-83277cea27d0"
}

• ApiUrl: URL der JaxForms-API

• token: Token eines JaxForms-Benutzers (Wird für die API benötigt)

Proxy

"Proxy": {
    "UseProxy": false,
    "ProxyUrl": "http://localhost:808",
    "BypassOnLocal": false,
    "BypassList": [
    ]
} 

• UseProxy: true wenn ein Proxy verwendet werden soll

• ProxyUrl: URL des Proxy Servers

• BypassOnLocal: true wenn alle lokalen Requests nich über den Proxy laufen sollen

• BypassList: Array Liste mit allen Hosts die nicht über den Proxy laufen sollen

Troubleshooting

SwaggerUI ist unter /swagger erreichbar. Hier können die Endpunkte getestet werden.

403 Forbidden

Wenn die API ein 403 Forbidden-StatusCode zurückgibt, sollten die appsettings.json überprüft werden.

• Wenn ApiConfiguration::UseClientTokens = false:
• Die IP die auf die API zugreifft muss in der ApiConfiguration.IpWhiteList aufgeführt sein. Wenn dies nicht der Fall ist, wird der Zugriff auf die Seite verweigert und ein 403 Forbidden-Fehler zurückgegeben.

OAuth Flows testen

Im Swagger UI kann man auch gleich die OAuth Flows testen.

• Client Credentials
• Authorization Code mit PKCE
• Implicit

Dazu muss ein Client im STS entsprechend konfiguriert sein.

Client Credentials

{
  "ClientId": "{{CLIENT_ID}}",
  "ClientSecret": "{{CLIENT_SECRET}}"
  "AllowedGrantTypes": [ "client_credentials" ],
  "AllowedScopes": [ "metatool" ]
}

Authorization Code mit PKCE

Empfohlener Flow für Webanwendungen. Der Authorization Code Flow mit PKCE ist sicherer als der Implicit Flow.

Beim Authorization Code Flow sind folgende Einstellungen besonders zu beachten:

• RedirectUris: die redirect_uri an die der STS den code schickt muss hier hinterlegt sein.
• AllowedCorsOrigins: Die Origin, von der die Anfrage kommt, muss hier hinterlegt sein.

{
  "ClientId": "{{CLIENT_ID}}",
  "RequirePkce": true,
  "AllowedGrantTypes": [ "authorization_code" ],
  "ProtocolType": "oidc",
  "AllowAccessTokensViaBrowser": true,
  "AllowOfflineAccess": true,
  "RedirectUris": [ "https://{{FORMS_BASE_URL}}/swagger/oauth2-redirect.html" ],
  "AllowedCorsOrigins": [ "https://{{FORMS_BASE_URL}}" ],
  "AllowedScopes": [ "openid", "profile", "metatool" ]
}

Implicit

Aus Gründen der Rückwärtskompatibilität belassen wir diesen Flow im Swagger UI. Wenn möglich nicht mehr verwenden und durch Authorization Code Flow mit PKCE ersetzen.

Identisch zu Authorization Code mit PKCE, jedoch ohne RequirePkce und AllowedGrantTypes:

{
  "AllowedGrantTypes": [ "implicit" ]
}