Konfiguration von Trusted Peer Authentication
Mindbreeze InSpire

Einführung

Typischerweise melden sich Benutzer bei der Suche direkt am Client Service an. Dazu wird eine der Authentifizierungsvarianten Kerberos, SAML oder CAS verwendet.

Mit Trusted Peer Authentifizierung ist es möglich, dass der Benutzername, der für die Berechtigungsprüfung der Suchresultate verwendet wird, mit der Anfrage gesendet wird. Damit dadurch nicht jeder Benutzer im Namen eines anderen suchen kann, muss der Aufrufer einen Beweis erbringen, dass ihm vertraut werden kann.

Hierfür gibt es folgende zwei Möglichkeiten:

1. die Anfrage verwendet ein Clientzertifikat, das von einem in der Konfiguration hinterlegten CA-Zertifikat signiert wurde
2. die Anfrage enthält einen OAuth 2.0 Bearer Token eines konfigurierten OAuth-Servers.

Trusted Peer Authentifizierung wird unter anderem verwendet, wenn

• die Suche in eine bestehende Anwendung eingebunden wird, wo bereits eine Authentifizierung stattfindet, oder
• die API direkt verwendet wird.

Voraussetzungen

Damit Client Services Trusted Peer Authentifizierung nutzen können, muss die Kommunikation zwischen Client- und Query Service mit Trusted Peer Authentifizierung mit Zertifikaten abgesichert sein.

Trusted Peer Authentifizierung mit Zertifikaten

Werden Zertifikate für die Vertrauensbeziehung zwischen Anfragesteller und Service verwendet, muss folgendes gegeben sein:

• auf der Appliance ist ein CA-Zertifikat installiert und als Trusted Peer markiert
• der Anfragesteller sendet die Anfrage mit einem von diesem CA-Zertifikat signierten Clientzertifikat
• die Eigenschaft Subject des Clientzertifikats stimmt mit einem konfigurierten regulären Ausdruck überein (nur bei Client Services)

Anforderungen an die Zertifikate

Wichtig: Das CA-Zertifikat darf ausschließlich für die Vertrauensbeziehung verwendet werden. Jeder Anfragesteller erhält ein mit diesem CA-Zertifikat signiertes Clientzertifikat. Dadurch werden die Missbrauchsmöglichkeiten eingeschränkt. Es ist beispielsweise fahrlässig das CA-Zertifikat zu verwenden, dass für SSL Server-Zertifikate im Unternehmen verwendet wird, sonst würde jedem SSL Server-Zertifikat vertraut.

Das CA-Zertifikat muss als PEM-Datei vorliegen. Der Private Key muss nicht enthalten sein. Für die Kommunikation zwischen Client- und Query Service muss ein Clientzertifikat im PKCS #12-Format und ohne Passwort installiert sein.

Es kann pro Installation nur ein CA-Zertifikat als Trusted Peer Zertifikat verwendet werden.

Installation und Auswahl der Zertifikate

• Öffnen Sie das „Configuration“-Menü und navigieren Sie zum Tab „Certificates“.
• Wählen Sie unter „Certificate“ in der Auswahl „CA“ aus und das zu installierende CA-Zertifikat (.pem). Klicken Sie „Upload“ um das Hochladen des CA-Zertifikates zu starten.

• Aktivieren Sie unter „Available CAs“ die Option „Trusted Peer“ beim neu installierten Zertifikat damit wird das Zertifikat automatisch für alle Query Services verwendet.

Wählen Sie unter „Certificate“ in der Auswahl „SSL“ aus und das zu installierende Clientzertifikat (.pem). Klicken Sie „Upload“ um das SSL-Zertifikat hochzuladen.

Navigieren Sie zum Tab „Client Services“ und im Bereich „Trusted Peer Communication To Query Services” wählen Sie das installierte Clientzertifikat in der Einstellung “Credential Certificate” aus. Aktivieren Sie auch die Einstellung “Authentication Generates Trusted Peer Credentials”.

