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
|
[Keystone][keystone-upstream] is the identity service used by OpenStack for
|
||||||
a specific domain with a Kerberos ticket. This provides an additional
|
authentication and high-level authorisation.
|
||||||
security layer. An external Kerberos server is necessary.
|
|
||||||
|
|
||||||
This kerberos subordinate charm is supported on Ubuntu Bionic (18.04 LTS) with
|
The keystone-kerberos subordinate charm allows for per-domain authentication
|
||||||
the Openstack versions Queens and later.
|
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
|
# 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
|
# Configuration
|
||||||
|
|
||||||
In the Kerberos server, a service must be created for the Keystone Principal.
|
This section covers common and/or important configuration options. See file
|
||||||
For example, first find the hostname of the keystone server :
|
`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
|
#### `kerberos-realm`
|
||||||
keystone-server.project.serverstack
|
|
||||||
|
|
||||||
Note 1 : make sure that your keystone server can resolve the Kerberos server
|
The `kerberos-realm` option is used to supply the external Kerberos realm name.
|
||||||
hostname. If if can't, consider adding an entry to /etc/hosts.
|
|
||||||
|
|
||||||
Then, in the Kerberos server, create the host and service (this example is
|
#### `kerberos-server`
|
||||||
based on a FreeIPA Kerberos Server):
|
|
||||||
|
|
||||||
ipa host-add keystone-server.project.serverstack --ip-adress=10.0.0.2
|
The `kerberos-server` option is used to supply the external Kerberos server
|
||||||
ipa service-add HTTP/keystone-server.project.serverstack
|
hostname.
|
||||||
ipa service-add-host HTTP/keystone-server.project.serverstack --hosts=keystone-server.project.serverstack
|
|
||||||
|
|
||||||
Note 2 : If you have multiple keystone servers, you should add each host to
|
#### `kerberos-domain`
|
||||||
the principal with the command
|
|
||||||
|
|
||||||
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:
|
## Deployment
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
juju attach-resource keystone-kerberos/0 keystone_keytab=new_keytab.keytab
|
Let file ``kerberos.yaml`` contain the deployment configuration:
|
||||||
|
|
||||||
# Authentication from a host
|
```yaml
|
||||||
|
keystone-kerberos:
|
||||||
To use the Openstack cli, two steps are required.
|
kerberos-realm: "PROJECT.SERVERSTACK"
|
||||||
1) Retrieve a token for an existing user in the Kerberos/LDAP directory:
|
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
|
Deploy keystone-kerberos with other essential applications:
|
||||||
openstack token issue
|
|
||||||
```
|
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
|
# 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
|
type: string
|
||||||
default: 'k8s'
|
default: 'k8s'
|
||||||
description: |
|
description: |
|
||||||
The Openstack domain against which Kerberos authentication should be
|
The OpenStack domain against which Kerberos authentication should be
|
||||||
used.
|
used.
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user