Konfiguration

Dieses Kapitel beschreibt die unterschiedlichen Konfigurationsoptionen der Authority. Pflichtfelder sind mit einem ❗️ gekennzeichnet. Die Konfiguration der Authority erfolgt über eine JSON Datei. Beispiel:

{
  "issuerUrl": "http://authority:11560",
  "applicationPort": 11560,
  "accessTokenTTL": 3600,
  "idTokenTTL": 3600,
  "sessionTTL": 1209600,
  "development": {
    "builtInReactDevServer": false,
    "detailedErrors": true,
    "disableHttpsEnforcement": true,
    "enableLocalhostImplicit": true,
    "fixWrongHostnames": true
  },
  "studio": true,
  "portals": [
    {
      "clientId": "portal",
      "rootUrl": "http://localhost:8082"
    }
  ]
}

IssuerUrl❗️

Die issuerUrl ist die URL unter der die Authority erreichbar ist und ist zwingend erforderlich. Alle Clients müssen die Authority unter dieser URL erreichen können.

Beispiel:

{
  "issuerUrl": "http://authority:11560",
  "applicationPort": 11560
}

Application Port

Über den applicationPort wird festgelegt auf welchen Port der HTTP Server der Authority startet.

Beispiel:

{
  "applicationPort": 11560
}

{
  "applicationPort": 80,
  "issuerUrl": "https://my-authority.prd"
}

accessTokenTTL

Der accessTokenTTL ist der Zeitraum in Sekunden, in dem ein Access Token gültig ist. Nach Ablauf dieses Zeitraums muss ein neuer Access Token angefordert, oder erneuert werden. Der Standardwert ist 3600 Sekunden (1 Stunde). Dieser Parameter ist nicht zwingend erforderlich.

Beispiel:

{
  "accessTokenTTL": 3600
}

idTokenTTL

Der idTokenTTL ist der Zeitraum in Sekunden, in dem ein ID Token gültig ist. Nach Ablauf dieses Zeitraums muss ein neuer ID Token angefordert, oder erneuert werden. Der Standardwert ist 3600 Sekunden (1 Stunde). Dieser Parameter ist nicht zwingend erforderlich.

Beispiel:

{
  "idTokenTTL": 3600
}

sessionTTL

Der sessionTTL bezeichnet die Gültigkeitsdauer in Sekunden einer Session. Der Standardwert ist 1209600 Sekunden (14 Tage).

Beispiel:

{
  "sessionTTL": 1209600
}

anonymousSessionTTL

Der anonymousSessionTTL bezeichnet die Gültigkeitsdauer in Sekunden einer Anonymen Session. Der Standardwert ist 3600 Sekunden (1 Stunde).

Beispiel:

{
  "anonymousSessionTTL": 3600
}

Development

Mit diesen Einstellungen können einige Produktiveinstellungen überschrieben werden. Sie sind besonders praktisch für die Entwicklung und den lokalen Betrieb. Die Einstellung akzeptiert folgende Werte:

Wird ein Objekt übergeben, muss dieses die folgenden Eigenschaften enthalten:

Bespiele:

Keine Entwicklungsfunktionalitäten aktiviert:

{
  "development": false
}

Alle Entwicklungsfeatures aktiviert:

{
  "development": true
}

Einige Entwicklungsfeatures aktiviert:

{
  "development": {
    "builtInReactDevServer": false,
    "detailedErrors": true,
    "disableHttpsEnforcement": true,
    "enableLocalhostImplicit": true,
    "fixWrongHostnames": true,
    "additionalCspDirectives": {
      "formAction": ["https://localhost"],
      "connectSrc": ["https://localhost", "http://localhost"]
    }
  }
}

Studio

Konfiguriert wie das Studio zusammen mit der Authority verwendet werden kann. Die Einstellung akzeptiert folgende Werte:

Für die erweitere Konfiguration muss ein Objekt übergeben werden, das die folgenden Eigenschaften enthalten:

Beispiele:

Keine Verwendung des Studios:

{
  "studio": false
}

Verwendung des Studios mit Standardkonfiguration:

{
  "studio": true
}

Verwendung des Studios mit erweiterter Konfiguration:

{
  "studio": {
    "enabled": true,
    "scope": "openid profile email engine_read engine_observer engine_write custom_scope1 custom_scope2",
    "accessTokenTTL": 600
  }
}

Portals

Konfiguriert die Instanzen von 5Minds Portalen, welche mit der Authority verwendet werden können. Für diese Einstellungen wird eine Liste übergeben. Die Werte in der Liste müssen folgende Eigenschaften enthalten:

Beispiele:

Keine Portale konfiguriert:

