x509 Authentication 3.0

This guide will show you how to enable and use the x509 certificates authentication with OpenNebula. The x509 certificates can be used in two different ways in OpenNebula.

The first option that is explained in this guide enables us to use certificates with the CLI. In this case the user will generate a login token with his private key, OpenNebula will validate the certificate and decrypt the token to authenticate the user.

The second option enables us to use certificates with Sunstone and the Public Cloud servers included in OpenNebula. In this case the authentication is leveraged to Apache or any other SSL capable http proxy that has to be configured by the administrator. If this certificate is validated the server will encrypt those credentials using a server certificate and will send the token to OpenNebula.

Requirements

If you want to use the x509 certificates with Sunstone or one of the Public Clouds, you must deploy a SSL capable http proxy on top of them in order to handle the certificate validation.

Considerations & Limitations

The X509 driver uses the certificate DN as user passwords. Certificate DNs are public and can be obtained by anyone. If you want to use this driver you must disable the plain authentication mechanism, that just compares the password stored in the DB with that provided by the user.

:!: Before disabling the plain user/password authentication, make sure you switch the oneadmin account to a valid x509 certificate, as explained in the configuration section.

:!: If the Auth driver is enabled in the oned.conf the default plain authentication method is disabled. The available authentication methods will be the one listed as –authn parameters in the AUTH_MAD section of the OpenNebula configuration file.

The x509 driver will remove any space in the certificate DN. This may cause problems in the unlikely situation that you are using a CA signing certificate subjects that only differ in spaces.

DNs that contain the colon (:) or special character are not supported in this version. See the known issues for more information.

Configuration

OpenNebula Configuration for using x509 with the CLI

The following table summarizes the available options for the x509 driver (/etc/one/auth/x509_auth.conf):

VARIABLE VALUE
:ca__dir Path to the trusted CA directory. It should contain the trusted CA's for the server, each CA certificate shoud be name CA_hash.0

The Auth MAD is not enabled by default, and has to be uncommented in oned.conf. But before that you should follow these steps in order to be able to access OpenNebula using x509:

  • Start OpenNebula configured to use plain text authentication, which is the default method when the Auth MAD is not enabled.
  • Change the oneadmin password to the oneadmin certificate DN.

oneadmin@frontend $ oneuser passwd 0 --x509 --cert /tmp/newcert.pem

  • Stop OpenNebula
  • Configure OpenNebula (oned.conf) to use x509 authentication. More than one authentication method can be defined, make sure that x509 is one of the listed authn arguments so this authentication method is enabled:
AUTH_MAD = [
    executable = "one_auth_mad",
    arguments  = "--authn x509"
]

$ openssl x509 -noout -hash -in cacert.pem
78d0bbd8

$ sudo cp cacert.pem /etc/one/auth/certificates/78d0bbd8.0

  • Create a login for oneadmin using the –x509 option. This token has a default expiration time set to 1 hour, you can change this value using the option –time.

newuser@frontend $ oneuser login newuser --x509 --cert newcert.pem --key newkey.pem
Enter PEM pass phrase:
export ONE_AUTH=/home/cmartin/.one/one_x509

  • Set ONE_AUTH to the x509 login file

newuser@frontend $ export ONE_AUTH=/home/cmartin/.one/one_x509

  • Start OpenNebula

The users that were created using the plain authentication system will not be able to access OpenNebula and should be migrated to the new system

OpenNebula Configuration for using x509 with the Public Cloud Servers and Sunstone

The following table summarizes the available options for the server auth driver (/etc/one/auth/server_auth.conf):

VARIABLE VALUE
:one_cert Path to the certificate used by the OpenNebula Services. Certificates must be in PEM format
:one_key Path to the private key used by the OpenNebula Services

In this configuration guide we assume that oneadmin owns a token to connect to OpenNebula locally using one of the available authentication methods and OpenNebula has been configured in order to use the x509 method with the CLI. You should follow these steps in order to be able to access OpenNebula using x509 through the Public Cloud Servers or Sunstone:

  • Stop OpenNebula
  • Configure OpenNebula (oned.conf) to use server_auth authentication. More than one authentication method can be defined, make sure that server_auth is one of the listed authn arguments so this authentication method is enabled:
AUTH_MAD = [
    executable = "one_auth_mad",
    arguments  = "--authn x509, server"
]
  • Define the server certificates that will sign the user credentials in the /etc/one/auth/server_auth.conf file
  • Enable the x509 authentication in the Servers configuration files.
  • Start OpenNebula

The users that were created using the plain authentication system will not be able to access OpenNebula and should be migrated to the new system

Usage

Add and Remove Trusted CA Certificates

You need to copy all trusted CA certificates to the certificates directory, renaming each of them as <CA_hash>.0. The hash can be obtained with the openssl command:

$ openssl x509 -noout -hash -in cacert.pem
78d0bbd8

$ sudo cp cacert.pem /etc/one/auth/certificates/78d0bbd8.0

To stop trusting a CA, simply remove its certificate from the certificates directory.

This process can be done without restarting OpenNebula, the driver will look for the certificates each time an authentication request is made.

Create New Users

The users requesting a new account have to send their certificate, signed by a trusted CA, to the administrator. The following command will create a new user with username 'newuser', assuming that the user's certificate is saved in the file /tmp/newcert.pem:

oneadmin@frontend $ oneuser create newuser --x509 --cert /tmp/newcert.pem

This command will create a new user whose password contains de subject DN of his certificate. Therefore if the subject DN is known by the administrator the user can be created as follows:

oneadmin@frontend $ oneuser create newuser --x509 "user_subject_DN"

Update Existing Users to x509 & Multiple DN

You can change the authentication method of an existing user to x509 with the following command:

  • Using the user certificate:

oneadmin@frontend $ oneuser passwd <id|name> --x509 --cert /tmp/newcert.pem

  • Using the user certificate subject DN:

oneadmin@frontend $ oneuser passwd <id|name> --x509 "user_subject_DN"

You can also map multiple certificates to the same OpenNebula account. Just add each certificate DN separated with '|' to the password field.

oneadmin@frontend $ oneuser passwd <id|name> --x509 --plain "/DC=es/O=one/CN=user|/DC=us/O=two/CN=user"

User Login

Users must execute the 'oneuser login' command to generate a login token, and export the new ONE_AUTH environment variable. The command requires the OpenNebula username, and the authentication method (–x509 in this case).

newuser@frontend $ oneuser login newuser --x509 --cert newcert.pem --key newkey.pem
Enter PEM pass phrase:
export ONE_AUTH=/home/cmartin/.one/one_x509

newuser@frontend $ export ONE_AUTH=/home/cmartin/.one/one_x509

The generated token has a default expiration time of 1 hour. You can change that with the –time option.

Tuning & Extending

The x509 authentication method is just one of the drivers enabled when the AUTH_MAD executable is uncommented in oned.conf. All drivers are located in /var/lib/one/remotes/auth.