Source:Configuring Certificate-Based Authentication

From SEPsesam
Revision as of 09:26, 13 April 2021 by Sta (talk | contribs) (Marked this version for translation)
Other languages:

Copyright © SEP AG 1999-2024. All rights reserved.

Any form of reproduction of the contents or parts of this manual is allowed only with the express written permission from SEP AG. When compiling and designing user documentation SEP AG uses great diligence and attempts to deliver accurate and correct information. However, SEP AG cannot issue a guarantee for the contents of this manual.

Docs latest icon.png Welcome to the latest SEP sesam documentation version 5.0.0 Jaglion. For previous documentation version(s), check Documentation archive.


Overview

As of SEP sesam v. 5.0.0 Jaglion, if database-based authentication is enabled it is possible to authenticate users via a signed certificate instead of using a username and password.

However, if you combine database-based authentication with LDAP or AD authentication, the users from external authentication sources (LDAP/AD) cannot use certificate-based authentication; LDAP/AD authentication requires password-based authentication. For more details on SEP sesam authentication, see About Authentication and Authorization.

Configuring authentication via signed certificate

Configuring authentication via a signed certificate requires superuser rights. This procedure involves the following steps:

  1. A user creates a user authentication certificate signing request (CSR) and sends it to administrator with superuser rights.
  2. The superuser (system administrator) signs the certificate and assigns the certificate to a user account.
  3. Afterwards, the user is able to authenticate via the certificate in one of the SEP sesam interfaces (SEP sesam GUI, SEP sesam Web UI, SEP sesam CLI).

Creating a user authentication certificate signing request (user side)

Note that if you have an existing private SSL key for which you want to create a certificate, skip step 1 and proceed with step 2.

  1. Create a new private key as follows:
  2. openssl genrsa -out <key name>.key
  3. Create a certificate signing request (CSR) from the private key:
  4. openssl req -new -key <key name>.key -out <key name>.csr
  5. Send the CSR to your system administrator.

Signing the user authentication certificate (by a user with superuser rights)

  1. Navigate to the directory where you have placed the user CSR file and sign the CSR using the REST server user authentication certificate:
  2. openssl x509 -trustout -days <days> -req -signkey <SESAM_VAR>/ini/ssl/sesam.auth.key -in <key name>.csr -out <key name>.crt
    Information sign.png Note
    In SEP sesam v. < 5.0.0 Jaglion, the REST server user authentication certificate signing key is named sesam.gui.key.
  3. Obtain the thumbprint of the signed user authentication certificate:
  4. openssl x509 -noout -fingerprint -sha1 -inform pem -in <key name>.crt
  5. Send the user authentication certificate (crt) back to the user.

Assigning the user authentication certificate to a user account (by a user with superuser rights)

To assign the user authentication certificate to a user account, proceed as follows:

  1. In the SEP sesam GUI, from the menu bar select Configuration ‐> Permission Management.
  2. Double-click the user account to which a user authentication certificate will be assigned to. The new Change User window opens.
  3. Click the + (plus) button and in the Add Thumbprint window, enter or paste the thumbprint of the user authentication certificate.
  4. Authentication via certificate add thumbprint.jpg
  5. Click OK in both open dialogs to add the certificate to the Certificate Thumbprints list.

Using the user authentication certificate for authentication (user side)

A user receives the authentication certificate from the administrator (with superuser rights) and has to save it to a location readable only by the user. Once this is done, the user should be able to authenticate via certificate by using one of the SEP sesam interfaces (SEP sesam GUI, SEP sesam Web UI, SEP sesam CLI) as described below.

Authentication in the GUI

To authenticate via a certificate in the GUI, proceed as follows:

  1. Run the SEP sesam GUI as administrator and check that the user name is correct.
  2. Use the Browse button to select the user authentication certificate or enter the absolute path to the user authentication certificate file in the Certificate file field.
  3. Authentication via certificate GUI.jpg
  4. Click the Login button or press Enter to authenticate the user with the SEP sesam Server and open the SEP sesam GUI.
Information sign.png Note
The user authentication certificate can be also specified when starting the SEP sesam Administrator GUI via the -z <absolute path of the user authentication certificate file> parameter. If the authentication is successful, the login dialog is not shown and the GUI opens immediately.

Authentication in the Web UI

To authenticate via certificate in the Web UI, proceed as follows:

  1. Enter the administrator user name.
  2. Use the Choose File button to select the user authentication certificate file from your computer.
  3. Authentication via certificate Web UI.jpg
  4. Click the Sign in button or press Enter to authenticate the user with the SEP sesam Server and to open the SEP sesam Web UI.

Authentication in the SEP sesam CLI

To authenticate via certificate in the SEP sesam CLI, use the following command-line options:

sm_cmd ... -U <user name> -z <absolute path of the user authentication certificate file> ...

Replacing the self-signed certificate with a custom user authentication server certificate

Once the REST server starts, it generates a self-signed user authentication server certificate and private key. Typically, these are sufficient to enable the certificate-based user authentication described above.

However, a server administrator (superuser) may want to replace the self-signed certificate with the official company certificate (root user authentication certificate), signed by a publicly trusted certificate authority (CA). If you want to use the certificate and private key as a root user authentication certificate, insert both in the <SESAM_VAR>/ini/ssl and name the files sesam.auth.crt (certificate) and sesam.auth.key (private key).

In this case, when the REST server is started, it performs the following to find the root user authentication certificate:

  1. If a certificate and the corresponding private key are specified via command line options ([-Z|--sesamUserSslCertificate] <absolute file name certificate>, [-K|--sesamUserSslPrivateKey> <absolute file name private key>), then it tries to use the given files.
  2. If the variable gv_ro_ssl_auth exists in the sm.ini (PATHES section), this location is probed next using the default file names.
  3. If the variable gv_ro_ssl exists in the sm.ini (PATHES section), this location is probed next using the default file names.
  4. Looks at the default location using the default file names (default location = <SESAM_VAR>/ini/ssl, default file names = sesam.auth.crt, sesam.auth.key).

To verify that the correct root user authentication certificate is used, in the sm_gui_server.log look for a line reading:

Enabling certificate-based user authentication using root certificate file <absolute path of the certificate file used>

See also

About Authentication and AuthorizationConfiguring Database-Based Authentication