ADOIT SAML Guide

Einführung

Willkommen beim ADOIT SAML Guide, Ihrer Anlaufstelle für die Einrichtung von SAML-basierter Authentifizierung in ADOIT. So können Sie Authentifizierungsprozesse optimieren und Benutzerdaten synchronisieren.

SAML 2.0 bietet ein robustes Framework zur Abwicklung von Authentifizierung und Autorisierung in ADOIT. Durch die Nutzung von SAML Identity Providern (IdP) wie Microsoft Entra ID kann Single Sign-On (SSO) schnell implementiert werden.

Das können Sie von diesem Guide erwarten:

• Einführung: Genau da, wo Sie jetzt sind. Lernen Sie die wichtigsten Begriffe kennen und machen Sie sich mit den Grundlagen des SAML-Authentifizierungsablaufs vertraut. Wenn Sie bereits mit der Materie vertraut sind, können Sie dieses Kapitel überspringen.
• Voraussetzungen: Erfahren Sie, welche Voraussetzungen Sie erfüllen müssen, bevor Sie mit der SAML-Konfiguration beginnen.
• SAML IdP konfigurieren: Allgemeine Informationen über die von ADOIT unterstützten SAML IdPs und wie Sie Microsoft Entra ID Schritt für Schritt konfigurieren.
• ADOIT konfigurieren: Wie Sie ADOIT an den von Ihnen gewählten IdP anpassen.
• Mehr: Zusätzliche Ressourcen zur Bewältigung von Herausforderungen bei der Authentifizierung, vom Zertifikatswechsel bis zur Änderung des Anmeldenamens.

Einige Begriffe, die Sie kennen sollten

Begriff	Akronym	Definition
Active Directory	AD	Microsofts Verzeichnisdienst zur Verwaltung von Domänenressourcen. Speichert Informationen über Benutzer, Computer und andere Ressourcen innerhalb eines Netzwerks und ermöglicht eine zentrale Authentifizierung und Autorisierung.
Identity Provider	IdP	Im Kontext von SAML ist der Identity Provider die Entität, die für die Authentifizierung von Benutzern und die Bereitstellung von Identitätsinformationen an Service Provider (SPs) verantwortlich ist. Er verwaltet Informationen über Benutzer und deren Authentifizierungsstatus.
Lightweight Directory Access Protocol	LDAP	LDAP ist ein standardisiertes Protokoll zur Verwaltung und Abfrage von Verzeichnisdiensten wie Active Directory. Es bietet eine Möglichkeit für Clients, Verzeichnisinformationen über ein Netzwerk abzufragen und zu ändern.
Microsoft Entra ID	ME-ID	Microsoft Entra ID ist Microsofts cloudbasierter Identitätsanbieterdienst, der Organisationen die Verwaltung der Benutzerauthentifizierung und den Zugriff auf Anwendungen und Dienste ermöglicht. Er unterstützt die Single Sign-On (SSO)-Funktionalität und integriert sich mit verschiedenen Microsoft-Produkten und Anwendungen von Drittanbietern.
Security Assertion Markup Language	SAML	SAML ist ein auf XML basierendes Framework zum Austausch von Authentifizierungs- und Autorisierungsdaten zwischen einem Identity Provider (IdP) und einem Service Provider (SP). Es erleichtert das Single Sign-On (SSO) und ermöglicht einen nahtlosen Zugriff auf mehrere Anwendungen mit einem einzigen Satz Anmeldeinformationen.
Service Provider	SP	Im SAML-Terminologie ist ein Service Provider (SP) eine Webapplikation oder ein Dienst, der die Authentifizierung und Autorisierung an einen Identity Provider (IdP) delegiert. Er verlässt sich auf den IdP, um Benutzeridentitäten zu überprüfen und den Zugriff auf geschützte Ressourcen zu gewähren.
Single Sign-On	SSO	Single Sign-On (SSO) ist ein Authentifizierungsprozess, der Benutzern ermöglicht, auf mehrere Anwendungen oder Dienste mit einem einzigen Set von Anmeldeinformationen zuzugreifen. Sobald authentifiziert, können Benutzer zwischen verschiedenen Anwendungen navigieren, ohne ihre Anmeldeinformationen erneut eingeben zu müssen.
User Agent	UA	Ein User Agent (UA) ist ein HTTP-Client, typischerweise ein Webbrowser oder eine mobile Anwendung, der mit Webservern interagiert, um Webinhalte abzurufen und anzuzeigen. Er sendet Anfragen für Ressourcen und verarbeitet Antworten von Servern, was es Benutzern ermöglicht, im Web zu surfen und Online-Dienste zu nutzen.

SAML verstehen

SAML ist ein XML-basiertes Datenformat mit offenem Standard für den Austausch von Authentifizierungs- und Autorisierungsdaten zwischen Parteien, insbesondere zwischen einem Identity Provider (IdP) und einem Service Provider (SP). Ein IdP ist eine Instanz, die Benutzer authentifizieren kann und Kenntnis von den Gruppenmitgliedschaften der Benutzer und anderen organisatorischen Details hat. Der SP ist die eigentliche Webapplikation, die die Authentifizierung an den IdP delegiert.

Folgende Abbildung (Englisch) veranschaulicht den Authentifizierungsprozess als Interaktion zwischen dem User Agent (UA), dem IdP und dem SP.

Ein wichtiges Merkmal des SAML-Protokolls ist die Tatsache, dass es keine Server-zu-Server-Kommunikation gibt. Der gesamte Nachrichtenfluss erfolgt über den UA mittels Redirects und (möglicherweise automatisch übermittelten) POST-Anfragen.

Wenn ein Benutzer versucht, ohne gültige Session auf die Webapplikation des SPs zuzugreifen, generiert der SP eine SAML-Authentifizierungsanfrage und leitet den UA auf die URL des IdP um. Die Authentifizierungsanfrage wird als Parameter des Query-Strings gesendet. Die IdP kann die Herkunft der Authentifizierungsanfrage validieren, indem er überprüft, ob sie mit dem Zertifikat des SPs signiert wurde.

Der nächste Schritt ist die Authentifizierung des Benutzers, für die verschiedene Verfahren verwendet werden können, darunter formularbasierte Authentifizierung, integrierte Windows-Authentifizierung (einschließlich SSO), Multi-Faktor-Authentifizierung und andere. Wenn die Authentifizierung erfolgreich ist, stellt der IdP die Authentifizierungsantwort zusammen. Diese enthält eine Security Assertion mit den so genannten Claims, die zum Transport von Informationen über den Benutzer verwendet werden. Sobald der UA diese Informationen an den SP sendet, kann die Antwort durch Verifizierung der Signatur validiert werden. Der SP kann dann die erhaltenen Informationen verwenden, um die Session des Benutzers mit der Webapplikation aufzubauen.

Voraussetzungen

Bevor Sie ADOIT für die Verwendung von SAML zur Authentifizierung konfigurieren können, müssen Sie Folgendes tun:

• Ein Autorisierungskonzept festlegen

• SSL-Zertifikate beschaffen und konfigurieren

• ADOIT mit SSL installieren

• ADOIT Benutzergruppen erstellen

Ein Autorisierungskonzept festlegen

Bei der Autorisierung wird festgelegt, auf welche Aktionen oder Ressourcen ein Benutzer innerhalb eines Systems oder einer Anwendung zugreifen darf. Dies geht Hand in Hand mit der Authentifizierung, bei der die Identität des Benutzers überprüft wird. Während die Authentifizierung bestätigt, wer der Benutzer ist, bestimmt die Autorisierung, was der Benutzer nach der Authentifizierung innerhalb des Systems tun kann.

Einrichten von Gruppen in ADOIT und am IdP

Ein effektives Autorisierungskonzept für SAML-basierte Authentifizierung in ADOIT erfordert die Einrichtung von Gruppen sowohl innerhalb von ADOIT als auch auf der IdP-Seite (z. B. Microsoft Entra ID).

Berechtigungen in ADOIT: Ein kurzer Überblick

In ADOIT wird der Zugriff auf Inhalte wie Modelle und Objekte in der Regel über Benutzergruppen und nicht über einzelne Benutzer gewährt. Die Gruppenberechtigungen werden dann an alle Mitglieder einer Gruppe vererbt.

Der Zugriff auf Funktionalitäten wie Freigabeworkflows oder die Erstellung von Reports wird jedoch über System-Rollen gesteuert. Durch Zuweisung von System-Rollen an Benutzergruppen werden die mit diesen Rollen verbundenen Berechtigungen automatisch auf alle Gruppenmitglieder übertragen.

Dieser Ansatz ermöglicht es, mit geringem Aufwand Berechtigungen für eine große Anzahl von Benutzern zu verwalten.

Mitarbeiter in Ihrer Organisation mit ADOIT Benutzergruppen verbinden

Sie können die Mitarbeiterin Ihrer Organisation auf unterschiedliche Weise mit ADOIT-Benutzergruppen verknüpfen:

• Manuelle Zuweisung: Benutzer können über die ADOIT Administration manuell zu ADOIT Benutzergruppen zugewiesen werden. Dieser Ansatz kann jedoch insbesondere bei einer großen Anzahl von Benutzern umständlich und fehleranfällig werden.

