Skip to content

Security

Jump to bottom
Anthony Romaniello edited this page May 10, 2024 · 2 revisions

This page describes authentication, permissions, and certificates used to access a SCOS sensor, as well as the authentication modes available for callback functionality. Two different types of authentication are available for authenticating against the sensor and for authenticating when using a callback URL.

Sensor Authentication And Permissions

The sensor can be configured to authenticate using mutual TLS with client certificates or using Django Rest Framework Token Authentication.

Django Rest Framework Token Authentication

This is the default authentication method. To enable Django Rest Framework token and session authentication, make sure AUTHENTICATION is set to TOKEN in the environment file (this will be enabled if AUTHENTICATION set to anything other than CERT).

A token is automatically created for each user. Django Rest Framework Token Authentication will check that the token in the Authorization header ("Token " + token) matches a user's token. Login session authentication with username and password is used for the browsable API.

Certificate Authentication

To enable Certificate Authentication, make sure AUTHENTICATION is set to CERT in the environment file. To authenticate, the client will need to send a trusted client certificate. The Common Name must match the username of a user in the database.

Certificates

Use this section to create self-signed certificates with customized organizational and host information. This section includes instructions for creating a self-signed root CA, SSL server certificates for the sensor, and optional client certificates.

As described below, a self-signed CA can be created for testing. For production, make sure to use certificates from a trusted CA.

Below instructions adapted from here.

Sensor Certificate

This is the SSL certificate used for the scos-sensor web server and is always required.

To be able to sign server-side and client-side certificates in this example, we need to create our own self-signed root CA certificate first. The command will prompt you to enter a password and the values for the CA subject.

openssl req -x509 -sha512 -days 365 -newkey rsa:4096 -keyout scostestca.key -out scostestca.pem

Generate a host certificate signing request. Replace the values in square brackets in the subject for the server certificate.

openssl req -new -newkey rsa:4096 -keyout sensor01.key -out sensor01.csr -subj "/C=[2 letter country code]/ST=[state or province]/L=[locality]/O=[organization]/OU=[organizational unit]/CN=[common name]"

Before we proceed with openssl, we need to create a configuration file -- sensor01.ext. It'll store some additional parameters needed when signing the certificate. Adjust the settings, especially DNS names, in the below example for your sensor. For more information and to customize your certificate, see the X.509 standard here.

authorityKeyIdentifier=keyid
basicConstraints=CA:FALSE
subjectAltName = @alt_names
subjectKeyIdentifier = hash
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth, # add , clientAuth to use as client SSL cert (2-way SSL)
[alt_names]
DNS.1 = localhost
# Add additional DNS names as needed, e.g. DNS.2, DNS.3, etc

Sign the host certificate.

openssl x509 -req -CA scostestca.pem -CAkey scostestca.key -in sensor01.csr -out sensor01.pem -days 365 -sha256 -CAcreateserial -extfile sensor01.ext

If the sensor private key is encrypted, decrypt it using the following command:

openssl rsa -in sensor01.key -out sensor01_decrypted.key

Combine the sensor certificate and private key into one file:

cat sensor01_decrypted.key sensor01.pem > sensor01_combined.pem
Client Certificate

This certificate is required for using the sensor with mutual TLS certificate authentication (2 way SSL, AUTHENTICATION=CERT). This example uses the same self-signed CA used for creating the example scos-sensor server certificate.

Replace the brackets with the information specific to your user and organization.

openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -subj "/C=[2 letter country code]/ST=[state or province]/L=[locality]/O=[organization]/OU=[organizational unit]/CN=[common name]"

Create client.ext with the following:

basicConstraints = CA:FALSE
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid
keyUsage = critical, digitalSignature
extendedKeyUsage = clientAuth

Sign the client certificate.

openssl x509 -req -CA scostestca.pem -CAkey scostestca.key -in client.csr -out client.pem -days 365 -sha256 -CAcreateserial -extfile client.ext

Convert pem to pkcs12:

openssl pkcs12 -export -out client.pfx -inkey client.key -in client.pem -certfile scostestca.pem

Import client.pfx into web browser for use with the browsable API or use the client.pem or client.pfx when communicating with the API programmatically.

Configure scos-sensor

The Nginx web server is not configured by default to require client certificates (mutual TLS). To require client certificates, uncomment out the following in nginx/conf.template:

ssl_client_certificate /etc/ssl/certs/ca.crt;
ssl_verify_client on;