{
  "portals": []
}

Ein Portal konfiguriert:

{
  "portals": [
    {
      "clientId": "portal",
      "rootUrl": "http://localhost:8082"
    }
  ]
}

Zwei Portale konfiguriert:

{
  "portals": [
    {
      "clientId": "portal",
      "rootUrl": "http://localhost:8082"
    },
    {
      "clientId": "portal2",
      "rootUrl": "http://localhost:8083"
    }
  ]
}

Portal mit erweiterter Konfiguration:

{
  "portals": [
    {
      "clientId": "portal",
      "rootUrl": "http://localhost:8082",
      "scope": "openid profile email engine_read engine_observer engine_write custom_scope1 custom_scope2",
      "accessTokenTTL": 600
    }
  ]
}

External Task Workers

Konfiguriert die Instanzen von External Task Workers, welche mit der Authority verwendet werden können. Für diese Einstellungen wird eine Liste übergeben. Die Werte in der Liste müssen folgende Eigenschaften enthalten:

Beispiele:

Keine External Task Workers konfiguriert:

{
  "externalTaskWorkers": []
}

Ein External Task Worker konfiguriert:

{
  "externalTaskWorkers": [
    {
      "clientId": "test_etw",
      "clientSecret": "abc"
    }
  ]
}

Ein External Task Worker mit erweiterter Konfiguration:

{
  "externalTaskWorkers": [
    {
      "clientId": "test_etw",
      "clientSecret": "abc",
      "scope": "engine_etw custom_scope1 custom_scope2",
      "accessTokenTTL": 600
    }
  ]
}

Andere Clients

In den Einstellungen für otherClients können weitere Clients erstellt und konfiguriert werden, die nicht aus dem ProcessCube kommen. Diese können verschiedene Grant Types benutzen und haben ihre eigenen IDs, Secrets und Scopes.

Hier ist ein Beispiel eines Clients mit dem Grant Type “Implicit”:

"otherClients": [
    {
      "clientId": "another_client",
      "scope": "openid profile email",
      "grant_types": ["implicit"],
      "response_types": ["id_token token"],
      "redirect_uris": ["http://authority:11560/acr/username_password/admin"]
    }
  ],

Ein anderes Beispiel für einen Clients mit dem Grant Type “Client Credentials”:

"otherClients": [
    {
      "clientId": "Terminalportal",
      "clientSecret": "973apMILx97C9u7GmSl5dbwdXXIPxvik",
      "scope": "openid profile email engine_read engine_observer engine_write schauf_lagerverwaltung anon_portal",
      "grant_types": [
        "client_credentials",
        "authorization_code"
      ],
      "redirect_uris": ["http://localhost:8083/signin-oidc"],
      "accessTokenTTL": 600
    }
],

Scopes

Mit der scopes Einstellungen können die Claims und Scopes der Authority konfiguriert werden. Die Einstellung ist ein optionales Objekt mit folgenden Werten:

Keine ProcessCube Scopes und Claims:

{
  "scopes": {
    "skipProcessCubeScopes": true
  }
}

Keine OpenID Scopes und Claims:

{
  "scopes": {
    "skipOidcScopes": true
  }
}

Additional Scopes:

Im additionalScopes Objekt können neue Scopes und die dazugehörigen Claims konfiguriert werden. Jeder Schlüssel stellt dabei den Scopenamen dar. Der Wert des Schlüssels ist ein Objekt mit den Feldern:

• claims: Liste von Claims, welche zu diesem Scope zugehörig sein sollen.
• description: Eine Beschreibung des Scopes.

Beispiele:

Eigene Scopes und dazugehörige Claims hinzufügen:

{
  "scopes": {
    "additionalScopes": {
      "interesting_data_scope": {
        "description": "This scope requests claim data that I find interesting!",
        "claims": ["birthdate", "gender", "address", "picture"]
      },
      "boring_data_scope_2": {
        "description": "This scope requests claim data that I find boring!",
        "claims": ["family_name", "email_verified", "website"]
      }
    }
  }
}

Zusätzliche Claims

Neben neuen Scopes und ihren dazugehörigen, bereits existierenden Claims, können auch neue Claims erstellt und der Authority hinzugefügt werden:

{
  "claims": {
    "has_superpowers": {
      "type": "boolean",
      "description": "Indicates whether the user has superpowers."
    },
    "favorite_beverage": {
      "type": "string",
      "description": "The user's favorite drink."
    }
  }
}

Database

Damit die Authority ihre Daten speichern kann, muss eine Datenbank konfiguriert werden.