• IdP-Integration: Wir empfehlen, Benutzer mithilfe des IdPs zu ADOIT Benutzergruppen zuzuweisen. Dabei werden IdP-Gruppen auf ADOIT-Benutzergruppen gemappt. Wenn Benutzer ihre Rolle oder Abteilung wechseln, werden ihre Berechtigungen automatisch aktualisiert. Neue Teammitglieder erhalten ebenfalls sofort die richtigen Berechtigungen. Dieser Ansatz vereinfacht das Onboarding und reduziert den manuellen Aufwand.

Strategien für die Gruppenzuordnung festlegen

Zwei gängige Strategien für das Mapping von IdP-Gruppen auf ADOIT Benutzergruppen sind:

1. Nutzung vorhandener IdP-Gruppen: Vorhandene IdP-Gruppen, die organisatorische Einheiten repräsentieren, können entsprechenden ADOIT Benutzergruppen zugeordnet werden. Mehrere IdP-Gruppen können auf eine einzelne ADOIT Benutzergruppe mappen, wie z. B. "Modellierer".

2. Erstellung neuer IdP-Gruppen: Neue Gruppen können am IdP erstellt und Benutzer entsprechend zugeordnet werden. Diese Gruppen werden dann ADOIT Benutzergruppen zugeordnet, wobei eine Eins-zu-Eins-Zuordnung zwischen IdP-Gruppen und ADOIT Benutzergruppen beibehalten wird.

Beispiel: Administratoren, Modellierer und Leser

Betrachten wir ein Szenario mit Administratoren, Modellierern und Lesern, wobei Microsoft Entra ID als IdP verwendet wird:

Auf Basis der bereitgestellten Gruppen kann ein Mapping zwischen den Gruppen auf beiden Seiten erstellt werden. Sobald alle Konfigurationsschritte abgeschlossen sind und die SAML-basierte Authentifizierung in ADOIT betriebsbereit ist, können sich Mitarbeiter in Ihrer Organisation bei ADOIT anmelden. Sie erhalten dann die Berechtigungen für die ADOIT-Benutzergruppen, denen sie angehören.

Fragen Sie Ihren Kundenbetreuer

Es ist ratsam, bei der Gestaltung und Umsetzung Ihres Autorisierungskonzepts mit einem ADOIT-Kundenbetreuer zusammenzuarbeiten. So erhalten Sie wertvolle Einblicke und maßgeschneiderte Unterstützung, die auf die Bedürfnisse Ihrer Organisation zugeschnitten sind.

SSL-Zertifikate für den IdP und SP beschaffen und konfigurieren

Abhängig vom verwendeten IdP und Ihren Sicherheitsanforderungen müssen Sie folgende Zertifikate beschaffen:

• Ein SSL-Zertifikat für den SP für HTTPS-Kommunikation (Cert SP-HTTPS)

• Ein SSL-Zertifikat für den IdP für HTTPS-Kommunikation (Cert IdP-HTTPS)

• Ein SSL-Zertifikat für den SP zum Signieren von SAML-Tokens (Cert SP-sig)

• Ein SSL-Zertifikat für den IdP zum Signieren von SAML-Tokens (Cert IdP-sig)

• (Optional) Ein SSL-Zertifikat für den SP zum Entschlüsseln von SAML-Assertionen (Cert SP-decr)

SSL-Zertifikate für HTTPS-Kommunikation

Die SSL-Zertifikate für HTTPS (sowohl Cert SP-HTTPS als auch Cert IdP-HTTPS) werden für die Browserkommunikation verwendet und sollten von einer Zertifizierungsstelle (CA) signiert sein, der die Browser vertrauen.

• Das Zertifikat Cert SP-HTTPS wird bei der Installation von ADOIT mit SSL benötigt und dient als Zertifikat für Tomcat. Sie müssen dieses Zertifikat von einer Zertifizierungsstelle beziehen.

