aboutsummaryrefslogtreecommitdiffstats
path: root/keystone-moon/doc/source/configure_tokenless_x509.rst
diff options
context:
space:
mode:
Diffstat (limited to 'keystone-moon/doc/source/configure_tokenless_x509.rst')
-rw-r--r--keystone-moon/doc/source/configure_tokenless_x509.rst328
1 files changed, 328 insertions, 0 deletions
diff --git a/keystone-moon/doc/source/configure_tokenless_x509.rst b/keystone-moon/doc/source/configure_tokenless_x509.rst
new file mode 100644
index 00000000..40b9fd20
--- /dev/null
+++ b/keystone-moon/doc/source/configure_tokenless_x509.rst
@@ -0,0 +1,328 @@
+..
+ Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ use this file except in compliance with the License. You may obtain a copy
+ of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ License for the specific language governing permissions and limitations
+ under the License.
+
+================================================
+Configuring Keystone for Tokenless Authorization
+================================================
+
+.. NOTE::
+
+ This feature is experimental and unsupported in Liberty.
+
+-----------
+Definitions
+-----------
+
+* `X.509 Tokenless Authorization`: Provides a means to authorize client
+ operations within Keystone by using an X.509 SSL client certificate
+ without having to issue a token. For details, please refer to the specs
+ `Tokenless Authorization with X.509 Client SSL Certificate`_
+
+.. _`Tokenless Authorization with X.509 Client SSL Certificate`: http://specs.openstack.org/openstack/keystone-specs/specs/liberty/keystone-tokenless-authz-with-x509-ssl-client-cert.html
+
+Prerequisites
+-------------
+
+Keystone must be running in a web container with https enabled; tests have
+been done with Apache/2.4.7 running on Ubuntu 14.04 . Please refer to
+`running-keystone-in-httpd`_ and `apache-certificate-and-key-installation`_
+as references for this setup.
+
+.. _`running-keystone-in-httpd`: http://docs.openstack.org/developer/keystone/apache-httpd.html
+.. _`apache-certificate-and-key-installation`: https://www.digitalocean.com/community/tutorials/how-to-create-a-ssl-certificate-on-apache-for-ubuntu-14-04
+
+--------------------
+Apache Configuration
+--------------------
+
+To enable X.509 tokenless authorization, SSL has to be enabled and configured
+in the Apache virtual host file. The Client authentication attribute
+``SSLVerifyClient`` should be set as ``optional`` to allow other token
+authentication methods and attribute ``SSLOptions`` needs to set as
+``+StdEnvVars`` to allow certificate attributes to be passed. The following
+is the sample virtual host file used for the testing.
+
+.. code-block:: ini
+
+ <VirtualHost *:443>
+ WSGIScriptAlias / /var/www/cgi-bin/keystone/main
+ ErrorLog /var/log/apache2/keystone.log
+ LogLevel debug
+ CustomLog /var/log/apache2/access.log combined
+ SSLEngine on
+ SSLCertificateFile /etc/apache2/ssl/apache.cer
+ SSLCertificateKeyFile /etc/apache2/ssl/apache.key
+ SSLCACertificatePath /etc/apache2/capath
+ SSLOptions +StdEnvVars
+ SSLVerifyClient optional
+ </VirtualHost>
+
+----------------------
+Keystone Configuration
+----------------------
+
+The following options can be defined in `keystone.conf`:
+
+* ``trusted_issuer`` - The multi-str list of trusted issuers to further
+ filter the certificates that are allowed to participate in the X.509
+ tokenless authorization. If the option is absent then no certificates
+ will be allowed. The naming format for the attributes of a Distinguished
+ Name(DN) must be separated by a comma and contain no spaces; however
+ spaces are allowed for the value of an attribute, like 'L=San Jose' in
+ the example below. This configuration option may be repeated for multiple
+ values. Please look at the sample below.
+* ``protocol`` - The protocol name for the X.509 tokenless authorization
+ along with the option `issuer_attribute` below can look up its
+ corresponding mapping. It defaults to ``x509``.
+* ``issuer_attribute`` - The issuer attribute that is served as an IdP ID for
+ the X.509 tokenless authorization along with the protocol to look up its
+ corresponding mapping. It is the environment variable in the WSGI
+ enviornment that references to the Issuer of the client certificate. It
+ defaults to ``SSL_CLIENT_I_DN``.
+
+This is a sample configuration for two `trusted_issuer` and a `protocol` set
+to ``x509``.
+
+.. code-block:: ini
+
+ [tokenless_auth]
+ trusted_issuer = emailAddress=mary@abc.com,CN=mary,OU=eng,O=abc,L=San Jose,ST=California,C=US
+ trusted_issuer = emailAddress=john@openstack.com,CN=john,OU=keystone,O=openstack,L=Sunnyvale,ST=California,C=US
+ protocol = x509
+
+-------------
+Setup Mapping
+-------------
+
+Like federation, X.509 tokenless authorization also utilizes the mapping
+mechanism to formulate an identity. The identity provider must correspond
+to the issuer of the X.509 SSL client certificate. The protocol for the
+given identity is ``x509`` by default, but can be configurable.
+
+Create an Identity Provider(IdP)
+--------------------------------
+
+In order to create an IdP, the issuer DN in the client certificate needs
+to be provided. The following sample is what a generic issuer DN looks
+like in a certificate.
+
+.. code-block:: ini
+
+ E=john@openstack.com
+ CN=john
+ OU=keystone
+ O=openstack
+ L=Sunnyvale
+ S=California
+ C=US
+
+The issuer DN should be constructed as a string that contains no spaces
+and have the right order seperated by commas like the example below.
+Please be aware that ``emailAddress`` and ``ST`` should be used instead
+of ``E`` and ``S`` that are shown in the above example. The following is
+the sample Python code used to create the IdP ID.
+
+.. code-block:: python
+
+ import hashlib
+ issuer_dn = 'emailAddress=john@openstack.com,CN=john,OU=keystone,
+ O=openstack,L=Sunnyvale,ST=California,C=US'
+ hashed_idp = hashlib.sha256(issuer_dn)
+ idp_id = hashed_idp.hexdigest()
+ print(idp_id)
+
+The output of the above Python code will be the IdP ID and the following
+sample curl command should be sent to keystone to create an IdP with the
+newly generated IdP ID.
+
+.. code-block:: bash
+
+ curl -k -s -X PUT -H "X-Auth-Token: <TOKEN>" \
+ -H "Content-Type: application/json" \
+ -d '{"identity_provider": {"description": "Stores keystone IDP identities.","enabled": true}}' \
+ https://<HOSTNAME>:<PORT>/v3/OS-FEDERATION/identity_providers/<IdP ID>
+
+Create a Map
+------------
+
+A mapping needs to be created to map the ``Subject DN`` in the client
+certificate as a user to yield a valid local user if the user's ``type``
+defined as ``local`` in the mapping. For example, the client certificate
+has ``Subject DN`` as ``CN=alex,OU=eng,O=nice-network,L=Sunnyvale,
+ST=California,C=US``, in the following examples, ``user_name`` will be
+mapped to``alex`` and ``domain_name`` will be mapped to ``nice-network``.
+And it has user's ``type`` set to ``local``. If user's ``type`` is not
+defined, it defaults to ``ephemeral``.
+
+Please refer to `mod_ssl`_ for the detailed mapping attributes.
+
+.. _`mod_ssl`: http://httpd.apache.org/docs/current/mod/mod_ssl.html
+
+.. code-block:: javascript
+
+ {
+ "mapping": {
+ "rules": [
+ {
+ "local": [
+ {
+ "user": {
+ "name": "{0}",
+ "domain": {
+ "name": "{1}"
+ },
+ "type": "local"
+ }
+ }
+ ],
+ "remote": [
+ {
+ "type": "SSL_CLIENT_S_DN_CN"
+ },
+ {
+ "type": "SSL_CLIENT_S_DN_O"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+When user's ``type`` is not defined or set to ``ephemeral``, the mapped user
+does not have to be a valid local user but the mapping must yield at least
+one valid local group. For example:
+
+.. code-block:: javascript
+
+ {
+ "mapping": {
+ "rules": [
+ {
+ "local": [
+ {
+ "user": {
+ "name": "{0}",
+ "type": "ephemeral"
+ }
+ },
+ {
+ "group": {
+ "id": "12345678"
+ }
+ }
+ ],
+ "remote": [
+ {
+ "type": "SSL_CLIENT_S_DN_CN"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+The following sample curl command should be sent to keystone to create a
+mapping with the provided mapping ID. The mapping ID is user designed and
+it can be any string as opposed to IdP ID.
+
+.. code-block:: bash
+
+ curl -k -s -H "X-Auth-Token: <TOKEN>" \
+ -H "Content-Type: application/json" \
+ -d '{"mapping": {"rules": [{"local": [{"user": {"name": "{0}","type": "ephemeral"}},{"group": {"id": "<GROUPID>"}}],"remote": [{"type": "SSL_CLIENT_S_DN_CN"}]}]}}' \
+ -X PUT https://<HOSTNAME>:<PORT>/v3/OS-FEDERATION/mappings/<MAPPING ID>
+
+
+Create a Protocol
+-----------------
+
+The name of the protocol will be the one defined in `keystone.conf` as
+``protocol`` which defaults to ``x509``. The protocol name is user designed
+and it can be any name as opposed to IdP ID.
+
+A protocol name and an IdP ID will uniquely identify a mapping.
+
+The following sample curl command should be sent to keystone to create a
+protocol with the provided protocol name that is defined in `keystone.conf`.
+
+.. code-block:: bash
+
+ curl -k -s -H "X-Auth-Token: <TOKEN>" \
+ -H "Content-Type: application/json" \
+ -d '{"protocol": {"mapping_id": "<MAPPING ID>"}}' \
+ -X PUT https://<HOSTNAME>:<PORT>/v3/OS-FEDERATION/identity_providers/<IdP ID>/protocols/<PROTOCOL NAME>
+
+-------------------------------
+Setup ``auth_token`` middleware
+-------------------------------
+
+In order to use ``auth_token`` middleware as the service client for X.509
+tokenless authorization, both configurable options and scope information
+will need to be setup.
+
+Configurable Options
+--------------------
+
+The following configurable options in ``auth_token`` middleware
+should set to the correct values:
+
+* ``auth_protocol`` - Set to ``https``.
+* ``certfile`` - Set to the full path of the certificate file.
+* ``keyfile`` - Set to the full path of the private key file.
+* ``cafile`` - Set to the full path of the trusted CA certificate file.
+
+Scope Information
+-----------------
+
+The scope information will be passed from the headers with the following
+header attributes to:
+
+* ``X-Project-Id`` - If specified, its the project scope.
+* ``X-Project-Name`` - If specified, its the project scope.
+* ``X-Project-Domain-Id`` - If specified, its the domain of project scope.
+* ``X-Project-Domain-Name`` - If specified, its the domain of project scope.
+* ``X-Domain-Id`` - If specified, its the domain scope.
+* ``X-Domain-Name`` - If specified, its the domain scope.
+
+---------------------
+Test It Out with cURL
+---------------------
+
+Once the above configurations have been setup, the following curl command can
+be used for token validation.
+
+.. code-block:: bash
+
+ curl -v -k -s -X GET --cert /<PATH>/x509client.crt \
+ --key /<PATH>/x509client.key \
+ --cacert /<PATH>/ca.crt \
+ -H "X-Project-Name: <PROJECT-NAME>" \
+ -H "X-Project-Domain-Id: <PROJECT-DOMAIN-ID>" \
+ -H "X-Subject-Token: <TOKEN>" \
+ https://<HOST>:<PORT>/v3/auth/tokens | python -mjson.tool
+
+Details of the Options
+----------------------
+
+* ``--cert`` - The client certificate that will be presented to Keystone.
+ The ``Issuer`` in the certificate along with the defined ``protocol``
+ in `keystone.conf` will uniquely identify the mapping. The ``Subject``
+ in the certificate will be mapped to the valid local user from the
+ identified mapping.
+* ``--key`` - The corresponding client private key.
+* ``--cacert`` - It can be the Apache server certificate or its issuer
+ (signer) certificate.
+* ``X-Project-Name`` - The project scope needs to be passed in the header.
+* ``X-Project-Domain-Id`` - Its the domain of project scope.
+* ``X-Subject-Token`` - The token to be validated.
+