Federated keystone¶

Enabling Federation¶

To enable Federation, perform the following steps:

1. Run the Identity service under Apache, instead of using keystone-all.

   1. Enable TLS support. Install mod_nss according to your distribution, then apply the following patch and restart HTTPD:

      --- /etc/httpd/conf.d/nss.conf.orig 2012-03-29 12:59:06.319470425 -0400
      +++ /etc/httpd/conf.d/nss.conf      2012-03-29 12:19:38.862721465 -0400
      @@ -17,7 +17,7 @@
      # Note: Configurations that use IPv6 but not IPv4-mapped addresses need two
      #       Listen directives: "Listen [::]:8443" and "Listen 0.0.0.0:443"
      #
      -Listen 8443
      +Listen 443
      
      ##
      ##  SSL Global Context
      @@ -81,7 +81,7 @@
      ## SSL Virtual Host Context
      ##
      
      -<virtualhost _default_:8443="">
      +<virtualhost _default_:443="">
      
      #   General setup for the virtual host
       #DocumentRoot "/etc/httpd/htdocs"
      </virtualhost></virtualhost>
      

   2. If you have a firewall in place, configure it to allow TLS traffic. For example:

      -A INPUT -m state --state NEW -m tcp -p tcp --dport 443 -j ACCEPT
      

      Note this needs to be added before your reject all rule which might be:

      -A INPUT -j REJECT --reject-with icmp-host-prohibited
      

   3. Copy the httpd/wsgi-keystone.conf file to the appropriate location for your Apache server, for example, /etc/httpd/conf.d/wsgi-keystone.conf file.

   4. Create the directory /var/www/cgi-bin/keystone/. Then link the files main and admin to the keystone.py file in this directory.

      For a distribution appropriate place, it should probably be copied to /usr/share/openstack/keystone/httpd/keystone.py.

      Note

      This path is Ubuntu-specific. For other distributions, replace with appropriate path.

   5. If you are running with SELinux enabled ensure that the file has the appropriate SELinux context to access the linked file. For example, if you have the file in /var/www/cgi-bin location, you can do this by running:

      # restorecon /var/www/cgi-bin
      

      Adding it in a different location requires you set up your SELinux policy accordingly.

   6. Make sure you use either the SQL or the memcached driver for tokens, otherwise the tokens will not be shared between the processes of the Apache HTTPD server.

      For SQL, in /etc/keystone/keystone.conf , set:

      [token]
      driver = sql
      

      For memcached, in /etc/keystone/keystone.conf, set:

      [token]
      driver = memcache
      

      In both cases, all servers that are storing tokens need a shared back end. This means either that both point to the same database server, or both point to a common memcached instance.

   7. Install Shibboleth:

      # apt-get install libapache2-mod-shib2
      

      Note

      The apt-get command is Ubuntu specific. For other distributions, replace with appropriate command.

   8. Configure the Identity service virtual host and adjust the config to properly handle SAML2 workflow.

      Add WSGIScriptAlias directive to your vhost configuration:

      WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1
      

   9. Add two <Location> directives to the wsgi-keystone.conf file:

      <Location /Shibboleth.sso>
      SetHandler shib
      </Location>
      
      <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/saml2/auth>
      ShibRequestSetting requireSession 1
      AuthType shibboleth
      ShibRequireAll On
      ShibRequireSession On
      ShibExportAssertion Off
      Require valid-user
      </LocationMatch>
      

      Note

      The option saml2 may be different in your deployment, but do not use a wildcard value. Otherwise every Federated protocol will be handled by Shibboleth.

      The ShibRequireSession rule is invalid in Apache 2.4 or newer and should be dropped in that specific setup.

   10. Enable the Identity service virtual host:

       # a2ensite wsgi-keystone.conf
       

   11. Enable the ssl and shib2 modules:

       # a2enmod ssl
       # a2enmod shib2
       

   12. Restart Apache:

       # service apache2 restart
       

       Note

       The service apache2 restart command is Ubuntu-specific. For other distributions, replace with appropriate command.

2. Configure Apache to use a Federation capable authentication method.

   1. Once you have your Identity service virtual host ready, configure Shibboleth and upload your metadata to the Identity Provider.

      If new certificates are required, they can be easily created by executing:

      $ shib-keygen -y NUMBER_OF_YEARS
      

      The newly created file will be stored under /etc/shibboleth/sp-key.pem

   2. Upload your Service Provider’s metadata file to your Identity Provider.

   3. Configure your Service Provider by editing /etc/shibboleth/shibboleth2.xml.

      For more information, see Shibboleth Service Provider Configuration.

   4. Identity service enforces external authentication when environment variable REMOTE_USER is present so make sure Shibboleth does not set the REMOTE_USER environment variable. To do so, scan through the /etc/shibboleth/shibboleth2.xml configuration file and remove the REMOTE_USER directives.

   5. Examine your attributes map in the /etc/shibboleth/attributes-map.xml file and adjust your requirements if needed. For more information see Shibboleth Attributes.

   6. Restart the Shibboleth daemon:

      # service shibd restart
      # service apache2 restart
      