• Ob Sie ein Zertifikat Cert IdP-HTTPS erhalten und konfigurieren müssen, hängt vom verwendeten IdP ab. Beispielsweise [müssen Sie ein SSL-Zertifikat für HTTPS für AD FS beschaffen und konfigurieren](https://learn.microsoft.com/en-us/ previous-versions/windows/it -pro/windows-server-2012-r2-and-2012/dn781428(v=ws.11)). Für Microsoft Entra ID müssen Sie jedoch kein SSL-Zertifikat für HTTPS separat beantragen und konfigurieren – es ist bereits standardmäßig enthalten.

SSL-Zertifikate zum Signieren von SAML-Tokens

Die SSL-Zertifikate zum Signieren von Tokens (Cert SP-sig und Cert IdP-sig) müssen nicht von einer Zertifizierungsstelle signiert werden, da sie auf beiden Seiten verwendet werden.

• Für das Zertifikat Cert SP-sig können Sie ein selbstsigniertes Zertifikat verwenden. Erstellen Sie einen Java-KeyStore mit dem Java-Keytool und exportieren Sie das Zertifikat daraus. Dieses Zertifikat wird verwendet, wenn Sie die SAML-Einstellungen in ADOIT konfigurieren. Je nach verwendetem IdP müssen Sie dieses Zertifikat auch dort hochladen. Beispielsweise erfordert AD FS das Hochladen des Cert SP-sig-Zertifikats, um Vertrauen zwischen dem IdP und dem SP herzustellen. Dies ist bei Microsoft Entra ID nicht erforderlich. Stattdessen werden zum Herstellen des Vertrauens die vom SP bereitgestellten Metadaten verwendet.

• Das Cert IdP-sig-Zertifikat ist ein vom IdP generiertes selbstsigniertes Zertifikat. Sie können es aus dem IdP exportieren und in ADOIT hochladen oder ADOIT die Metadaten-URL vom IdP zur Verfügung stellen, um Details über das Zertifikat abzurufen.

SSL-Zertifikat zum Entschlüsseln von SAML-Assertionen

Das Zertifikat Cert SP-decr kann wie die Zertifikate zum Signieren von SAML-Tokens behandelt werden, d. h. es muss nicht von einer Zertifizierungsstelle signiert werden. Dieses Zertifikat kann mit dem Zertifikat Cert SP-sig identisch sein.

Ich bin verwirrt - welche Zertifikate muss ich jetzt beschaffen?

Hier ist eine kurze Zusammenfassung, um jegliche Verwirrung bezüglich der SSL-Zertifikate, die Sie benötigen, zu beseitigen:

• Für HTTPS-Kommunikation:

  • Cert SP-HTTPS: Erforderlich für die Installation von ADOIT mit SSL. Beschaffen Sie dieses Zertifikat von einer Zertifizierungsstelle.

  • Cert IdP-HTTPS: Erforderlich je nach IdP. Beschaffen Sie dieses Zertifikat für AD FS. Nicht notwendig für Microsoft Entra ID.

• Zum Signieren von SAML-Tokens:

  • Cert SP-sig: Erforderlich für die Konfiguration der SAML-Einstellungen in ADOIT. Erstellen Sie zu diesem Zweck ein selbstsigniertes Zertifikat mit dem Java Keytool.

  • Cert IdP-sig: Ein selbstsigniertes Zertifikat, vom IdP generiert. Exportieren Sie es aus dem IdP.

• Für das Entschlüsseln von SAML-Assertions (optional):

  • Cert SP-decr: Dieses optionale Zertifikat kann mit dem Cert SP-sig-Zertifikat identisch sein.

Beispiel: Erstellen eines Java-KeyStores und Exportieren des Zertifikats Cert SP.sig

1. Starten Sie eine Windows-Eingabeaufforderung als Administrator und navigieren Sie dann zum Verzeichnis "<Java JDK Installation>/bin".

2. Führen Sie folgenden Befehl aus, um den KeyStore im Ordner \bin zu erstellen:

keytool -genkey -alias <ALIAS> -keyalg RSA -keystore <KEYSTORE_FILE_NAME>.jks -storepass <PASSWORD> -validity <VALIDITY>

• <ALIAS> dient zur Identifizierung des Zertifikats im KeyStore
• <KEYSTORE_FILE_NAME> enthält den Namen der zu erstellenden KeyStore-Datei
• <PASSWORD> enthält das Passwort zum Zugriff auf den KeyStore
• <VALIDITY> ist die Gültigkeitsdauer in Tagen

Beispiel

Beispiel: keytool -genkey -alias BOC -keyalg RSA -keystore BOC.jks -storepass <mein-Passwort> -validity 365

3. Führen Sie den folgenden Befehl aus, um das selbstsignierte Zertifikat in den Ordner \bin zu exportieren:

keytool -export -alias <ALIAS> -storepass <PASSWORD> -file <CERTIFICATE_FILE_NAME>.cer -keystore <KEYSTORE_FILE_NAME>.jks

Beispiel

Beispiel: keytool –export –alias BOC –storepass <mein-Passwort> -file BOC.cer –keystore BOC.jks

Fertig! Sie haben erfolgreich einen Java-KeyStore erstellt und das Zertifikat Cert SP.sig daraus exportiert.

ADOIT mit SSL installieren

Installieren Sie ADOIT gemäß dem Installationshandbuch. Sie müssen SSL/TLS-Unterstützung für Tomcat konfigurieren. Als Zertifikat für Tomcat muss das Zertifikat Cert SP-HTTPS verwendet werden.

ADOIT Benutzergruppen erstellen

Erstellen Sie jetzt in ADOIT die für Ihr Autorisierungskonzept erforderlichen Benutzergruppen, konfigurieren Sie deren Berechtigungen und weisen System-Rollen zu. Wenn Sie dabei Hilfe benötigen, lesen Sie Benutzergruppen in ADOIT einrichten.

SAML IdP konfigurieren

Dieser Abschnitt behandelt mögliche SAML IdPs für ADOIT und enthält ein detailliertes Tutorial speziell für Microsoft Entra ID.

Unterstützte IdPs

ADOIT unterstützt eine Integration mit folgenden IdPs:

• Microsoft Entra ID

• Microsoft Active Directory Federation Services (AD FS)

• Okta

• Shibboleth

• PingFederate

• Jeder andere SAML 2.0 kompatible IdP (vorherige Evaluierung erforderlich)

Detaillierte Anweisungen zur Konfiguration von Microsoft Entra ID finden Sie im folgenden Abschnitt. Wenn Sie eine Anleitung für die Konfiguration von AD FS benötigen, wenden Sie sich bitte an Ihren ADOIT-Kundenbetreuer. Hilfe bei der Konfiguration eines anderen IdPs finden Sie in der Dokumentation des jeweiligen IdPs.

Microsoft Entra ID konfigurieren

Dieser Abschnitt enthält eine detaillierte Anleitung zur Konfiguration von Microsoft Entra ID als IdP für ADOIT. Führen Sie folgende Schritte aus, um ADOIT mit Microsoft Entra ID zu integrieren, egal ob es sich um eine SaaS-Lösung handelt oder ob es in Ihrer eigenen Infrastruktur (on premise) betrieben wird.

Anmeldung im Microsoft Entra Admin Center

Um loszulegen, melden Sie sich mit Ihrem Administratorkonto beim Microsoft Entra Admin Center an.

Microsoft Entra Gruppen erstellen und Benutzer zuweisen

Wenn Ihr Autorisierungskonzept dies vorsieht und Sie es noch nicht getan haben, erstellen Sie jetzt Microsoft Entra-Gruppen und weisen Sie ihnen Benutzer zu. Weitere Informationen finden Sie in der Microsoft Entra Dokumentation.

Anwendung erstellen

Um ADOIT mit Microsoft Entra ID zu integrieren, müssen Sie eine Anwendung im Microsoft Entra Admin Center erstellen:

1. Wechseln Sie zu Identität > Anwendungen > Unternehmensanwendungen, und wählen Sie dann Neue Anwendung aus.

2. Wählen Sie Eigene Anwendung erstellen aus.

3. Geben Sie im Feld Namen eingeben den Namen Ihrer Anwendung ein (zum Beispiel ADOIT).

4. Wählen Sie Beliebige andere, nicht im Katalog gefundene Anwendung integrieren aus.

5. Klicken Sie auf Erstellen.

SAML-SSO einrichten

Nachdem Sie die Anwendung im Microsoft Entra Admin Center erstellt haben, müssen Sie SSO mit SAML konfigurieren:

1. Wechseln Sie auf der Seite Übersicht der Anwendung zu Einmaliges Anmelden > SAML.

2. Klicken Sie unter Grundlegende SAML-Konfiguration auf Bearbeiten und führen Sie folgende Schritte aus:

   • Geben Sie für Bezeichner (Entitäts-ID) eine eindeutige ID ("Bezeichner") ein, die ADOIT für Microsoft Entra ID identifiziert (z. B. ADOIT_Identifier). Bewahren Sie diese ID für die spätere Verwendung auf der ADOIT-Seite auf.

   • Geben Sie für Antwort-URL (Assertionsverbraucherdienst-URL) die Antwort-URL ein, unter der die ADOIT-Webapplikation den Empfang des Authentifizierungstokens erwartet.

     • Geben Sie die HTTPS-URL ein, unter der ADOIT verfügbar ist, und fügen Sie /auth.view hinzu, z.B: https://pp2****.de.boc-cloud.com/auth.view.

3. Klicken Sie unter Attribute & Ansprüche auf Bearbeiten und konfigurieren Sie folgende Claims ("Ansprüche"), die standardmäßig bereitgestellt sind. Ändern Sie die Quellattribute, wenn die definierten Attribute nicht mit den in Ihrer Organisation verwendeten übereinstimmen:

   • surname (user.surname): Dieser Claim übergibt den Nachnamen des Benutzers an ADOIT.

   • emailaddress (user.mail): Dieser Claim übergibt die E-Mail-Adresse des Benutzers an ADOIT.

   • name (user.userprincipalname): Dieser Claim übergibt die eindeutige Kennung des Benutzers an ADOIT.

   • givenname (user.givenname): Dieser Claim übergibt den Vornamen des Benutzers an ADOIT.

4. Immer noch auf der Seite Attribute & Ansprüche, müssen Sie als Nächstes einen benutzerdefinierten Claim hinzufügen:

   • user.groups: Fügen Sie einen Gruppenclaim hinzu, der die Informationen zur Gruppenmitgliedschaft des Benutzers an ADOIT übergibt. Wählen Sie aus, welche Gruppen im Claim zurückgegeben werden sollen, zum Beispiel Sicherheitsgruppen, um alle Sicherheitsgruppen zu erhalten. Verwenden Sie sAMAccountName als Quellattribut, wenn Ihre Umgebung mit einem lokalen Active Directory synchronisiert ist. Wenn dies nicht der Fall ist, wählen Sie Der Anwendung zugewiesene Gruppen für im Claim zurückzugebende Gruppen aus, und verwenden Sie Anzeigenamen für reine Cloudgruppen als Quellattribut.

5. Führen Sie unter SAML-Zertifikate folgende Schritte aus:

   • Kopieren Sie die App-Verbundmetadaten-URL in die Zwischenablage, die alle notwendigen Details enthält, damit ADOIT die von Microsoft Entra ID ausgestellten Tokens verarbeiten kann.

   • Laden Sie das Zertifikat (Base64) herunter, das SSL-Zertifikat für den IdP zum Signieren von SAML-Tokens (Cert IdP-sig).

   • Laden Sie die Verbundmetadaten-XML herunter. Diese Datei enthält alle Informationen, die ADOIT benötigt, um die von Microsoft Entra ID ausgestellten Tokens zu verwenden. Bewahren Sie diese Daten für die spätere Verwendung auf der ADOIT-Seite auf.

6. Führen Sie unter <mein-App-Name> einrichten folgende Schritte aus:

   • Kopieren Sie die URL für Anmeldung in die Zwischenablage. Bewahren Sie diese URL für die spätere Verwendung auf der ADOIT-Seite auf.

Mit diesen Schritten haben Sie Microsoft Entra ID erfolgreich für SSO mit SAML mit ADOIT konfiguriert.

Hinweis

Die URL für Anmeldung und das Zertifikat (Base64) könnten auch aus der Verbundmetadaten-XML extrahiert werden. Praktischer ist es jedoch, sie jetzt direkt herunterzuladen, damit Sie sie später beim Konfigurieren der SAML-Einstellungen auf der ADOIT-Seite verwenden können.

Erforderliche Benutzerzuweisung deaktivieren

In Microsoft Entra ID haben Anwendungen eine Eigenschaft namens Zuweisung erforderlich?, die den Zugriff auf die Anwendung steuert. Standardmäßig ist diese Eigenschaft auf Ja gesetzt, was bedeutet, dass Benutzer erst dieser Anwendung zugewiesen werden müssen, bevor sie sich anmelden können.

Wir empfehlen, diese Option auf Nein zu setzen, damit sich alle Benutzer authentifizieren können, ohne dass explizite Zuweisungen erforderlich sind.

So deaktivieren Sie die erforderliche Benutzerzuweisung im Microsoft Entra Admin Center:

1. Klicken Sie auf der Seite Übersicht der Anwendung unter Verwalten auf Eigenschaften.

2. Deaktivieren Sie Zuweisung erforderlich?, damit keine Benutzerzuweisung erforderlich ist.

3. Klicken Sie auf Speichern.

Solange diese Einstellung deaktiviert ist, kann sich jeder Benutzer innerhalb Ihres Verzeichnisses bei der Anwendung anmelden, was den Prozess der Zugriffsverwaltung vereinfacht.

Optional: Tokenverschlüsselung konfigurieren

Optional können Sie SAML-Assertionen zwischen Microsoft Entra ID und ADOIT für mehr Sicherheit verschlüsseln. Bei diesem Prozess wird ein öffentlicher Schlüssel verwendet, der von einem in Microsoft Entra ID gespeicherten Zertifikat abgerufen wird, um die SAML-Assertionen zu verschlüsseln, die dann von ADOIT mit dem passenden privaten Schlüssel entschlüsselt werden.

Hinweis

Auch ohne Tokenverschlüsselung gewährleistet Microsoft Entra eine sichere Übertragung von SAML-Tokens, indem es HTTPS/TLS-Verbindungen für den gesamten Token-Austausch vorschreibt. Wägen Sie die Vorteile von mehr Sicherheit durch Token-Verschlüsselung gegen den administrativen Aufwand für die Verwaltung weiterer Zertifikate ab. Entscheiden Sie dann, welcher Ansatz für die Sicherheitsanforderungen Ihrer Organisation am besten geeignet ist.

So aktivieren Sie Tokenverschlüsselung im Microsoft Entra Admin Center:

1. Wählen Sie auf der Seite Übersicht der Anwendung Tokenverschlüsselung aus.

2. Importieren Sie das Zertifikat für den SP zum Entschlüsseln von SAML-Assertionen (Cert SP-decr). Sie können ein selbstsigniertes Zertifikat verwenden oder das Zertifikat Cert SP-sig wiederverwenden.

3. Aktivieren Sie die Tokenverschlüsselung.

ADOIT konfigurieren

Jetzt, wo Sie den von Ihnen gewählten Identity Provider (IdP) konfiguriert haben, ist es an der Zeit, die Einstellungen für SAML-SSO in ADOIT festzulegen. Wenn Sie SAML-Integrationssupport gebucht haben, übernimmt der technische Support von BOC diesen Teil. On-premise-Kunden lesen bitte weiter und lassen Sie sich Schritt für Schritt durch den gesamten Prozess führen.

ADOIT Administration öffnen

Um loszulegen, öffnen Sie mit Ihrem Administratorkonto die ADOIT Administration:

• Geben Sie die HTTPS-URL ein, unter der ADOIT verfügbar ist. Klicken Sie auf Administration, geben Sie Ihre Anmeldeinformationen ein und loggen Sie sich ein.

• Wenn Sie bereits in ADOIT eingeloggt sind und zur ADOIT Administration wechseln möchten, klicken Sie auf das Benutzersymbol in der rechten oberen Ecke und dann auf Administration.

Vertrauensbeziehung mit IdP etablieren

Der IdP verwendet ein Zertifikat zum Signieren von SAML-Tokens (Cert IdP-sig) und nutzt zu diesem Zweck den privaten Schlüssel. ADOIT benötigt dieses Zertifikat ebenfalls, um damit signierte SAML-Token unter Verwendung des öffentlichen Schlüssels zu validieren. Es gibt zwei grundsätzliche Methoden, um dieses Zertifikat ADOIT bekannt zu machen:

• Metadaten-URL referenzieren (bevorzugt): Beziehen Sie die Metadaten-URL von Ihrem IdP und referenzieren Sie sie in ADOIT.
• Zertifikat hochladen: Laden Sie das Cert IdP-sig Zertifikat direkt in ADOIT hoch.

Metadaten-URL referenzieren (bevorzugt)

Die bevorzugte Methode, um ADOIT das Zertifikat bekannt zu machen. Sie erhalten die Metadaten-URL von Ihrem IdP und referenzieren diese in ADOIT. Diese URL verweist auf ein Metadaten-Dokument, das alle notwendigen Konfigurationsdetails für SAML-basiertes Single Sign-On enthält, einschließlich des für die Token-Signierung verwendeten Zertifikats. Die Metadaten-URL muss von ADOIT aus erreichbar sein.

So referenzieren Sie die Metadaten-URL von Ihrem IdP in ADOIT:

1. Wechseln Sie in der ADOIT Administration zu Authentifizierung > Konnektoren.

2. Bewegen Sie den Mauszeiger auf den SAML 1 Konnektor, klicken Sie auf Mehr, und dann auf IdP konfigurieren.

3. Wählen Sie in der Liste Konfigurationsquelle die Option URL aus.

4. Geben Sie für Metadaten URL die Metadaten-URL Ihres IdPs ein. Für Microsoft Entra ID geben Sie zum Beispiel die App-Verbundmetadaten-URL ein, die Sie kopiert haben. Schließen Sie den Bereich und speichern Sie anschließend Ihre Änderungen.

Eine Erfolgsmeldung wird angezeigt. Schließen Sie die Meldung, um den Vorgang abzuschließen.

Zertifikat hochladen

Alternativ können Sie das Zertifikat Cert IdP-sig auch direkt in ADOIT hochladen. Bei dieser Methode müssen Sie das Zertifikat allerdings jedes Mal neu hochladen, wenn Ihr IdP zu einem neuen wechselt.

So laden Sie das Zertifikat Cert IdP-sig hoch:

1. Wechseln Sie in der ADOIT Administration zu Authentifizierung > Konnektoren.

2. Bewegen Sie den Mauszeiger auf den SAML 1 Konnektor, klicken Sie auf Mehr, und dann auf Bearbeiten.

3. Klicken Sie auf der Seite Eigenschaften der Konnektorkonfiguration unter IDP public key file auf Durchsuchen, um das Token-Signaturzertifikat vom IdP hochzuladen. Wenn Sie zum Fortfahren aufgefordert werden, klicken Sie auf Ja.

Eine Erfolgsmeldung wird angezeigt. Schließen Sie das Fenster und speichern Sie anschließend Ihre Änderungen.

Globale SAML-Einstellungen konfigurieren

Als Nächstes müssen Sie die globalen Einstellungen für SAML-Authentifizierung ändern.

1. Wechseln Sie in der ADOIT Administration zu Authentifizierung > SAML.

2. Geben Sie im Feld Konfigurations-ID eine eindeutige ID ein, mit der sich ADOIT gegenüber dem IdP identifiziert.

   • Der Wert muss mit der ID übereinstimmen, die auf IdP-Seite konfiguriert ist, um ADOIT zu identifizieren. Für Microsoft Entra ID muss er beispielsweise mit dem Bezeichner (Entitäts-ID) übereinstimmen.

3. Geben Sie im Feld Assertion Consumer-URL die Antwort-URL ein, unter der ADOIT den Empfang des Authentifizierungstokens erwartet.

   • Geben Sie die HTTPS-URL ein, unter der ADOIT verfügbar ist, und fügen Sie /auth.view hinzu, z.B: https://pp2****.de.boc-cloud.com/auth.view.

   • Der Wert muss mit der Antwort-URL übereinstimmen, die auf IdP-Seite konfiguriert ist. Für Microsoft Entra ID muss er beispielsweise der Antwort-URL (Assertionsverbraucherdienst-URL) entsprechen.

4. Konfigurieren Sie unter Token-Signierung die Einstellungen für das Signieren von SAML-Tokens in ADOIT:

   • Keystore-Alias: Geben Sie das im KeyStore hinterlegte Alias für das Zertifikat Cert SP-sig ein (z.B. BOC).

   • Keystore-Datei: Klicken Sie auf Durchsuchen, um die KeyStore-Datei hochzuladen, die das Zertifikat Cert SP-sig enthält (z.B. BOC.jks).

   • Keystore-Passwort: Geben Sie das Passwort für den Zugriff auf den KeyStore ein. Das Passwort wird verschlüsselt gespeichert.

5. Optional: Wurde Ihr IdP für die Verschlüsselung von SAML-Assertionen konfiguriert? Dann bearbeiten Sie die Einstellungen zur Entschlüsselung unter Assertion-Entschlüsselung:

   • Aktiviert: Aktivieren Sie diese Option, damit ADOIT eingehende verschlüsselte Assertionen vom IdP entschlüsseln kann.

   • Keystore-Alias: Geben Sie das im KeyStore hinterlegte Alias für das Zertifikat Cert SP-decr ein.

   • Keystore-Datei: Klicken Sie auf Durchsuchen, um die KeyStore-Datei hochzuladen, die das Zertifikat Cert SP-decr enthält.

   • Keystore-Passwort: Geben Sie das Passwort für den Zugriff auf den KeyStore ein. Das Passwort wird verschlüsselt gespeichert.

Beispiel

Beispielkonfiguration, Entschlüsseln von Tokens ist deaktiviert:

SAML-Einstellungen
- Konfigurations-ID: ADOIT_Identifier
- Assertion Consumer-URL: https://pp2****.de.boc-cloud.com/auth.view
- Token-Signierung:
  - Keystore-Alias: BOC
  - Keystore-Datei: BOC.jks
  - Keystore-Passwort: ******** (verschlüsselt)
- Assertion decryption:
  - Enabled: (deaktiviert)
  - Keystore-Alias: (nicht konfiguriert)
  - Keystore-Datei: (nicht konfiguriert)
  - Keystore-Passwort: (nicht konfiguriert)

Konnektor-Spezifische SAML-Einstellungen adaptieren

Um SAML-basierte Authentifizierung mit Ihrem gewählten IdP zu aktivieren, müssen verschiedene Einstellungen konfiguriert werden. Dazu gehören die IdP-Eigenschaften, Claims und ein User Mapping. Diese Einstellungen werden über die Eigenschaften des SAML-Konnektors innerhalb von ADOIT aufgerufen und verwaltet.

So greifen Sie auf diese Einstellungen zu und ändern sie:

1. Wechseln Sie in der ADOIT Administration zu Authentifizierung > Konnektoren.

2. Bewegen Sie den Mauszeiger auf den SAML 1 Konnektor, klicken Sie auf Mehr, und dann auf Bearbeiten.

In den folgenden Abschnitten werden die Konfigurationsparameter beschrieben, die angepasst werden müssen.

IdP-Eigenschaften konfigurieren

Zuerst müssen Sie konfigurieren, wie ADOIT mit dem IdP bei der Authentifizierung interagiert:

• Passen Sie auf der Seite Eigenschaften des SAML-Konnektors die IDP-Eigenschaften an.

Hinweis

Je nachdem, wie Sie die Vertrauensbeziehung mit dem IdP etabliert haben, können einige IdP-Eigenschaften bereits automatisch ausgefüllt sein:

• Referenz-Metadaten-URL (bevorzugt): Füllt die Eigenschaften Binding-Typ, IdP-Adresse und IDP public key file automatisch aus.
• Zertifikat hochladen: Füllt nur die Eigenschaft IDP public key file automatisch aus.

Führen Sie folgende Schritte zur Konfiguration der erforderlichen Einstellungen durch:

1. Geben Sie im Feld IdP-Name einen Namen für den IdP ein. Sie können jeden beliebigen Namen verwenden, z. B. ME-ID. Dieser Name wird in ADOIT angezeigt und in Protokollen verwendet.

2. Wählen Sie in der Liste Binding-Typ den Bindungstyp für die Kommunikation mit dem IdP aus. Standardmäßig ist post eingestellt, was bedeutet, dass die Kommunikation technisch über das POST-Verfahren eines HTML-Formulars erfolgt. Wenn redirect festgelegt wird, kontaktiert der Client den IdP über einen Redirect-Aufruf, was möglicherweise aufgrund bestimmter Richtlinien nicht zulässig ist.

3. Geben Sie im Feld IdP-Adresse die URL des IdP an, an die Authentifizierungsanfragen gesendet werden. Für Microsoft Entra ID geben Sie zum Beispiel die **URL für Anmeldung** ein, die Sie kopiert haben.

4. Aktivieren Sie IDP-Sitzungsende bei Dienstanbieter-Sitzungsende, wenn das Abmelden von ADOIT auch eine Abmeldung beim IdP auslösen soll. Standardmäßig ist diese Option deaktiviert.

5. Stellen Sie sicher, dass das Feld IDP public key file das Zertifikat Cert IdP-sig enthält.

Beispiel

Beispielkonfiguration:

IDP-Eigenschaften
- IDP-Name: ME-ID
- Binding-Typ: post
- IDP-Adresse: https://login.microsoftonline.com/****/saml2
- Assertion-Entschlüsselung: Nicht gesetzt
- Metadaten-URL: https://login.microsoftonline.com/****federationmetadata.xml?appid=****
- IDP-Sitzungsende bei Service-Provider-Sitzungsende: (deaktiviert)
- IDP public key file: <Cert IdP-sig>.cer

Claims definieren

Als Nächstes müssen Sie die Claims erfassen, die ADOIT vom IdP erwarten soll. Claims dienen dazu, Informationen über den Benutzer zu transportieren, wie etwa die E-Mail-Adresse, den Vornamen und den Nachnamen. Später werden Sie ein User Mapping erstellen, das definiert, wie diese Claims für die Zuweisung von Benutzerattributen, System-Rollen, Benutzergruppen und mehr in ADOIT verarbeitet werden:

• Fügen Sie auf der Seite Eigenschaften des SAML-Konnektors unter Claims folgende Claims hinzu:

Name	Wert [Beispiel - verwenden Sie den vom IdP bereitgestellten Wert]	Attribut	Beschreibung
claim_lastname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	AttributeStatement	Dieser Claim steht für den Nachnamen des Benutzers. Als Wert können Sie in der Regel http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname verwenden. Diese URI entspricht dem surname-Claim von verschiedenen IdPs, einschließlich Microsoft Entra ID und AD FS. Bei Bedarf können Sie den Wert ändern, um ihn einem anderen Claim-Typ zuzuordnen.
claim_email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	AttributeStatement	Dieser Claim steht für die E-Mail-Adresse des Benutzers. Als Wert können Sie in der Regel http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress verwenden. Diese URI entspricht dem emailaddress-Claim von verschiedenen IdPs, einschließlich Microsoft Entra ID und AD FS. Bei Bedarf können Sie den Wert ändern, um ihn einem anderen Claim-Typ zuzuordnen.
claim_login	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	AttributeStatement	Dieser Claim steht für die eindeutige Kennung des Benutzers, die in ADOIT als Anmeldename dient. Als Wert können Sie in der Regel http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name verwenden. Diese URI entspricht dem name-Claim von verschiedenen IdPs, einschließlich Microsoft Entra ID und AD FS. Bei Bedarf können Sie den Wert ändern, um ihn einem anderen Claim-Typ zuzuordnen, z. B. http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname, was dem Claim für den Windows-Kontonamen entspricht.
claim_firstname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	AttributeStatement	Dieser Claim steht für den Vornamen des Benutzers. Als Wert können Sie in der Regel http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname verwenden. Diese URI entspricht dem givenname-Claim von verschiedenen IdPs, einschließlich Microsoft Entra ID und AD FS. Bei Bedarf können Sie den Wert ändern, um ihn einem anderen Claim-Typ zuzuordnen.
claim_group	http://schemas.microsoft.com/ws/2008/06/identity/claims/groups	AttributeStatement	Dieser Claim steht für die Gruppenzugehörigkeit des Benutzers. Wenn Sie Microsoft Entra ID und AD FS verwenden, sollte der Wert http://schemas.microsoft.com/ws/2008/06/identity/claims/groups sein. Andere IdPs verwenden normalerweise http://schemas.xmlsoap.org/claims/Group.

User Mapping konfigurieren

Als Nächstes müssen Sie konfigurieren, wie ADOIT mit Benutzern umgeht, die sich anmelden. Sie können beispielsweise festlegen, ob ein Benutzer erstellt werden soll, falls er noch nicht existiert, oder welche Claims zum Zuweisen von System-Rollen, Benutzergruppen usw. verarbeitet werden.

Führen Sie folgende Schritte auf der Seite User Mapping des SAML-Konnektors aus:

Eigenschaften

In diesem Bereich können Sie zuvor erfasste Claims den Benutzerattributen in ADOIT zuordnen. Ein Mapping ist dabei zwingend erforderlich:

• Der Claim claim_login dient in ADOIT als Anmeldename und muss dem Attribut Name zugeordnet werden.

Andere Mappings sind optional. Die folgende Tabelle zeigt eine mögliche Konfiguration:

Name	Attribute
claim_login	Name
claim_firstname	First name
claim_lastname	Last name
claim_email	Email

Diese Konfiguration stellt sicher, dass wichtige Benutzerdetails wie Name und E-Mail während des Authentifizierungsprozesses korrekt zugeordnet werden.

Rollen

In diesem Bereich können Sie konfigurieren, wie Benutzern während des Authentifizierungsprozesses System-Rollen zugewiesen werden.

Info

Lassen Sie die Einstellungen für Rollen leer, wenn Sie dem hier im Guide vorgeschlagenen Autorisierungskonzept folgen. In diesem Fall werden System-Rollen in der ADOIT Administration direkt an Benutzergruppen zugewiesen, anstatt an einzelne Benutzer über die Einstellungen in diesem Abschnitt.

Sie können sowohl Standardrollen festlegen als auch bedingte Rollenzuweisungen definieren.

• Standardrollen: Definieren Sie die standardmäßigen System-Rollen für Benutzer, wenn keine anderen Rollenzuweisungen zutreffen.

• Rollen: Konfigurieren Sie benutzerdefinierte Rollenzuweisungen mit:

  • Eigenschaft: Wählen Sie den Claim (z.B. claim_group) für die Zuweisung der System-Rolle aus.

  • Typ: Wählen Sie eine Methode zum Abgleichen von Werten aus (siehe "Mögliche Methoden zum Abgleichen von Werten" im Abschnitt Gruppen unten für mehr Details).

  • Match: Definieren Sie den Wert, der übereinstimmen soll (z.B. ein bestimmter Gruppenname oder eine ID).

  • Zielname: Wählen Sie die Systemrolle in ADOIT aus, die zugewiesen werden soll, wenn die Bedingungen erfüllt sind.

Gruppen

In diesem Bereich können Sie konfigurieren, wie Benutzern während des Authentifizierungsprozesses Benutzergruppen zugewiesen werden. Gruppenzuweisungen basieren häufig auf dem Claim claim_group, der die Gruppenzugehörigkeit des Benutzers repräsentiert. Es gibt zwei Methoden zur Zuweisung von Benutzergruppen: die Definition von Standardgruppen und die Erstellung von Gruppenzuweisungen auf der Grundlage bestimmter Claim-Werte.

• Standardgruppen: Definieren Sie die standardmäßigen Benutzergruppen für Benutzer, wenn keine anderen Gruppenzuweisungen zutreffen.

• Gruppen: Konfigurieren Sie benutzerdefinierte Gruppenzuweisungen mit:

  • Eigenschaft: Wählen Sie den Claim (z.B. claim_group) für die Zuweisung der Benutzergruppe aus.

  • Typ: Wählen Sie eine Methode zum Abgleichen von Werten aus (siehe "Mögliche Methoden zum Abgleichen von Werten" unten für mehr Details).

  • Match: Definieren Sie den Wert, der übereinstimmen soll (z.B. ein bestimmter Gruppenname oder eine ID).

  • Zielname: Wählen Sie die Benutzergruppe in ADOIT aus, die zugewiesen werden soll, wenn die Bedingungen erfüllt sind.

Mögliche Methoden zum Abgleichen von Werten

Hier sind die möglichen Methoden zum Abgleichen von Werten (Eigenschaft Typ), wenn Sie ein User Mapping für einen SAML-Konnektor definiern:

• equals: Die Werte müssen exakt übereinstimmen.

• equalsIgnoreCase: Die Werte müssen exakt übereinstimmen, aber Groß- und Kleinschreibung wird ignoriert.

• contains: Der Zielwert muss die angegebene Übereinstimmung als Teilzeichenfolge enthalten.

• containsWord: Der Zielwert muss das genaue Wort (als Ganzes) enthalten, das Sie abgleichen.

• containsWordIgnoreCase: Dasselbe wie containsWord, aber Groß- und Kleinschreibung wird ignoriert.

• regExp: Der Abgleich wird mithilfe eines regulären Ausdrucks durchgeführt (ein musterbasiertes Abgleichsystem, siehe Regex-Mappings erstellen).

Beispiel

Beispielkonfiguration:

• Mitglieder der IdP-Gruppe ADO_Modellierer werden in ADOIT der Benutzergruppe Modellierer zugewiesen.
• Mitglieder der IdP-Gruppe ADO_Administratoren werden in ADOIT der Benutzergruppe Administratoren zugewiesen.
• Alle anderen Benutzer werden automatisch der Benutzergruppe Leser zugewiesen.

Gruppen
- Standardgruppen
  - Name: Leser
- Gruppen
  - Benutzergruppe: Modellierer
    - Eigenschaft: claim_group 
    - Typ: equals
    - Match: ADO_Modellierer
  - Benutzergruppe: Administratoren
    - Eigenschaft: claim_group 
    - Typ: equals
    - Match: ADO_Administratoren

Repository

In diesem Bereich können Sie Benutzern auf Basis von Claims bestimmte Repositorys als Arbeitsplatz zuweisen. Die Benutzer werden gleichzeitig als Objekte in der Modellierung verfügbar gemacht.

• Basis-Zuweisungen: Legen Sie die Basis-Repositorys fest, die jedem Benutzer automatisch zugewiesen werden sollen. Zusätzlich können Sie bedingte Repository-Zuweisungen konfigurieren, aber diese Repositorys dienen als Basis für alle Benutzer. Wählen Sie "Alle Repositorys" oder ein bestimmtes Repository aus. Bei Auswahl eines bestimmten Repositorys können Sie außerdem eine Objektgruppe festlegen, in der sich die zugewiesenen Benutzerobjekte befinden sollen.

• Bedingte Zuweisungen: Konfigurieren Sie benutzerdefinierte Repositoryzuweisungen mit:

  • Eigenschaft: Wählen Sie den Claim für die Zuweisung des Repositorys aus.

  • Typ: Wählen Sie eine Methode zum Abgleichen von Werten aus siehe "Mögliche Methoden zum Abgleichen von Werten" im Abschnitt Gruppen oben für mehr Details).

  • Match: Definieren Sie den Wert, der übereinstimmen soll (z.B. ein bestimmter Gruppenname oder eine ID).

  • Zielname: Wählen Sie das Repository in ADOIT aus, das zugewiesen werden soll, wenn die Bedingungen erfüllt sind. Sie können entweder "Alle Repositorys" oder ein bestimmtes Repository als Ziel angeben. Bei Auswahl eines bestimmten Repositorys können Sie außerdem eine Objektgruppe festlegen, in der sich die zugewiesenen Benutzerobjekte befinden sollen.

