Source:Configuring Certificate-Based Authentication

From SEPsesam
Revision as of 10:21, 14 September 2022 by Jus (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.

Configuring authentication using a signed certificate

Configuring authentication with a signed certificate requires superuser privileges. You have to create a user authentication certificate and assign it to a user account. The easiest way is to use the SEP sesam GUI, where the certificate is automatically created and assigned to a user account. Optionally, you can also create and assign a certificate manually, but this requires additional steps.

Then the user can 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 in the GUI

In the SEP sesam GUI, you can easily set a user authentication certificate that is automatically created and assigned to a user.

  1. From the SEP sesam GUI menu bar, select Configuration ‐> Permission Management.
  2. Double-click the user for whom you want to create a user authentication certificate. In the new window Change User click New.
  3. Authentication via certificate new.jpg
  4. Select a folder on your computer where you want to save the certificate and click Save. The certificate and thumbprint are created automatically.
  5. Authentication via certificate save.jpg
  6. In both open dialogs, click OK to set the certificate.

Creating a user authentication certificate manually

Optionally, you can also create and assign a user authentication certificate manually. This procedure involves the following steps:

  1. A user creates a user authentication certificate signing request (CSR) and sends it to an administrator with superuser privileges.
  2. The superuser (system administrator) signs the certificate.
  3. The superuser then assigns the certificate to a user account.
  4. For LDAP/AD based authentication, the administrator binds the certificate to the user in LDAP/AD. For instructions refer to the corresponding LDAP/AD server documentation.

Creating a user authentication certificate signing request (user side)

Information sign.png Note
The private key must be in PKCS8 format. If you have a key in another format, you need to convert it to PKCS8 first. For this you can use the openssl utility.

If you already have an SSL private key that you want to create a certificate for, skip step 1 and go to 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 privileges)

  1. Navigate to the directory where you placed the user CSR file and sign the CSR with 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. Get 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, do the following:

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

Using the user authentication certificate for authentication (user side)

A user obtains the authentication certificate from the administrator (with superuser privileges) and must store it in a location that is readable only by the user. Once this is done, the user should be able to authenticate via the certificate 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. Start the SEP sesam GUI as administrator and verify 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 to the SEP sesam Server and open the SEP sesam GUI.
Information sign.png Note
The user authentication certificate can also be specified when starting the SEP sesam Administrator GUI using the -z <absolute path of the user authentication certificate file> parameter. If the authentication is successful, the login dialog will not be displayed and the GUI will open immediately.

Authentication in the Web UI

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

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

Authentication in the SEP sesam CLI

To authenticate using a 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

As soon as the REST server starts, it generates a self-signed user authentication server certificate and private key. Normally, 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 the private key as root user authentication certificate, add both to the <SESAM_VAR>/ini/ssl and name the files sesam.auth.crt (certificate) and sesam.auth.key (private key).

In this case, the REST server will perform the following on startup to find the root user authentication certificate:

  1. If a certificate and associated private key are specified via command line options ([-Z|--sesamUserSslCertificate] <absolute file name certificate>, [-K|--sesamUserSslPrivateKey> <absolute file name private key>), it attempts to use the specified files.
  2. If the variable gv_ro_ssl_auth is present in sm.ini (PATHES section), this location is probed next using the default file names.
  3. If the variable gv_ro_ssl is present in sm.ini (PATHES section), this location is checked 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 that reads:

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

See also

Configuring SSL Secured Communication for SEP sesam Backup NetworkAbout Authentication and AuthorizationConfiguring Database-Based Authentication - Configuring LDAP/AD Authentication