3. Enable OS-FEDERATION extension:

   1. Add the Federation extension driver to the [federation] section in the keystone.conf file. For example:

      [federation]
      driver = sql
      

   2. Add the saml2 authentication method to the [auth] section in keystone.conf file:

      [auth]
      methods = external,password,token,saml2
      saml2 = keystone.auth.plugins.saml2.Saml2
      

      Note

      The external method should be dropped to avoid any interference with some Apache and Shibboleth SP setups, where a REMOTE_USER environment variable is always set, even as an empty value.

   3. Add the federation_extension middleware to the api_v3 pipeline in the keystone-paste.ini file. For example:

      [pipeline:api_v3]
      pipeline = access_log sizelimit url_normalize token_auth
      admin_token_auth xml_body json_body ec2_extension s3_extension
      federation_extension service_v3
      

   4. Create the Federation extension tables if using the provided SQL back end. For example:

      $ keystone-manage db_sync --extension federation
      

Ideally, to test that the Identity Provider and the Identity service are communicating, navigate to the protected URL and attempt to sign in. If you get a response back from keystone, even if it is a wrong response, indicates the communication.

Performing Federation authentication¶

1. Authenticate externally and generate an unscoped token in Identity service.

   To start Federated authentication a user must access the dedicated URL with Identity Provider’s and Protocol’s identifiers stored within a protected URL. The URL has a format of: /v3/OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth.

   This instance follows a standard SAML2 authentication procedure, that is, the user will be redirected to the Identity Provider’s authentication webpage and be prompted for credentials. After successfully authenticating the user will be redirected to the Service Provider’s endpoint. If using a web browser, a token will be returned in XML format. As an alternative to using a web browser, you can use Enhanced Client or Proxy (ECP), which is available in the keystoneclient in the Identity service API.

   In the returned unscoped token, a list of Identity service groups the user belongs to will be included.

   For example, the following URL would be considered protected by mod_shib and Apache, as such a request made to the URL would be redirected to the Identity Provider, to start the SAML authentication procedure.

   # curl -X GET \
   -D - http://localhost:5000/v3/OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth
   

   Note

   It is assumed that the keystone service is running on port 5000.

2. Determine accessible resources.

   By using the previously returned token, the user can issue requests to the list projects and domains that are accessible.

   • List projects a federated user can access: GET /OS-FEDERATION/projects
   • List domains a federated user can access: GET /OS-FEDERATION/domains

   For example,

   # curl -X GET \
   -H "X-Auth-Token: <unscoped token>" \
   http://localhost:5000/v3/OS-FEDERATION/projects
   

   or

   # curl -X GET \
   -H "X-Auth-Token: <unscoped token>" http://localhost:5000/v3/OS-FEDERATION/domains
   

3. Get a scoped token.

   A federated user may request a scoped token, by using the unscoped token. A project or domain may be specified by either ID or name. An ID is sufficient to uniquely identify a project or domain. For example,

   # curl -X POST \
   -H "Content-Type: application/json" \
   -d '{"auth":{"identity":{"methods":["saml2"],"saml2":{"id":
   "<unscoped_token_id>"}},"scope":{"project":{"domain": {"name":
   "Default"},"name":"service"}}}}' \
   -D - http://localhost:5000/v3/auth/tokens
   

Configuration options¶

Before attempting to federate multiple Identity service deployments, you must setup certain configuration options in the keystone.conf file.

Within the keystone.conf assign values to the [saml] related fields, for example:

[saml]
certfile=/etc/keystone/ssl/certs/ca.pem
keyfile=/etc/keystone/ssl/private/cakey.pem
idp_entity_id=https://keystone.example.com/v3/OS-FEDERATION/saml2/idp
idp_sso_endpoint=https://keystone.example.com/v3/OS-FEDERATION/saml2/sso
idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml

It is recommended that the following Organization configuration options be setup.

idp_organization_name=example_company
idp_organization_display_name=Example Corp.
idp_organization_url=example.com

It is also recommended the following Contact options are set.

idp_contact_company=example_company
idp_contact_name=John
idp_contact_surname=Smith
idp_contact_email=jsmith@example.com
idp_contact_telephone=555-55-5555
idp_contact_type=technical

Generate metadata¶

In order to create a trust between the Identity Provider and the Service Provider, metadata must be exchanged. To create metadata for your Identity service, run the keystone-manage command and pipe the output to a file. For example:

$ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml

Create a region for the Service Provider¶

Create a new region for the service provider, for example, create a new region with an ID of BETA, and URL of https://beta.com/Shibboleth.sso/SAML2/POST. This URL will be used when creating a SAML assertion for BETA, and signed by the current keystone Identity Provider.

$ curl -s -X PUT \
  -H "X-Auth-Token: $OS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"region": {"url": "http://beta.com/Shibboleth.sso/SAML2/POST"}}' \
  http://localhost:5000/v3/regions/BETA | python -mjson.tool

Testing it all out¶

Lastly, if a scoped token and a Service Provider region are presented to keystone, the result will be a full SAML Assertion, signed by the IdP keystone, specifically intended for the Service Provider keystone.

$ curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"auth": {"scope": {"region": {"id": "BETA"}}, "identity": {"token": {"id": "d793d935b9c343f783955cf39ee7dc3c"}, "methods": ["token"]}}}' \
  http://localhost:5000/v3/auth/OS-FEDERATION/saml2

At this point the SAML Assertion can be sent to the Service Provider keystone, and a valid OpenStack token, issued by a Service Provider keystone, will be returned.