Beispiel

Beispielkonfiguration:

• Allen Benutzern wird in ADOIT das Repository Standard-Repository zugewiesen.

• Mitgliedern der IdP-Gruppe ADO_Modellierer wird zusätzlich das Repository Test-Repository zugewiesen. Die Benutzerobjekte werden in der Objektgruppe Mitarbeiter erstellt.

Repositorys
- Basis-Zuweisungen
  - Repository: Standard-Repository
- Bedingte Zuweisungen
  - Repository: Test-Repository
    - Eigenschaft: claim_group 
    - Typ: equals
    - Match: ADO_Modellierer
    - Objektgruppe (optional): Mitarbeiter

Named Use

In diesem Bereich können Sie Benutzern auf Basis von Claims benannten Zugriff auf bestimmte Szenarien in ADOIT zuweisen.

• Standard-Szenarien: Definieren Sie die standardmäßigen Szenarien für Benutzer, wenn keine anderen Szenariozuweisungen zutreffen.

• Szenarien: Konfigurieren Sie benutzerdefinierte Szenariozuweisungen mit:

  • Eigenschaft: Wählen Sie den Claim für die Zuweisung des Szenarios aus.

  • Typ: Wählen Sie eine Methode zum Abgleichen von Werten aus siehe "Mögliche Methoden zum Abgleichen von Werten" im Abschnitt Gruppen oben für mehr Details).

  • Match: Definieren Sie den Wert, der übereinstimmen soll (z.B. ein bestimmter Gruppenname oder eine ID).

  • Zielname: Wählen Sie das Szenario in ADOIT aus, das zugewiesen werden soll, wenn die Bedingungen erfüllt sind.

