diff options
Diffstat (limited to 'keystone-moon/doc/source/configure_tokenless_x509.rst')
| -rw-r--r-- | keystone-moon/doc/source/configure_tokenless_x509.rst | 328 |
1 files changed, 0 insertions, 328 deletions
diff --git a/keystone-moon/doc/source/configure_tokenless_x509.rst b/keystone-moon/doc/source/configure_tokenless_x509.rst deleted file mode 100644 index 614b1179..00000000 --- a/keystone-moon/doc/source/configure_tokenless_x509.rst +++ /dev/null @@ -1,328 +0,0 @@ -.. - 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 - environment 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 separated 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. - |