keystone/doc/source/ssl.rst

Instructions for Keystone x.509 client authentication

Purpose

Allows the Keystone middleware to authenticate itself with the Keystone server via an x.509 client certificate. Both Service API and Admin API may be secured with this feature.

Certificates

The following types of certificates are required. A set of certficates is provided in the examples/ssl directory with the Keystone distribution for testing. Here is the description of each of them and their purpose:

1. ca.pem : Certificate Authority chain to validate against.
2. keystone.pem : Public certificate for Keystone server.
3. middleware-key.pem: Public and private certificate for Keystone middleware.
4. cakey.pem : Private key for the CA.
5. keystonekey.pem : Private key for the Keystone server.

Note that you may choose whatever names you want for these certificates, or combine the public/private keys in the same file if you wish. These certificates are just provided as an example.

Keystone server

By default, the Keystone server does not use SSL. To enable SSL with client authentication, modify the etc/keystone.conf file accordingly:

1. To enable SSL for Service API:

   service_ssl = True

2. To enable SSL for Admin API:

   admin_ssl = True

3. To enable SSL client authentication:

   cert_required = True

4. Set the location of the Keystone certificate file (example):

   certfile = /etc/keystone/ca/certs/keystone.pem

5. Set the location of the Keystone private file (example):

   keyfile = /etc/keystone/ca/private/keystonekey.pem

6. Set the location of the CA chain:

   ca_certs = /etc/keystone/ca/certs/ca.pem

Middleware

Add the following to your middleware configuration to support x.509 client authentication. If cert_required is set to False on the keystone server, the certfile and keyfile parameters in steps 3) and 4) may be commented out.

1. Specify 'https' as the auth_protocol:

   auth_protocol = https

2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured for SSL: auth_uri = https://localhost:5000/

3. Set the location of the middleware certificate file (example):

   certfile = /etc/keystone/ca/certs/middleware-key.pem

4. Set the location of the Keystone private file (example):

   keyfile = /etc/keystone/ca/certs/middleware-key.pem

For an example, take a look at the 'echo.ini' middleware configuration for the 'echo' example service in the examples/echo directory.

Testing

You can test out how it works by using the 'echo' example service in the examples/echo directory and the certficates included in the examples/ssl directory. Invoke the echo_client.py with the path to the client certificate:

python echo_client.py -s <path to client certificate>