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 interface
2. Navigate to the Certificates tab
   
3. Under Certificate, select CA from the menu.
   
4. Under Certificate, select the CA certificate (.pem) to be installed.
   
5. Click Upload
   
6. Under Available CAs, enable the Trusted Peer option for the newly installed certificate so that the certificate is automatically used for all query services.
   
7. Under Certificate, select SSL.
   
8. Under Certificate, select the client certificate (.pem) to be installed.
   
9. Click Upload
   
10. Navigate to the Client Services tab
    
11. Under Trusted Peer Communication To Query Services – Credential Certificate, select the installed client certificate.
    
12. Enable the setting Trusted Peer Communication To Query Services – Authentication Generates Trusted Peer Credentials
    

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

1. Navigate to the Client Services tab
   
2. Open the settings of the desired client service
3. Enable Trusted Peer Access Using Certificates – Enable Trusted Peer Access Using Certificates
   
4. UnderTrusted Peer Access Using Certificates – Certificate Subjects Trusted for Identity Delegation, enter a regular expression to check the Subject property of the client certificate (Java, case-sensitive). The option 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.

1. Navigate to the Client Services tab
   
2. Open the settings of the desired client service
3. Enable Trusted Peer Access Using OAuth 2.0 Bearer Token – Enable Trusted Peer Access Using OAuth 2.0 Bearer Token
   
4. Store the address of the OAuth server in Auth Server URL
   
5. Check the rest of the settings in Trusted Peer Access Using OAuth 2.0 Bearer Token and change the following if desired:

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 option Trusted Peer Identity Extraction – Identity Extraction Order 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.