diff --git a/src/README.md b/src/README.md index 181b70d..4dbd40f 100644 --- a/src/README.md +++ b/src/README.md @@ -1,105 +1,139 @@ -# keystone-kerberos +# Overview -This subordinate charm provides a way to authenticate in Openstack for -a specific domain with a Kerberos ticket. This provides an additional -security layer. An external Kerberos server is necessary. +[Keystone][keystone-upstream] is the identity service used by OpenStack for +authentication and high-level authorisation. -This kerberos subordinate charm is supported on Ubuntu Bionic (18.04 LTS) with -the Openstack versions Queens and later. +The keystone-kerberos subordinate charm allows for per-domain authentication +via a Kerberos ticket, thereby providing an additional layer of security. It is +used in conjunction with the [keystone][keystone-charm] charm. +An external Kerberos server is a prerequisite. + +> **Note**: The keystone-kerberos charm is supported starting with OpenStack + Queens. + +> **Warning**: This charm is in a preview state and should not be used in + production. See the [OpenStack Charm Guide][cg-preview-charms] for more + information on preview charms. # Usage -Use this charm with the Keystone charm: - - juju deploy keystone - juju deploy openstack-dashboard - juju deploy keystone-kerberos - juju add-relation keystone openstack-dashboard - juju add-relation keystone keystone-kerberos - -In a bundle: - -``` - applications - # ... - keystone-kerberos: - charm: ../../../keystone-kerberos - num_units: 0 - options: - kerberos-realm: "PROJECT.SERVERSTACK" - kerberos-server: "freeipa.project.serverstack" - kerberos-domain: "k8s" - resources: - keystone_keytab: "/home/ubuntu/keystone.keytab" - relations: - # ... - - - keystone - - keystone-kerberos -``` - -# Prerequisites - -To authenticate against Keystone and Kerberos from a host, the following -librairies need to be installed : -- sudo apt install krb5-user python3-openstackclient python3-requests-kerberos - # Configuration -In the Kerberos server, a service must be created for the Keystone Principal. -For example, first find the hostname of the keystone server : +This section covers common and/or important configuration options. See file +`config.yaml` for the full list of options, along with their descriptions and +default values. See the [Juju documentation][juju-docs-config-apps] for details +on configuring applications. - ubuntu@keystone-server$ hostname -f - keystone-server.project.serverstack +#### `kerberos-realm` -Note 1 : make sure that your keystone server can resolve the Kerberos server -hostname. If if can't, consider adding an entry to /etc/hosts. +The `kerberos-realm` option is used to supply the external Kerberos realm name. -Then, in the Kerberos server, create the host and service (this example is -based on a FreeIPA Kerberos Server): +#### `kerberos-server` - ipa host-add keystone-server.project.serverstack --ip-adress=10.0.0.2 - ipa service-add HTTP/keystone-server.project.serverstack - ipa service-add-host HTTP/keystone-server.project.serverstack --hosts=keystone-server.project.serverstack +The `kerberos-server` option is used to supply the external Kerberos server +hostname. -Note 2 : If you have multiple keystone servers, you should add each host to -the principal with the command +#### `kerberos-domain` - ipa host-add-principal keystone-server HTTP/@PROJECT.SERVERSTACK +The `kerberos-domain` option is the OpenStack domain against which Kerberos +authentication should be used. -Retrieve the keytab associated with this service: - - ipa-getkeytab -p HTTP/keystone-server.project.serverstack -k keystone.keytab - -This is the keytab needed in the resources of the keystone-kerberos charm. If -you retrieved it post-deploy, you can attach it with a command to keystone: +## Deployment - juju attach-resource keystone-kerberos/0 keystone_keytab=new_keytab.keytab +Let file ``kerberos.yaml`` contain the deployment configuration: -# Authentication from a host - -To use the Openstack cli, two steps are required. -1) Retrieve a token for an existing user in the Kerberos/LDAP directory: +```yaml + keystone-kerberos: + kerberos-realm: "PROJECT.SERVERSTACK" + kerberos-server: "freeipa.project.serverstack" + kerberos-domain: "k8s" ``` - kinit -``` -2) Source the openstack rc file with the correct information: -``` - cat k8s-user.rc - export OS_AUTH_URL=http://kerberos-server.project.serverstack:5000/krb/v3 - export OS_PROJECT_ID= - export OS_PROJECT_NAME= # i.e k8s - export OS_PROJECT_DOMAIN_ID= - export OS_REGION_NAME="RegionOne" - export OS_INTERFACE=public - export OS_IDENTITY_API_VERSION=3 - export OS_AUTH_TYPE=v3kerberos - source k8s-user.rc - openstack token issue -``` +Deploy keystone-kerberos with other essential applications: + + juju deploy keystone + juju deploy openstack-dashboard + juju deploy --config kerberos.yaml --resource=/home/ubuntu/keystone.keytab keystone-kerberos + juju add-relation keystone openstack-dashboard + juju add-relation keystone keystone-kerberos + +See the next section for retrieving the keytab file. It can also be added to +the application post-deploy: + + juju attach-resource keystone-kerberos keystone_keytab=keystone.keytab + +## Kerberos pre-requisites - the Keystone service keytab + +In an external Kerberos server, a service must be created for the Keystone +Principal. + +1. First determine the FQDN of the Keystone server. For example: + + keystone-server.project.serverstack + + Ensure that the Keystone server can resolve the Kerberos server hostname. If + it can't, consider adding an entry to `/etc/hosts`. + +1. In the Kerberos server, create the host and service. This example is based + on a FreeIPA Kerberos server: + + ipa host-add keystone-server.project.serverstack --ip-adress=10.0.0.2 + ipa service-add HTTP/keystone-server.project.serverstack + ipa service-add-host HTTP/keystone-server.project.serverstack --hosts=keystone-server.project.serverstack + + If you have multiple Keystone servers, you should add each host to the + principal: + + ipa host-add-principal keystone-server HTTP/@PROJECT.SERVERSTACK + +1. Retrieve the keytab associated with this service: + + ipa-getkeytab -p HTTP/keystone-server.project.serverstack -k keystone.keytab + +## Authenticate from a host + +The below steps show how to authenticate from a host using the `openstack` CLI +client. + +1. Ensure that the following software is installed on the host: + + sudo apt install krb5-user python3-openstackclient python3-requests-kerberos + +1. Retrieve a token for an existing user in the Kerberos/LDAP directory. + + kinit + +1. Source the OpenStack rc file. + + source k8s-user.rc + + Where the contents of `k8s-user.rc` is: + + export OS_AUTH_URL=http://kerberos-server.project.serverstack:5000/krb/v3 + export OS_PROJECT_ID= + export OS_PROJECT_NAME= # i.e k8s + export OS_PROJECT_DOMAIN_ID= + export OS_REGION_NAME="RegionOne" + export OS_INTERFACE=public + export OS_IDENTITY_API_VERSION=3 + export OS_AUTH_TYPE=v3kerberos + +1. Test the client + + openstack token issue # Bugs -Please report bugs on [Launchpad](link missing). -For general questions please refer to the OpenStack [Charm Guide](https://docs.openstack.org/charm-guide/latest/). \ No newline at end of file +Please report bugs on [Launchpad][lp-bugs-charm-keystone-kerberos]. + +For general charm questions refer to the [OpenStack Charm Guide][cg]. + + + +[cg]: https://docs.openstack.org/charm-guide +[keystone-charm]: https://jaas.ai/keystone +[keystone-upstream]: https://docs.openstack.org/keystone/latest/ +[cg-preview-charms]: https://docs.openstack.org/charm-guide/latest/openstack-charms.html#tech-preview-charms-beta +[lp-bugs-charm-keystone-kerberos]: https://bugs.launchpad.net/charm-keystone-kerberos/+filebug +[juju-docs-config-apps]: https://juju.is/docs/configuring-applications diff --git a/src/config.yaml b/src/config.yaml index 8bac044..7298980 100644 --- a/src/config.yaml +++ b/src/config.yaml @@ -21,5 +21,5 @@ options: type: string default: 'k8s' description: | - The Openstack domain against which Kerberos authentication should be + The OpenStack domain against which Kerberos authentication should be used.