Aktivieren der Trusted Peer Authentifizierung mit Zertifikaten am Client Service

• Navigieren Sie zum Tab „Client Services“ und öffnen Sie den gewünschten Client Service.
• Gehen Sie zum Abschnitt „Trusted Peer Access Using Certificates” und aktivieren Sie die Einstellung “Enable Trusted Peer Access Using Certificates”.
• In der Einstellung „Certificate Subjects Trusted for Identity Delegation“, hinterlegen Sie einen regulären Ausdruck mit dem die Eigenschaft „Subject“ des Clientzertifikats (Java, Groß- und Kleinschreibung werden berücksichtigt) geprüft wird. Die Einstellung muss gesetzt werden.

Trusted Peer Authentifizierung mit OAuth 2.0 Bearer Token

Bei der Authentifizierung mit OAuth 2.0 Bearer Token muss der OAuth-Server hinterlegt werden. Trusted Peer Authentifizierung wird nur Benutzern erlaubt, denen eine konfigurierte Rolle zugewiesen ist. Die einzelnen Konfigurationswerte erfragen Sie am besten bei ihrem OAuth-Server-Administrator.

• Navigieren Sie zum Tab „Client Services“ und öffnen Sie den gewünschten Client Service.
• Im Bereich „Trusted Peer Access Using OAuth 2.0 Bearer Token” aktivieren Sie die Einstellung “Enable Trusted Peer Access Using OAuth 2.0 Bearer Token”.
• Hinterlegen Sie die Adresse des OAuth-Servers in der Einstellung „Auth Server URL“.

• Kontrollieren Sie die restlichen Einstellungen und passen Sie diese gemäß ihrem Anwendungsfall an:

Senden des Benutzernamens

Der Benutzername kann entweder als HTTP-Header oder in der Anfrage gesendet werden.

Benutzername als HTTP-Header

Der Benutzername wird als HTTP-Header X-Auth-User übertragen.

Beispiel für das Senden des Benutzernamens als HTTP-Header:

X-Auth-User: max.mustermann

Benutzername als Teil der Anfrage

Bei api.v2-Anfragen kann der Benutzername in der Eigenschaft user_context.username übermittelt werden.

Beispiel für das Senden des Benutzernamens als Teil einer api.v2.search-Anfrage:

{

  "user_context": {

    "user_name": "max.mustermann"

  },

  "properties": [

    {

      "formats": [

        "HTML"

      ],

      "name": "title"

    }

  ],

  "count": 5,

  "query": {

    "unparsed": "mindbreeze"

  }

}

Auswahl der Quelle des Benutzernamens

Die Einstellung „Identity Extraction Order“ im Bereich „Trusted Peer Identity Extraction“ legt fest wie der Benutzername gesendet werden kann. Folgende Auswahlmöglichkeiten stehen zur Verfügung:

Senden von Benutzergruppen

Benutzergruppen können als HTTP-Header X-Auth-Groups übertragen werden. Die Benutzergruppen müssen beistrichgetrennt und anschließend HTML form encodiert werden.

Beispiel für das Senden von Benutzergruppen als HTTP-Header:

X-Auth-Groups: marketing%2Cauthors%2Cquality%20assurance

Dies ergibt folgende Benutzergruppen:

marketing

authors

quality assurance

Senden von Benutzerattributen

Mit HTTP-Headern ist es möglich zu der Benutzer Identität zusätzlich Attribute hinzuzufügen.

Dafür können HTTP-Header nach folgenden Muster gesendet werden:

X-Identity-Property-{{key}}: {{value}}

Zum Beispiel erzeugen folgende Header:

X-Identity-Property-mail: user@example.com

X-Identity-Property-color: light%20blue

diese Attribute:

"mail": "user@example.com"

"color": "light blue"

Hinweis: Der {{value}} muss HTML Form Encodiert sein.

Diese Attribute werden intern mit der Benutzer Identität (Identity Property) verknüpft und können dann in anderen Services verwendet werden.