Beispiel

Beispielkonfiguration:

• Mitgliedern der IdP-Gruppen ADO_Modellierer und ADO_Administratoren wird in ADOIT benannter Zugriff auf das Szenario Gestalten & Dokumentieren zugewiesen.
• Allen anderen Benutzern wird benannter Zugriff auf das Szenario Lesen & Entdecken zugewiesen.

Named Use
- Standard-Szenarien
  - Name: Lesen & Entdecken
- Szenarien
  - Szenario: Gestalten & Dokumentieren
    - Eigenschaft: claim_group 
    - Typ: equals
    - Match: ADO_Modellierer
  - Szenario: Gestalten & Dokumentieren
    - Eigenschaft: claim_group 
    - Typ: equals
     - Match: ADO_Administratoren

Mapped User Verwaltung

Dieser Bereich kann verwendet werden, um Benutzer auf einen Alias-Benutzer zu mappen (= als solche zu behandeln). Dieser Alias-Benutzer repräsentiert die authentifizierten Benutzer, wenn sie sich an ADOIT anmelden. Beispielsweise können Sie so eine bestimmte Gruppe von Anwendern auf einen Benutzer mappen, der Zugriff auf das Organisationsportal hat.

Info

Lassen Sie die Einstellungen für Mapped User Verwaltung leer, außer Ihr Autorisierungskonzept sieht die Verwendung von Alias-Benutzern explizit vor.

