Improve README
Change-Id: Ie0f91abf5d45c58641b45dc576e8670c3ffa95df
This commit is contained in:
Peter Matulis
parent
88de3b8d8f
commit
0288884157
200
src/README.md
200
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/<keystone-other-hostname>@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 <username>
|
||||
```
|
||||
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=<projectID>
|
||||
export OS_PROJECT_NAME=<kerberos_domain> # i.e k8s
|
||||
export OS_PROJECT_DOMAIN_ID=<domainID>
|
||||
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/<keystone-other-hostname>@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 <username>
|
||||
|
||||
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=<projectID>
|
||||
export OS_PROJECT_NAME=<kerberos_domain> # i.e k8s
|
||||
export OS_PROJECT_DOMAIN_ID=<domainID>
|
||||
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/).
|
||||
Please report bugs on [Launchpad][lp-bugs-charm-keystone-kerberos].
|
||||
|
||||
For general charm questions refer to the [OpenStack Charm Guide][cg].
|
||||
|
||||
<!-- LINKS -->
|
||||
|
||||
[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
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user