Die Authority verwendet Sequelize . Das Konfigurationsobjekt wird an Sequelize übergeben. Die Einstellungen sind in der Dokumentation von Sequelize  zu finden.

Beispiele:

Verwendung von SQLite als Datenbank:

{
  "database": {
    "dialect": "sqlite",
    "storage": "storage/database.sqlite"
  }
}

Verwendung von PostgreSQL als Datenbank:

{
  "database": {
    "dialect": "postgres",
    "host": "localhost",
    "port": 5432,
    "username": "postgres",
    "password": "postgres",
    "database": "authority"
  }
}

Verwendung von MSSQL als Datenbank:

{
  "database": {
    "dialect": "mssql",
    "host": "localhost",
    "port": 1433,
    "username": "SA",
    "password": "mssql",
    "database": "authority"
  }
}

Username & Password Extension (UPE)

Die interne Username Password Extension kann im Bereich username_password konfiguriert werden.

Beispiel:

{
  "extensions": {
    "configs": {
      "username_password": {
        "skipConsentPageForClientIds": ["upe_client", "portal", "atlas_studio"],
        "customization": {
          "title": "5Minds Authority",
          "logoPath": "../../configs/assets/logo.png"
        },
        "passwordPolicy": {
          "regex": ".{8,}",
          "mismatchMessage": "Password must contain at least 8 characters."
        }
      }
    }
  }
}

Password Policy

Es kann eine eigene Richtlinie konfiguriert werden, die Anforderungen an neue Passwörter festlegt. Beim Anlegen neuer Accounts und Ändern von Passwörtern werden diese stets mit der Richtlinie abgeglichen. Diese Richtlinie wird über einen regulären Ausdruck definiert. Außerdem kann eine Nachricht konfiguriert werden, die bei Verletzung der Richtlinien angezeigt wird. Zur Konfiguration wird das Feld passwordPolicy verwendet. Dieses erwartet ein Objekt mit den zwei optionalen Feldern regex und mismatchMessage.

Extensions

Mit der extensions Einstellung können die Extensions der Authority konfiguriert werden. In dieser Einstellung sind folgende Werte möglich:

Jede Extension erhält automatisch ihren Abschnitt aus dem configs Wert. Die Abschnitte verwenden den Namen der Erweiterung als Schlüssel, die Erweiterung legt die Struktur des Wertes fest.

Beispiele:

Konfiguration der Erweiterung mit den Namen test_erweiterung:

{
  "extensions": {
    "configs": {
      "test_erweiterung": {
        "foo": "value1",
        "bar": "value2"
      }
    }
  }
}

Festlegen des Pfades zu den Erweiterungen:

{
  "extensions": {
    "path": "./extensions2"
  }
}

Festlegen des Pfades zu den Erweiterungen und Konfiguration der Erweiterung mit dem Namen test_erweiterung:

{
  "extensions": {
    "path": "./extensions2",
    "configs": {
      "test_erweiterung": {
        "foo": "value1",
        "bar": "value2"
      }
    }
  }
}

Informationen zu den einzelnen Erweiterungen finden sich im Abschnitt Externe Identitätsprovider.

Konifguration über Environment-Variablen

In manchen Anwendungsfällen ist es nicht möglich oder nicht wünschenswert, eine Konfigurationsdatei zu hinterlegen. In diesen Fällen kann die Authority über Environment-Variablen konfiguriert werden.

Um eine beliebige Option mit einer ENviornment-Variable zu konfigurieren, kann einfach eine Environment-Variable definiert werden, deren Namen den gleichen Namen wie die zu konfigurierende Option hat. Der Wert der Environment-Variable bestimmt dann den Wert der Konfigurationsoption. Hierbei muss der Wert immer als String (in einfachen Anführungszeichen) angegeben werden. Um den Port zu konfigurieren, wird zum Beispiel die Environment-Variable port='11560' angelegt.

Bei genesteten Optionen wird der Pfad durch doppelte Unterstriche (__) deklariert. Die Option dialect im Bereich database wird zum Beispiel mit database__dialect='sqlite' konfiguriert.

Auch Arrays von Strings oder anderen primitiven Typen können als Environement-Variable angegeben werden. Hierbei ist zu beachten, dass dass Array an sich als String in einfachen Anführungszeichen angegeben wird

Empfehlung für das Layout von Ordnern und Dateien

Unsere Empfehlung ist, die Konfigurationen der Produkte im Wurzelverzeichnis des Projektes in einem Ordner namens .processcube zu lagern, und die Konfiguration des jeweiligen Produkts in einen separaten Unterordner zu legen.

So ergibt sich die Struktur:

• .processcube
  • authority
    • config.json
  • engine
    • config.json
• docker-compose.yml