# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.

# This file contains a specification of what feature capabilities each driver
# is able to support. Feature capabilities include what API operations are
# supported, what backend behaviors features can be used and what aspects of
# the driver implementation can be configured. The capabilities can be
# considered to be structured into nested groups, but in this file they have
# been flattened for ease of representation. The section names represent the
# group structure. At the top level there are the following groups defined:
#
# - operation: Public API operations.
# - feature: Features of the token format.
#
# When considering which capabilities should be marked as mandatory, consider
# the following guiding principles.
#
# The 'status' field takes possible values:
#
# - mandatory: Unconditionally required to be implemented.
# - optional: Optional to support, but nice to have.
# - choice(group): At least one of the options within the named group
#                  must be implemented.
# - conditional(cond): Required, if the referenced condition is met.
#
# The value against each 'driver-impl-XXXX' entry refers to the level of the
# implementation of the feature in that driver:
#
# - complete: Fully implemented, expected to work at all times.
# - partial: Implemented, but with caveats about when it will work.
#            For example, some configurations or hardware or guest OS may not
#            support it.
# - missing: Not implemented at all.
#
# In the case of the driver being marked as 'partial', then
# 'driver-notes-XXX' entry should be used to explain the caveats around the
# implementation.
#
# The 'cli' field takes a list of client commands, separated by semicolon.
# These CLi commands are related to that feature.
# Example:
# cli=openstack domain list;openstack domain show <domain>
#
[targets]
# List of driver implementations for which we are going to track the status of
# features. This list only covers drivers that are in tree. Out of tree
# drivers should maintain their own equivalent document, and merge it with this
# when their code merges into core.
driver-impl-uuid=UUID tokens
driver-impl-pki=PKI tokens
driver-impl-pkiz=PKIZ tokens
driver-impl-fernet=Fernet tokens

[operation.create_unscoped_token]
title=Create unscoped token
status=mandatory
notes=All token providers must be capable of issuing tokens without an explicit
  scope of authorization.
cli=openstack --os-username=<username> --os-user-domain-name=<domain>
  --os-password=<password> token issue
driver-impl-uuid=complete
driver-impl-pki=complete
driver-impl-pkiz=complete
driver-impl-fernet=complete

[operation.create_project_scoped_token]
title=Create project-scoped token
status=mandatory
notes=All token providers must be capable of issuing project-scoped tokens.
cli=openstack --os-username=<username> --os-user-domain-name=<domain>
  --os-password=<password> --os-project-name=<project>
  --os-project-domain-name=<domain> token issue
driver-impl-uuid=complete
driver-impl-pki=complete
driver-impl-pkiz=complete
driver-impl-fernet=complete

[operation.create_domain_scoped_token]
title=Create domain-scoped token
status=optional
notes=Domain-scoped tokens are not required for all use cases, and for some use
  cases, projects can be used instead.
cli=openstack --os-username=<username> --os-user-domain-name=<domain>
  --os-password=<password> --os-domain-name=<domain> token issue
driver-impl-uuid=complete
driver-impl-pki=complete
driver-impl-pkiz=complete
driver-impl-fernet=complete

[operation.create_trust_scoped_token]
title=Create trust-scoped token
status=optional
notes=Tokens scoped to a trust convey only the user impersonation and
  project-based authorization attributes included in the delegation.
cli=openstack --os-username=<username> --os-user-domain-name=<domain>
  --os-password=<password> --os-trust-id=<trust> token issue
driver-impl-uuid=complete
driver-impl-pki=complete
driver-impl-pkiz=complete
driver-impl-fernet=complete

[operation.create_token_using_oauth]
title=Create a token given an OAuth access token
status=optional
notes=OAuth access tokens can be exchanged for keystone tokens.
cli=
driver-impl-uuid=complete
driver-impl-pki=complete
driver-impl-pkiz=complete
driver-impl-fernet=complete

[operation.create_token_with_bind]
title=Create a token with a bind attribute
status=optional
notes=Tokens can express a binding to an additional authentication method, such
  as kerberos or x509.
cli=
driver-impl-uuid=complete
driver-impl-pki=complete
driver-impl-pkiz=complete
driver-impl-fernet=missing

[operation.revoke_token]
title=Revoke a token
status=optional
notes=Tokens may be individually revoked, such as when a user logs out of
  Horizon. Under certain circumstances, it's acceptable for more than just a
  single token may be revoked as a result of this operation (such as when the
  revoked token was previously used to create additional tokens).
cli=openstack token revoke
driver-impl-uuid=complete
driver-impl-pki=complete
driver-impl-pkiz=complete
driver-impl-fernet=complete

[feature.online_validation]
title=Online validation
status=mandatory
notes=Keystone must be able to validate the tokens that it issues when
  presented with a token that it previously issued.
cli=
driver-impl-uuid=complete
driver-impl-pki=complete
driver-impl-pkiz=complete
driver-impl-fernet=complete

[feature.offline_validation]
title=Offline validation
status=optional
notes=Services using Keystone for authentication may want to validate tokens
  themselves, rather than calling back to keystone, in order to improve
  performance and scalability.
cli=
driver-impl-uuid=missing
driver-impl-pki=complete
driver-impl-pkiz=complete
driver-impl-fernet=missing

[feature.non_persistent]
title=Non-persistent
status=optional
notes=If a token format does not require persistence (such as to a SQL
  backend), then there is no scalability limit to the number of tokens that
  keystone can issue at once, and there is no need to perform clean up
  operations such as `keystone-manage token_flush`.
cli=
driver-impl-uuid=missing
driver-impl-pki=partial
driver-impl-pkiz=partial
driver-impl-fernet=complete