• Standardmäßig zugeordnete Benutzer: Definieren Sie einen standardmäßigen Alias-Benutzer für Benutzer, wenn keine andere Zuweisung zutrifft.

• Szenarien: Konfigurieren Sie benutzerdefinierte Alias-Benutzer-Zuweisungen mit:

  • Eigenschaft: Wählen Sie den Claim für die Zuweisung des Alias-Benutzers aus.

  • Typ: Wählen Sie eine Methode zum Abgleichen von Werten aus siehe "Mögliche Methoden zum Abgleichen von Werten" im Abschnitt Gruppen oben für mehr Details).

  • Match: Definieren Sie den Wert, der übereinstimmen soll (z.B. ein bestimmter Gruppenname oder eine ID).

  • Vorhandene Benutzer zuordnen: Optional können Sie angeben, wie vorhandene Benutzer behandelt werden sollen. Wenn diese Option aktiviert ist, wird der authentifizierte Benutzer immer durch den Alias-Benutzer repräsentiert, wenn das Mapping zutrifft. Wenn deaktiviert, gilt das Mapping nur für neue Benutzer, die noch nicht in der ADOIT-Datenbank vorhanden sind und nicht automatisch erstellt werden können.

  • Zielname: Wählen Sie den Alias-Benutzer in ADOIT aus, der zugewiesen werden soll, wenn die Bedingungen erfüllt sind.

Benutzer synchronisieren

Sie haben bereits konfiguriert, wie Claims für die Zuweisung von System-Rollen, Benutzergruppen und mehr verarbeitet werden. Der nächste Schritt besteht darin, die automatische Benutzererstellung zu aktivieren und die Synchronisation der Benutzerdaten einzuschalten.

• Benutzer automatisch erstellen: Aktivieren Sie diese Option, um neue Benutzer automatisch in der ADOIT-Datenbank zu erstellen, wenn sie sich das erste Mal anmelden. Dies gewährleistet eine nahtlose Benutzererstellung "on-the-fly" ohne manuelle Eingriffe.

• Automatische Synchronisieren: Aktivieren Sie diese Option, damit die Benutzerdaten bei jeder Anmeldung mit den Informationen des IdP synchronisiert werden. Dadurch wird sichergestellt, dass die Benutzerdaten stets auf dem neuesten Stand sind. Beachten Sie, dass manuelle Änderungen durch den ADOIT-Administrator bei der Synchronisation überschrieben werden. Mit folgenden Unteroptionen legen Sie fest, welche Daten synchronisiert werden:

  • Attribute synchronisieren (= Eigenschaften): Aktualisiert Benutzerattribute wie Name, E-Mail usw.

  • Rollen synchronisieren: Stellt sicher, dass die System-Rollen in ADOIT mit den Daten des IdP abgeglichen werden.

  • Gruppen synchronisieren: Synchronisiert die Benutzergruppen-Mitgliedschaften mit den Informationen des IdP.

  • Repositorys synchronisieren: Aktualisiert den Zugriff auf Repositorys basierend auf den IdP-Daten.

  • Named Use synchronisieren: Synchronisiert die Nutzungsberechtigungen für spezifische Szenarien.

Konnektor aktivieren

Um die Konfiguration der konnektor-spezifische SAML-Einstellungen abzuschließen, müssen Sie den SAML-Konnektor aktivieren:

1. Wechseln Sie in der ADOIT Administration zu Authentifizierung > Konnektoren.

2. Suchen Sie nach dem SAML 1 Konnektor und aktivieren Sie das Kontrollkästchen Konnektor aktiviert.

3. Verwenden Sie den Ziehpunkt (), um den SAML 1 Konnektor an den Anfang der Liste zu verschieben und ihn als primären Authentifizierungsmechanismus zu priorisieren.

4. Speichern Sie die Änderungen in der ADOIT Administration.

SAML-basierte Authentifizierung ist nun aktiviert und wird als Standard-Authentifizierungsmechanismus verwendet. Der Standard-Konnektor ("Standard Login", die Standard-Anmeldeseite) bleibt als Fallback für Benutzer aktiv, die sich nicht über den IdP authentifizieren können. Deaktivieren Sie den Standard-Konnektor nicht.

