Configuring Trusted Peer Authentication

Introduction

Users typically log in directly to the client service when searching. To do this, one of the authentication methods, Kerberos, SAML, or CAS is used.

With trusted peer authentication, it is possible to send the user name used for the authorization check of the search results along with the query. In order to prevent a user from searching in the name of another user, the caller must provide proof that he or she can be trusted.

There are two ways to do this:

1. The request uses a client certificate signed by a CA certificate stored in the configuration.
2. The request contains an OAuth 2.0 Bearer Token from a configured OAuth server.

Trusted peer authentication can be used, for instance

• when the search is integrated into an existing application where authentication already takes place, or
• when the API is used directly.

Requirements

In order for client services to be able to use trusted peer authentication, communication between client service and query service has to be secured using trusted peer authentication with certificates.

Trusted peer authentication with certificates

If certificates are used for the trust relationship between requester and service, the following conditions must be met:

• A CA certificate is installed on the appliance and labeled asTrusted Peer.
• The requester sends the request with a client certificate signed by this CA certificate.
• The property Subject of the client certificate matches a configured regular expression (only for client services).

Requirements for the certificates

Important: The CA certificate may only be used for the trust relationship. Each requester receives a client certificate signed with this CA certificate. This reduces the potential for improper use. For example, it is negligent to use the CA certificate that is used for SSL server certificates in the company, otherwise every SSL server certificate would be trusted.

The CA certificate must be available as a PEM file. The private key does not have to be included. For communication between client service and query service, a client certificate in PKCS #12 format and without password must be installed.

Only one CA certificate per installation can be used as a trusted peer certificate.

Installation and selection of certificates

1. Open the “Configuration” menu and navigate to the „Certificates“ tab.
2. Under „Certificate“, select „CA“ from the drop-down-menu and select the CA certificate (.pem) to be installed. Click „Upload“ to start uploading the CA certificate.

1. Under “Available CAs”, enable the option “Trusted Peer” for the newly installed certificate so that the certificate is automatically used for all query services.

Under Certificate, select SSL and then select the client certificate (.pem) to be installed. Then upload the SSL certificate with “Upload.

Navigate to the tab “Client Services” and in the section “Trusted Peer Communication To Query Services” select the installed client certificate in the setting “Credential Certificate”. Also, enable the setting “Authentication Generates Trusted Peer Credentials”:

Enable the trusted peer authentication with certificates on the client service.

• Navigate to the tab “Client Services” and open the desired client service.
• Then go to the section “Trusted Peer Access Using Certificates” and enable the setting “Enable Trusted Peer Access Using Certificates”.
• In the setting “Certificate Subjects Trusted for Identity Delegation”, enter a regular expression to check the property “Subject” of the client certificate (Java, case-sensitive). The setting must be selected.

Trusted peer authentication with OAuth 2.0 bearer token

When authenticating with OAuth 2.0 bearer token, the OAuth server must be stored. Trusted peer authentication is only allowed for users who have been assigned a configured role. The individual configuration values are best obtained from your OAuth server administrator.

• Navigate to the tab “Client Services” and open the desired client service.
• In the section “Trusted Peer Access Using OAuth 2.0 Bearer Token” enable the setting “Enable Trusted Peer Access Using OAuth 2.0 Bearer Token”.
• In the setting “Auth Server URL” put in the address of the OAuth server.

1. Check the rest of the settings and adjust them according to your use case:

Sending the user name

The user name can be sent either as an HTTP header or in the request.

User name as HTTP header

The user name is transmitted as HTTP header X-Auth-User.

Example of sending the user name as HTTP header:

X-Auth-User: max.mustermann

User name as part of the request

For api.v2 queries, the user name can be transmitted in the user_context.username property.

Example of sending the user name as part of an api.v2.search query:

{

  "user_context": {

    "user_name": "max.mustermann"

  },

  "properties": [

    {

      "formats": [

        "HTML"

      ],

      "name": "title"

    }

  ],

  "count": 5,

  "query": {

    "unparsed": "mindbreeze"

  }

}

Selecting the source of the user name

The setting “Identity Extraction Order” in the section “Trusted Peer Identity Extraction” determines how the user name can be sent. The following options are available:

Sending User Groups

User groups can be transferred as HTTP header X-Auth-Groups. The user groups must be comma-separated and then HTML form encoded.

Example for sending user groups as HTTP header:

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

This results in the following user groups:

marketing

authors

quality assurance

Sending User Properties

With HTTP headers it is possible to add additional attributes to the user identity.

HTTP headers can be sent according to the following patterns:

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

For example, the following headers

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

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

create this properties:

"mail": "user@example.com"

"color": "light blue"

Note: The {{value}} must be HTML form encoded.

These attributes are internally linked to the user identity (Identity Property) and can then be used in other services.