Rationalise README with CDG
The security compliance and token support sections have recently been moved into the CDG. Minor improvements. Change-Id: Iee1f6acde01ef3e94f2d96df6eb419df917d08c7
This commit is contained in:
parent
0dd1557f95
commit
ac92271341
161
README.md
161
README.md
|
@ -140,14 +140,14 @@ configuration:
|
|||
shared-db: internal-space
|
||||
```
|
||||
|
||||
NOTE: Spaces must be configured in the underlying provider prior to attempting
|
||||
to use them (i.e. see [MAAS spaces][ms]).
|
||||
> **Note**: Spaces must be configured in the underlying provider prior to
|
||||
attempting to use them (see [MAAS spaces][maas-docs-spaces]).
|
||||
|
||||
NOTE: Existing deployments using `os\-\*-network` configuration options will
|
||||
continue to function; these options are preferred over any network space
|
||||
binding provided if set.
|
||||
> **Note**: Existing deployments using `os\-\*-network` configuration options
|
||||
will continue to function; these options are preferred over any network space
|
||||
binding provided if set.
|
||||
|
||||
## Policy Overrides
|
||||
## Policy overrides
|
||||
|
||||
Policy overrides is an advanced feature that allows an operator to override the
|
||||
default policy of an OpenStack service. The policies that the service supports,
|
||||
|
@ -167,7 +167,7 @@ Here are the essential commands (filenames are arbitrary):
|
|||
juju attach-resource keystone policyd-override=overrides.zip
|
||||
juju config keystone use-policyd-override=true
|
||||
|
||||
See appendix [Policy Overrides][cdg-appendix-n] in the [OpenStack Charms
|
||||
See [Policy overrides][cdg-policy-overrides] in the [OpenStack Charms
|
||||
Deployment Guide][cdg] for a thorough treatment of this feature.
|
||||
|
||||
## Relations
|
||||
|
@ -228,141 +228,17 @@ developers:
|
|||
|
||||
* `nrpe-external-master`: Used to generate Nagios checks.
|
||||
|
||||
## Security Compliance config option "password-security-compliance"
|
||||
## Further resources
|
||||
|
||||
The `password-security-compliance` configuration option sets the
|
||||
`[security_compliance]` section of Keystone's configuration file.
|
||||
The below topics are covered in the [OpenStack Charms Deployment Guide][cdg].
|
||||
|
||||
The configuration option is a YAML dictionary, that is one level deep, with the
|
||||
following keys (and value formats).
|
||||
* [Security compliance][cdg-security-compliance]: Shows how to use the
|
||||
`password-security-compliance` charm option to set Keystone's security
|
||||
compliance configuration.
|
||||
|
||||
```yaml
|
||||
lockout_failure_attempts: <int>
|
||||
lockout_duration: <int>
|
||||
disable_user_account_days_inactive: <int>
|
||||
change_password_upon_first_use: <boolean>
|
||||
password_expires_days: <int>
|
||||
password_regex: <string>
|
||||
password_regex_description: <string>
|
||||
unique_last_password_count: <int>
|
||||
minimum_password_age: <int>
|
||||
```
|
||||
|
||||
It can be set by placing the keys and values in a file and then using the Juju
|
||||
command:
|
||||
|
||||
juju config keystone --file path/to/config.yaml
|
||||
|
||||
Note that, in this case, the `config.yaml` file requires the YAML key
|
||||
`password-security-compliance:` with the desired config keys and values on the
|
||||
following lines, indented for a dictionary.
|
||||
|
||||
> **Note**: Please ensure that the page [Security compliance and PCI-DSS][SCPD]
|
||||
is consulted before setting these options.
|
||||
|
||||
The charm will protect service accounts (accounts requested by other units that
|
||||
are in the service domain) against being forced to change their password.
|
||||
Operators should also ensure that any other accounts are protected as per the
|
||||
above referenced note.
|
||||
|
||||
If the config value cannot be parsed as YAML and/or the options are not
|
||||
able to be parsed as their indicated types then the charm will enter a blocked
|
||||
state until the config value is changed.
|
||||
|
||||
## Token Support
|
||||
|
||||
As the keystone charm supports multiple releases of the OpenStack software, it
|
||||
also supports two Keystone token systems: UUID and Fernet. The capabilities are:
|
||||
|
||||
- pre 'ocata': UUID tokens only.
|
||||
- ocata and pike: UUID or Fernet tokens, configured via the 'token-provider'
|
||||
configuration parameter.
|
||||
- rocky and later: Fernet tokens only.
|
||||
|
||||
Fernet tokens were added to OpenStack to solve the problem of Keystone being
|
||||
required to persist tokens to a common database (cluster) like UUID tokens,
|
||||
and solve the problem of size for PKI or PKIZ tokens.
|
||||
|
||||
For further information, please see [Fernet - Frequently Asked
|
||||
Questions](https://docs.openstack.org/keystone/pike/admin/identity-fernet-token-faq.html).
|
||||
|
||||
### Theory of Operation
|
||||
|
||||
Fernet keys are used to generate tokens; they are generated by Keystone
|
||||
and have an expiration date. The key repository is a directory, and each
|
||||
key is an integer number, with the highest number being the primary key. Key
|
||||
'0' is the staged key, that will be the next primary. Other keys are secondary
|
||||
keys.
|
||||
|
||||
New tokens are only ever generated from the primary key, whilst the secondary
|
||||
keys are used to validate existing tokens. The staging key is not used to
|
||||
generate tokens but can be used to validate tokens as the staging key might be
|
||||
the new primary key on the master due to a rotation and the keys have not yet
|
||||
been synchronised across all the units.
|
||||
|
||||
Fernet keys need to be rotated at periodic intervals, and the keys need to be
|
||||
synchronised to each of the other keystone units. Keys should only be rotated
|
||||
on the master keystone unit and must be synchronised *before* they are rotated
|
||||
again. *Over rotation* occurs if a unit rotates its keys such that there is
|
||||
no suitable decoding key on another unit that can decode a token that has been
|
||||
generated on the master. This happens if two key rotations are done on the
|
||||
master before a synchronisation has been successfully performed. This should
|
||||
be avoided. Over rotations can also cause validation keys to be removed
|
||||
*before* a token's expiration which would result in failed validations.
|
||||
|
||||
There are 3 parts to the **Key Rotation Strategy**:
|
||||
|
||||
1. The rotation frequency
|
||||
2. The token lifespan
|
||||
3. The number of active keys
|
||||
|
||||
There needs to be at least 3 keys as a minimum. The actual number of keys is
|
||||
determined by the *token lifespan* and the *rotation frequency*. The
|
||||
*max_active_keys* must be one greater than the *token lifespan* / *rotation
|
||||
frequency*
|
||||
|
||||
To quote from the [FAQ](https://docs.openstack.org/keystone/queens/admin/identity-fernet-token-faq.html):
|
||||
|
||||
The number of max_active_keys for a deployment can be determined by
|
||||
dividing the token lifetime, in hours, by the frequency of rotation in
|
||||
hours and adding two. Better illustrated as:
|
||||
|
||||
### Configuring Key Lifetime
|
||||
|
||||
In the keystone charm, the _rotation frequency_ is calculated
|
||||
automatically from the `token-expiration` and the `fernet-max-active-keys`
|
||||
configuration parameters. For example, with an expiration of 24 hours and
|
||||
6 active keys, the rotation frequency is calculated as:
|
||||
|
||||
```python
|
||||
token_expiration = 24 # actually 3600, as it's in seconds
|
||||
max_active_keys = 6
|
||||
rotation_frequency = token_expiration / (max_active_keys - 2)
|
||||
```
|
||||
|
||||
Thus, the `fernet-max-active-keys` can never be less than 3 (which is
|
||||
enforced in the charm), which would make the rotation frequency the *same*
|
||||
as the token expiration time.
|
||||
|
||||
NOTE: To increase the rotation frequency, _either_ increase
|
||||
`fernet-max-active-keys` or reduce `token-expiration`, and, to decrease
|
||||
rotation frequency, do the opposite.
|
||||
|
||||
NOTE: If the configuration parameters are used to significantly reduce the
|
||||
key lifetime, then it is possible to over-rotate the verification keys
|
||||
such that services will hold tokens that cannot be verified but haven't
|
||||
yet expired. This should be avoided by only making small changes and
|
||||
verifying that current tokens will still be able to be verified. In
|
||||
particular, `fernet-max-active-keys` affects the rotation time.
|
||||
|
||||
### Upgrades
|
||||
|
||||
When an older keystone charm is upgraded to this version, NO change will
|
||||
occur to the token system. That is, an ocata system will continue to use
|
||||
UUID tokens. In order to change the token system to Fernet, change the
|
||||
`token-provider` configuration item to `fernet`. This will switch the
|
||||
token system over. There may be a small outage in the _control plane_,
|
||||
but the running instances will be unaffected.
|
||||
* [Token support][cdg-token-support]: Provides a background of Keystone keys
|
||||
and tokens. It explains key rotation, and how to use the
|
||||
`fernet-max-active-keys` and `token-expiration` charm options.
|
||||
|
||||
# Bugs
|
||||
|
||||
|
@ -376,9 +252,8 @@ For general charm questions refer to the [OpenStack Charm Guide][cg].
|
|||
[vault-charm]: https://jaas.ai/vault
|
||||
[cg]: https://docs.openstack.org/charm-guide
|
||||
[cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide
|
||||
[cdg-appendix-n]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-policy-overrides.html
|
||||
[cdg-policy-overrides]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-policy-overrides.html
|
||||
[lp-bugs-charm-keystone]: https://bugs.launchpad.net/charm-keystone/+filebug
|
||||
[SCPD]: https://docs.openstack.org/keystone/latest/admin/configuration.html#security-compliance-and-pci-dss
|
||||
[cdg-ha-apps]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-ha.html#ha-applications
|
||||
[upstream-keystone]: https://docs.openstack.org/keystone/latest/
|
||||
[juju-docs-config-apps]: https://juju.is/docs/configuring-applications
|
||||
|
@ -386,4 +261,6 @@ For general charm questions refer to the [OpenStack Charm Guide][cg].
|
|||
[juju-docs-actions]: https://jaas.ai/docs/actions
|
||||
[percona-cluster-charm]: https://jaas.ai/percona-cluster
|
||||
[mysql-innodb-cluster-charm]: https://jaas.ai/mysql-innodb-cluster
|
||||
[ms]: https://maas.io/docs/concepts-and-terms#heading--spaces
|
||||
[maas-docs-spaces]: https://maas.io/docs/concepts-and-terms#heading--spaces
|
||||
[cdg-token-support]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/keystone.html#token-support
|
||||
[cdg-security-compliance]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/keystone.html#security-compliance
|
||||
|
|
Loading…
Reference in New Issue