System-Einstellungen bearbeiten

Der letzte Konfigurationsschritt besteht darin, einige technische Einstellungen definieren, die die grundlegende Funktionsweise von ADOIT betreffen:

1. Wechseln Sie in der ADOIT Administration zu Einstellungen > Systemeinstellungen > System.

2. Tragen Sie im Feld Basis-URL die URL ein, unter der ADONIS von anderen Rechnern aus erreicht werden kann.

   • Geben Sie die HTTPS-URL ein, unter der ADOIT verfügbar ist, und fügen Sie /auth.view hinzu, z.B: https://pp2****.de.boc-cloud.com/auth.view.

   • Stellen Sie sicher, dass der eingegebene Wert mit der in den globalen SAML-Einstellungen konfigurierten **Assertion Consumer-URL** übereinstimmt, ohne das Suffix /auth.view.

3. Klicken Sie auf Speichern.

Authentifizierung von Benutzern starten

Starten Sie jetzt den ADOIT Applikations-Server neu, damit alle vorgenommenen Konfigurationen wirksam werden. Sobald der Server betriebsbereit ist, können sich die Benutzer über den konfigurierten IdP authentifizieren. Neue Benutzer werden automatisch in der ADOIT-Datenbank erstellt, wenn sie sich das erste Mal anmelden. System-Rollen, Benutzergruppen und andere Attribute werden bei der Anmeldung mit dem IdP synchronisiert, damit die Zugriffsrechte aktuell bleiben.

(Optional) Fehlersuche

