- This line was added.
- This line was removed.
- Formatting was changed.
Mutual authentication is a secure two-way SSL authentication where users are authenticated with their certificates. To establish a mutual authentication, the authentication server must be configured with HTTPS protocol enabled. This can be done by following the instructions in the section Managing HTTPS/SSL on server.
User certificates can be either self-signed or signed by a trusted certificate authority (CA). The authentication server supports the user certificates installed on browsers and operating systems as well as on Smart Cards. In the latter case, additional configuration is required to enable certificate reading from the Smart Card devices, which is not covered in this manual.
To enable mutual SSL authentication
- Create a self-signed CA certificate if the user certificates will be signed by a self-signed Certificate Authority (see Creating a self-signed CA certificate). Not actual for Smart Cards usage.
- Create a truststore for the authentication server (see Creating an authentication server truststore).
- Edit the configuration file config/authserver.properties and set the appropriate parameters (see Configuring the authentication server).
- Create a self-signed user certificate if the organisation will use self-signed certificates for users (see Creating a self-signed user certificate). Not actual for Smart Cards usage.
- Install the user keystore on a user's machine if the self-signed user certificates are used (see Installing a user keystore on the user's machine). Not actual for Smart Cards usage.
- If the authentication server is deployed on a cluster, see Deployment on cluster.
Creating a self-signed CA certificate
This section only applies if the user certificates will be signed by a self-signed Certificate Authority. If there is a third-party trusted Certificate Authority that signs user certificates, or if your organization already has the infrastructure to do that, please skip this section.
The CA certificate can be generated with the following OpenSSL commands:
1. openssl genrsa -des3 -out ca.key 4096
2. openssl req -new -key ca.key -out ca.csr
3. openssl x509 -req -days 365 -in ca.csr -signkey ca.key -out ca.crt
When executing these commands you will be asked for a key password as well as for other information required for the CA certificate. Please read the instructions carefully and provide all required information. If you want the certificate to stay valid for longer than 365 days, you should specify another value in the -days 365 argument.
openssl req -new -key ca.key -out ca.csr -config /path/to/openssl.cnf
Creating an authentication server truststore
Authentication Server verifies user certificates against CA certificate, which must be stored in a truststore. To create the truststore, keytool executable should be used. It can be found in the JRE or JDK bin directory, for example:
To create the truststore for authentication server
- Run the keytool command with administrator rights to create a keystore with a CA certificate in it:
keytool -keystore truststore.jks -import -alias CA_CERTIFICATE_ALIAS -file ca.crt
Note title Notes
- When executing the keytool command you will be asked for a truststore password. Please read the instructions carefully and provide all required information.
- If the CA provides more than one certificate to be used to sign the user certificates, all of them should be added with the same keytool command. A unique alias should be specified for each certificate.
- Copy the generated file truststore.jks to the ./config directory of the authentication server.
Configuring the authentication server
To enable certificate authentication, edit the configuration file config/authserver.properties and set the appropriate parameters (see Authentication by certificate in Authentication server (advance) configuration parameters).
The authentication server handles revoked certificates by reading the certificate revocation list (CRL) files that can be either stored in the file system or available on the web. Usually, the CRL file is provided by the trusted Certificate Authority that signs user certificates. If the CRL file is stored on the file system, specify the following parameter.
Otherwise, if the CRL file is available on the web, specify the file URL.
After the Authentication Server configuration is updated, restart the service.
Creating a self-signed user certificate
This section only applies if your organization uses self-signed user certificates. Skip this section if there is a third-party Certificate Authority that signs user certificates or if your organization already has the infrastructure to do that.
For starters, you need to create a certificate and a keystore for each user. This can be done with the following OpenSSL commands.
1. openssl genrsa -des3 -out user.key 4096
2. openssl req -new -key user.key -out user.csr
3. openssl x509 -req -days 365 -in user.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out user.crt
Note that a serial number of each certificate must be unique.
Next, add a private key and a certificate to the keystore with the following command.
4. openssl pkcs12 -export -clcerts -in user.crt -inkey user.key -out user.p12
openssl req -new -key user.key -out user.csr -config /path/to/openssl.cnf
Installing a user keystore on the user's machine
The user keystore should be installed on each user's machine. The method of doing this is OS and browser dependent.
The user keystore can be installed on Linux operating system with a pk12util command from the NSS tools package:
pk12util -d sql:$HOME/.pki/nssdb -i user.p12
This will make the certificate available system-wide, enabling authentication in Magicdraw and most of the web browsers.
You can install the user keystore on Windows operating system by double-clicking the keystore file and following the instructions in the import wizard. This way you will make the certificate available system-wide, enabling authentication in MagicDraw and most of the web browsers.
You can also install the keystore on a specific web browser, like Firefox, by importing the user keystore:
- Click Options.
- Click Advanced.
- Click the Certificates tab.
- Click View Certificates.
- Click the Your Certificates tab.
- Click Import.
- Select the user.p12 keystore.
- Provide a keystore password and click OK.
- Select Settings.
- Click the Advanced settings button to expand it.
- Select Manage certificates.
- Click the Import button.
- Change the file type to Personal Information Exchange (*.pfx;*.p12).
- Select the user.p12 keystore and click Next.
- Provide a keystore password and click Next.
- Click Next > Finish.
Deployment on cluster
If the authentication server is deployed on a cluster, all service instances should use the same truststore and configuration parameters. You need to copy the truststore file and the certificate-related parameters from one server node to others.