Note that additional configuration may be needed for Nginx to use OCSP validation and/or check certificate revocation lists (CRL). Adjust the other Nginx parameters, such as ssl_verify_depth, as desired. See the Nginx documentation for more information about configuring Nginx SSL settings. The ssl_verify_client setting can also be set to optional or optional_no_ca, but if a client certificate is not provided, scos-sensor AUTHENTICATION setting must be set to TOKEN which requires a token for the API or a username and password for the browsable API.

To disable client certificate authentication, comment out the following in nginx/conf.template:

# ssl_client_certificate /etc/ssl/certs/ca.crt;
# ssl_verify_client on;

Copy the server certificate and server private key (sensor01_combined.pem) to scos-sensor/configs/certs. Then set SSL_CERT_PATH and SSL_KEY_PATH (in the environment file) to the path of the sensor01_combined.pem relative to configs/certs (for file at scos-sensor/configs/certs/sensor01_combined.pem, set SSL_CERT_PATH=sensor01_combined.pem and SSL_KEY_PATH=sensor01_combined.pem). For mutual TLS, also copy the CA certificate to the same directory. Then, set SSL_CA_PATH to the path of the CA certificate relative to configs/certs.

If you are using client certificates, use client.pfx to connect to the browsable API by importing this certificate into your browser.

Permissions and Users

The API requires the user to be a superuser. New users created using the API initially do not have superuser access. However, an admin can mark a user as a superuser in the Sensor Configuration Portal.

When scos-sensor starts, an admin user is created using the ADMIN_NAME, ADMIN_EMAIL and ADMIN_PASSWORD environment variables. The ADMIN_NAME is the username for the admin user. Additional admin users can be created using the ADDITIONAL_USER_NAMES and ADDITIONAL_USER_PASSWORD environment variables. ADDITIONAL_USER_NAMES is a comma separated list. ADDITIONAL_USER_PASSWORD is a single password used for each additional admin user. If ADDITIONAL_USER_PASSWORD is not specified, the additional users will be created with an unusable password, which is sufficient if only using certificates or tokens to authenticate. However, a password is required to access the Sensor Configuration Portal.

Callback URL Authentication

Certificate and token authentication are supported for authenticating against the server pointed to by the callback URL. Callback SSL verification can be enabled or disabled using CALLBACK_SSL_VERIFICATION in the environment file.

Token

A simple form of token authentication is supported for the callback URL. The sensor will send the user's (user who created the schedule) token in the authorization header ("Token " + token) when posting results to callback URL. The server can then verify the token against what it originally sent to the sensor when creating the schedule. This method of authentication for the callback URL is enabled by default. To verify it is enabled, set CALLBACK_AUTHENTICATION to TOKEN in the environment file (this will be enabled if CALLBACK_AUTHENTICATION set to anything other than CERT). PATH_TO_VERIFY_CERT, in the environment file, can used to set a CA certificate to verify the callback URL server SSL certificate. If this is unset and CALLBACK_SSL_VERIFICATION is set to true, standard trusted CAs will be used.

Certificate

Certificate authentication (mutual TLS) is supported for callback URL authentication. The following settings in the environment file are used to configure certificate authentication for the callback URL.

  • CALLBACK_AUTHENTICATION - set to CERT.
  • PATH_TO_CLIENT_CERT - client certificate used to authenticate against the callback URL server.
  • PATH_TO_VERIFY_CERT - CA certificate to verify the callback URL server SSL certificate. If this is unset and CALLBACK_SSL_VERIFICATION is set to true, standard trusted CAs will be used.

Set PATH_TO_CLIENT_CERT and PATH_TO_VERIFY_CERT relative to configs/certs. Depending on the configuration of the callback URL server, the scos-sensor server certificate could be used as a client certificate (if created with clientAuth extended key usage) by setting PATH_TO_CLIENT_CERT to the same value as SSL_CERT_PATH if the private key is bundled with the certificate. Also the CA used to verify the scos-sensor client certificate(s) could potentially be used to verify the callback URL server certificate by setting PATH_TO_VERIFY_CERT to the same file as used for SSL_CA_PATH. This would require the callback URL server certificate to be issued by the same CA as the scos-sensor client certficate(s) or have the callback URL server's CA cert bundled with the scos-sensor client CA cert. Make sure to consider the security implications of these configurations and settings, especially using the same files for multiple settings.

Clone this wiki locally