Fehler werden in den Dateien <Tomcat-Installation>/logs/<WEBAPPLIKATION_NAME>.log und ADOIT-Installation/*_aworker.log geloggt.

Mehr

In diesem Abschnitt:

• Benutzergruppen in ADOIT einrichten
• Administratoren in ADOIT konfigurieren
• Regex-Mappings erstellen
• Zertifikatswechsel
• Änderungen des Anmeldenamens verwalten

Benutzergruppen in ADOIT einrichten

Ein effektives Autorisierungskonzept für SAML-basierte Authentifizierung in ADOIT erfordert die Erstellung von Benutzergruppen in ADOIT, die auf IdP-Gruppen mappen. So werden die Personen in Ihrer Organisation mit ADOIT-Benutzergruppen verbunden. Nachdem Sie die Gruppen definiert haben, konfigurieren Sie deren Berechtigungen und weisen System-Rollen zu. Hier ist eine Übersicht über die Schritte:

Benutzergruppen erstellen

In ADOIT lassen sich ganz einfach Benutzergruppen erstellen. Dazu müssen Sie Folgendes tun:

1. Wechseln Sie in der ADOIT Administration auf die Seite Benutzer.

2. Wählen Sie den Pfeil neben Neuer Benutzer aus, und wählen Sie dann Neue Benutzergruppe auf oberster Ebene aus.

3. Geben Sie im Feld Name eingeben einen Namen für Ihre Benutzergruppe ein (z. B. Modellierer) und klicken Sie dann auf OK.

Wiederholen Sie diese Schritte, um alle erforderlichen Benutzergruppen für Ihr Authentifizierungskonzept zu erstellen, z. B. Administratoren, Modellierer und Leser.

Berechtigungen für Benutzergruppen festlegen

Sobald die Gruppen erstellt sind, vergeben Sie Berechtigungen für Inhalte wie Modelle und Objekte auf Ebene dieser Gruppen:

1. Wechseln Sie in der ADOIT Administration auf die Seite Rechte.

2. Wählen Sie die Benutzergruppe aus, die Sie konfigurieren möchten.

3. Wählen Sie als Nächstes eine Registerkarte aus, um die passendende Kategorie von Berechtigungen anzuzeigen, z. B. Modelle oder Objekte.

4. Um Informationen darüber zu erhalten, welche Berechtigungen für ein Element gelten, überprüfen Sie die Spalte Lesen/Schreiben. Wenn Sie das gewünschte Element nicht sehen können, erweitern Sie die Hierarchie aus Gruppen und Einträgen, um alle Elemente anzuzeigen.

5. Um Berechtigungen zu ändern, führen Sie eine der folgenden Aktionen aus:

   • Um die Berechtigungen für ein einzelnes Element zu ändern, klicken Sie in der Spalte Lesen/Schreiben auf Berechtigungen ändern, und wählen Sie dann eine Berechtigung aus.

   • Um die Berechtigungen für mehrere Elemente auf einmal zu ändern, aktivieren Sie die Kontrollkästchen links neben den Elementen, klicken Sie auf Bulk-Aktionen, und wählen Sie dann die gewünschte Berechtigung aus.

Beispiel:

• Wenn die Gruppe Leser keine Inhalte ändern muss, können Sie ihren Zugriff für alle Modell- und Objektgruppen auf Lesen beschränken.

• Dies lässt sich am einfachsten erreichen, indem Sie die Berechtigungen für die Standardgruppen Modelle und Objekte anpassen. Diese Berechtigungen gelten dann automatisch für alle untergeordneten Gruppen, sofern dort keine eigenen Berechtigungen gesetzt sind.

Standard-System-Rollen an Benutzergruppen zuweisen

Als Nächstes weisen Sie die vordefinierten Standard-System-Rollen Ihren Benutzergruppen zu. Diese Rollen steuern den Zugriff auf die Szenarien von ADOIT und Freigabeworkflows.

Hinweis

Weitere Informationen zu den Standard-System-Rollen finden Sie in der ADOIT Hilfe.

Durch Zuweisung dieser System-Rollen an Ihre Benutzergruppen werden die mit diesen Rollen verbundenen Berechtigungen automatisch auf alle Gruppenmitglieder übertragen:

1. Wechseln Sie in der ADOIT Administration auf die Seite Benutzer.

2. Bewegen Sie den Mauszeiger auf die Benutzergruppe, die Sie anpassen möchten, klicken Sie auf Mehr, und dann auf System-Rollen zuweisen.

3. Wählen Sie die gewünschten System-Rollen aus und klicken Sie auf Auswählen.

Beispiel:

Angenommen, Mitglieder der Benutzergruppen Administratoren, Modellierer und Leser sollen Zugriff auf unterschiedliche Szenarien in ADOIT haben. Die Konfiguration könnte folgendermaßen aussehen:

• Weisen Sie die System-Rolle User den Benutzergruppen Administratoren und Modellierer zu, um Zugriff auf ALLE Szenarien zu gewähren.
• Weisen Sie die Systemrolle Reader der Benutzergruppe Leser zu, um Zugriff auf das Szenario "Lesen & Entdecken" zu gewähren.

Optional: Module und Metamodellrechte

Für komplexere Anwendungsfälle können Sie System-Rollen Zugriff auf bestimmte Module gewähren (z. B. Matrix- Charts oder Excel-Importfunktionen). Sie können diese Module den Standard-System-Rollen zuweisen oder neue Rollen erstellen.

Um Zugriffsberechtigungen noch präziser zu steuern, können Sie auf Ebene von System-Rollen Metamodellrechte konfigurieren. So legen Sie fest, wer in ADOIT mit Metamodellelementen wie Modelltypen und Attributen arbeiten darf. Da die vordefinierten Standard-System-Rollen diese Rechte nicht unterstützen, ist es notwendig, eigene System-Rollen für diesen Zweck zu erstellen.

Hinweis

Weitere Informationen zum Zuweisen von Modulen, zum Erstellen von System-Rollen und zum Konfigurieren von Metamodellrechten finden Sie in der ADOIT Hilfe:

• Module

• System-Rolle erstellen

• Metamodellrechte verwalten

Administratoren in ADOIT konfigurieren

In ADOIT können Administratoren auf zwei Arten erstellt werden:

• Globale Administratoren: Weisen Sie einem Benutzer umfassende Administratorrechte für das gesamte System zu, sodass er nahezu alle administrativen Aufgaben ausführen kann.

• Sub-Administratoren: Gewähren Sie eingeschränkte Administratorrechte, um bestimmte Repository-Bereiche oder Benutzergruppen zu verwalten - entweder auf Gruppenebene oder für einzelne Benutzer.

Lesen Sie weiter, um zu erfahren, wie das funktioniert.

Globale Administrationsrechte zuweisen

So machen Sie einen Benutzer zum globalen Administrator:

1. Wechseln Sie in der ADOIT Administration auf die Seite Rechte.

2. Wählen Sie den Benutzer aus, der globale Administrationsrechte erhalten soll.

3. Wechseln Sie auf die Registerkarte Komponenten.

4. Suchen Sie im Arbeitsbereich nach der Komponente Administrations-Toolkit.

5. Klicken Sie in der Spalte Zugriff auf Berechtigungen ändern, und wählen Sie dann Globale Administrationsrechte zuweisen aus. Wenn Sie zum Fortfahren aufgefordert werden, klicken Sie auf Ja.

Damit erhält der Benutzer Schreibzugriff auf alle Modellgruppen, Modelle, Objektgruppen, Objekte, Benutzergruppen und Benutzer.

Sub-Administratoren konfigurieren

Führen Sie folgende Schritte aus, um Sub-Administratoren zu konfigurieren:

Zugriffsrechte auf die ADOIT Administration gewähren

Sub-Administratoren benötigen Zugriff auf die ADOIT Administration, um Benutzerrechte verwalten zu können. Weisen Sie dies auf Gruppenebene zu, um den Verwaltungsaufwand zu reduzieren:

1. Wechseln Sie in der ADOIT Administration auf die Seite Rechte.

2. Wählen Sie die Benutzergruppe aus, die Sie autorisieren möchten.

3. Wechseln Sie auf die Registerkarte Komponenten.

4. Suchen Sie im Arbeitsbereich nach der Komponente Administrations-Toolkit.

5. Klicken Sie in der Spalte Zugriff auf Berechtigungen ändern, und wählen Sie dann Zugriffsberechtigung aus.

Sub-Administratoren das Verwalten von Benutzerrechten ermöglichen

Damit Sub-Admins die Zugriffsrechte anderer Benutzer auf Modelle und Objekte ändern können, erlauben Sie Berechtigungen ändern für die zu verwaltenden Benutzergruppen:

1. Wechseln Sie in der ADOIT Administration auf die Seite Rechte.

2. Klicken Sie auf die Expertenmodus Schaltfläche.

3. Wählen Sie die Sub-Admin-Benutzergruppe aus.

4. Wechseln Sie auf die Registerkarte Benutzer.

5. Für jede Benutzergruppe, deren Rechte von den Sub-Administratoren verwaltet werden sollen, klicken Sie in der Spalte Zugriffsrechte ändern auf Berechtigungen ändern und wählen Sie Erlaubt aus.

Mitglieder der Sub-Admin-Benutzergruppe können sich nun in die ADOIT Administration einloggen und die Rechte für die Benutzergruppen verwalten, die ihnen zugewiesen sind.

Hinweis

Um eine Rechteausweitung zu verhindern, können Sub-Administratoren keine Rechte vergeben, die über ihre eigenen hinausgehen. Zum Beispiel kann ein Sub-Admin mit Lesezugriff auf die Modellgruppe "Modelle" nicht Schreibzugriff für diese Gruppe vergeben.

Regex-Mappings erstellen

Wenn Sie in ADOIT ein User Mapping konfigurieren, können Sie mithilfe regulärer Ausdrücke erweiterte, musterbasierte Regeln für die Zuweisung von Benutzern zu System-Rollen, Benutzergruppen usw. Auf Grundlage IdP-Claims erstellen. Dies ist insbesondere dann hilfreich, wenn Gruppennamen in Ihrem IdP einer Namenskonvention folgen oder bestimmte Muster enthalten.

So erstellen Sie ein Regex-Mapping:

• Setzen Sie Typ auf regexp und geben Sie Ihren regulären Ausdruck im Feld Match ein.

Schauen wir uns zwei Beispiele an:

Beispiel 1: Regex-Mapping mit "exakter Zeilenübereinstimmung"

In diesem Beispiel möchten wir Benutzer der Benutzergruppe Leser in ADOIT zuordnen, wenn der Wert von claim_group genau "ReadOnly" als eigene Zeile oder am Anfang bzw. Ende einer Zeile enthält. Hier ist die Konfiguration:

Gruppen
- Standardgruppen: (nicht konfiguriert)
- Gruppen:
  - Benutzergruppe: Readers
    - Eigenschaft: claim_group 
    - Typ: regexp
    - Match: (?s).*(^|\n)ReadOnly($|\n).*

Erklärung:

• Match: Der reguläre Ausdruck (?s).*(^|\n)ReadOnly($|\n).* sorgt dafür, dass "ReadOnly" nur dann zugeordnet wird, wenn es als gesamte Zeile oder am Anfang oder Ende einer Zeile erscheint. Hier ist die Funktionsweise:
  • (?s): Aktiviert den "dotall"-Modus, sodass . jedes Zeichen einschließlich Zeilenumbrüchen abdecken kann.
  • (^|\n)ReadOnly($|\n): Verankert "ReadOnly" am Anfang (^) oder Ende ($) einer Zeile und stimmt nur dann zu, wenn es als eigene Zeile erscheint.
  • .* vor und nach diesem Ausdruck erlaubt beliebigen Text, was bei mehrzeiligen Zeichenfolgen Flexibilität bietet.

Beispiel 2: Regex-Mapping mit "Enthält"-Übereinstimmung

In diesem Beispiel ordnen wir Benutzer der Benutzergruppe Leser zu, wenn claim_group irgendwo im Text „ReadOnly“ enthält. Hier ist die Konfiguration:

Gruppen
- Standardgruppen: (nicht konfiguriert)
- Gruppen:
  - Benutzergruppe: Readers
    - Eigenschaft: claim_group 
    - Typ: regexp
    - Match: .*ReadOnly.*

Erklärung:

• Match: Das Muster .*ReadOnly.* erfasst jeden Wert in claim_group, der "ReadOnly" als Teilzeichenfolge enthält, unabhängig von seiner Position.

Zusätzliche Ressourcen

Falls Sie mit regulären Ausdrücken nicht vertraut sind oder mehr über deren Aufbau erfahren möchten, finden Sie hier eine ausgezeichnete Einführung in reguläre Ausdrücke: Regular Expressions (Regex).

Zum Testen Ihrer Regex-Muster und zur Überprüfung, dass sie wie gewünscht übereinstimmen, können Sie regex101 nutzen – ein hilfreiches Tool zur Erstellung und Validierung von regulären Ausdrücken.

Zertifikatswechsel

Das von Ihrem IdP verwendete Zertifikat zum Signieren von SAML-Tokens (Cert IdP-sig) muss regelmäßig erneuert werden. Wenn dies geschieht, muss sichergestellt werden, dass ADOIT mit dem neuen Zertifikat aktualisiert wird, um die Vertrauensbeziehung zwischen ADOIT und Ihrem IdP aufrechtzuerhalten.

Es gibt zwei Szenarien für die Verwaltung des Zertifikatswechsels, abhängig davon, wie das Zertifikat ursprünglich in ADOIT konfiguriert wurde: durch die Referenzierung einer Metadaten-URL oder durch direktes Hochladen des Zertifikats.

Szenario 1: Referenzierung der Metadaten-URL

Falls Sie bei der initialen Konfiguration die Metadaten-URL des IdP referenziert haben, müssen Sie den Konnektor nach einem Zertifikatswechsel manuell aktualisieren. Obwohl ADOIT die neuesten Metadaten von der URL abrufen kann, wird die Konfiguration nicht automatisch regelmäßig aktualisiert. Führen Sie daher nach einem Zertifikatswechsel folgende Schritte aus, um das Zertifikat zu erneuern:

1. Wechseln Sie in der ADOIT Administration zu Authentifizierung > Konnektoren.

2. Bewegen Sie den Mauszeiger auf den SAML 1 Konnektor, klicken Sie auf Mehr, und dann auf IdP konfigurieren.

3. Wählen Sie in der Liste Konfigurationsquelle die Option URL aus.

4. Das Feld Metadaten URL sollte bereits mit der Metadaten-URL Ihres IdP ausgefüllt sein. Falls nicht, geben Sie diese hier ein.

5. Klicken Sie auf OK, schließen Sie die Erfolgsmeldung und speichern Sie die Änderungen.

Dieser Vorgang stellt sicher, dass ADOIT das neue Zertifikat aus den Metadaten abruft.

Szenario 2: Direktes Hochladen des Zertifikats

Falls Sie das Zertifikat direkt in ADOIT hochgeladen haben, müssen Sie bei einem Zertifikatswechsel des IdP das neue Zertifikat ebenfalls manuell hochladen. Gehen Sie wie folgt vor, um das Zertifikat zu aktualisieren:

1. Wechseln Sie in der ADOIT Administration zu Authentifizierung > Konnektoren.

2. Bewegen Sie den Mauszeiger auf den SAML 1 Konnektor, klicken Sie auf Mehr, und dann auf Bearbeiten.

3. Klicken Sie auf der Seite Eigenschaften der Konnektorkonfiguration unter IDP public key file auf Durchsuchen, um das neue Token-Signaturzertifikat vom IdP hochzuladen. Wenn Sie zum Fortfahren aufgefordert werden, klicken Sie auf Ja.

4. Eine Erfolgsmeldung wird angezeigt. Schließen Sie die Meldung Fenster und speichern Sie Ihre Änderungen.

Durch das Hochladen des neuen Zertifikats stellen Sie sicher, dass ADOIT weiterhin SAML-Tokens validiert, die von Ihrem IdP ausgestellt wurden.

Änderungen des Anmeldenamens verwalten

In einigen Fällen kann sich der vom IdP in der SAML-Antwort angegebene Anmeldename ändern, z. B. nach einer Namensänderung (z. B. Heirat) oder aufgrund einer Domain-Migration. In diesem Fall behandelt ADOIT den neuen Anmeldenamen als einen anderen Benutzer, was zur Erstellung eines neuen Benutzerkontos und eines entsprechenden neuen Benutzerobjekts führt. Dies bedeutet, dass dieselbe Person zwei Konten in ADOIT hat – eines mit dem alten Anmeldenamen und ein anderes mit dem neuen.

Wenden Sie sich zur Behebung dieses Problems bitte an unser Supportteam. Unsere Kollegen können den Anmeldenamen im System aktualisieren und die beiden Benutzerobjekte zu einem zusammenführen. Sobald die Änderung verarbeitet wurde, kann sich der Benutzer mit seinen neuen Anmeldeinformationen anmelden, wobei alle seine Beziehungen in ADOIT intakt bleiben.