Configuring Trusted Peer Authentication for Mindbreeze InSpire

Copyright ©

Mindbreeze GmbH, A-4020 Linz, 2018.

All rights reserved. All hardware and software names used are brand names and/or trademarks of their respective manufacturers.

These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes, or any other protected rights. The dissemination, publication, or reproduction hereof is prohibited.

For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.

IntroductionPermanent link for this heading

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.

RequirementsPermanent link for this heading

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 certificatesPermanent link for this heading

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 certificatesPermanent link for this heading

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 certificatesPermanent link for this heading

  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.Permanent link for this heading

  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 tokenPermanent link for this heading

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 TokenEnable 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:

Realm

the OAuth Realm to be used; see your OAuth server for details

Resource

the OAuth resource to be used; details can be found on your OAuth server (in some OAuth servers also called client)

SSL Security for Communication with Auth Server

determines how the HTTPS connection to the Auth Server will be checked:

Validate Certificate and Hostname

The server certificate of the Auth Server must be issued by a trusted certificate and the host name must match the Auth Server URL option.

Validate Hostname

The host name in the server certificate of the Auth Server must match the Auth Server URL option.

No Validation (do not use in production)

The server certificate of the Auth Server is always accepted

Role Trusted for Identity Delegation

Only users assigned to this role are allowed to perform trusted peer authentication.

Sending the user namePermanent link for this heading

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

User name as HTTP headerPermanent link for this heading

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 requestPermanent link for this heading

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 namePermanent link for this heading

The option Trusted Peer Identity Extraction – Identity Extraction Order determines how the user name can be sent. The following options are available:

Header, request

The user name is used if it is set in the X-Auth-User HTTP header. If not, the user name from the query is used.

Header

The user name in the X-Auth-User HTTP header is used. The request will not be considered.

Request

The user name from the query is used. The X-Auth-User HTTP header will not be considered.

Request, header

If the user name is set in the query, it is used. If not, the user name from the X-Auth-user HTTP header is used.