Reasonable assumptions concerning domain references

[Dolph Mathews]

There are 3 primary places where client can be configured to reference domains. The actual parameter names vary based on the configuration interface (a function's arguments, the env, CLI arguments, etc), but I'll use environment variables here for the sake of general familiarity:

1. OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME: Used for specifying the domain which owns the authenticating user.

2. OS_PROJECT_DOMAIN_ID and OS_PROJECT_DOMAIN_NAME: Used for specifying the domain which owns the desired project scope.

3. OS_DOMAIN_ID and OS_DOMAIN_NAME: Used for specifying the desired domain scope.

On the service side, a "default domain" is created which, by default, looks like:

  id="default"

  name="Default"

The default domain is exclusively used on the service-side for scoping v2 operations, which are not domain-aware, in the broader multi-domain namespace exposed by v3. The default domain's ID is mutable via configuration (CONF.identity.default_domain_id) and the domain name is mutable via the API (PATCH /v3/domains/default, for example). Generally, deployers should not have any reason to change the default domain ID from it's default value of "default".

Both (1) and (2) refer to domains that provide context to other configuration options. In single domain deployments, or deployments wherein most users and projects exist in the "default domain", it would benefit the user experience to assume that the user's and project exist in the default domain. Specifically, this means that users have fewer (if any) additional configuration options to set when migrating from v2 to v3, easing adoption of v3 overall. Deployments that opt into more complex multi-domain arrangement are thus opting into consuming more complex configuration options on the client side (they must specify their non-default domains explicitly).

On (3), these values should always default to null values, and no assumptions should ever be made about their values. If a non-null default were to be set, then that means that the client should always try to obtain a domain-scoped token which is almost never the intended behavior.

There are three approaches to implementing this behavior. Two of them are obvious at a high level, but easily fragile.

If OS_USER_DOMAIN_ID defaults to "default" to match the default CONF.identity.default_domain_id value, then whenever the user sets a OS_USER_DOMAIN_NAME, the OS_USER_DOMAIN_ID *must* be ignored in favor of using the specified domain name. This is a potentially unreliable behavior, as domain IDs are immutable and are thus more preferable as reliable references.

If OS_USER_DOMAIN_NAME defaults to "Default" to match the default domain name value, then whenever the user sets a OS_USER_DOMAIN_ID, the OS_USER_DOMAIN_NAME *must* be ignored in favor of using the specified domain ID. This is a potentially unreliable behavior, as assuming that the default domain still has a default domain name of "Default" is fragile considering that it's mutable through the regular HTTP API (a deployer will inevitably change it, thus breaking the client's default behavior). This approach is fragile.

The third option is a combination of the above two approaches, and must happen at the "last minute" before requests are issued to keystone (after all possible sources of configuration have been handled). That is, both OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME default to null values on the surface. When an actual HTTP request is built, normal configuration precedence takes place (for example, in a CLI client):

1) If an --os-user-domain-id is specified, then that is used, ignoring --os-user-domain-name, OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME. This is the most specific, reliable configuration option available. A warning could be issued about the ignored values being discarded to communicate this sequence of precedence.

2) If an --os-user-domain-name is specified, then that is used, ignoring OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME.

3) If an OS_USER_DOMAIN_ID, then that is used, ignoring OS_USER_DOMAIN_NAME.

4) If an OS_USER_DOMAIN_NAME, then that is used.

5) Else, assume the domain id="default".

Everything above referencing a OS_USER_DOMAIN_ID + OS_USER_DOMAIN_NAME applies equally to OS_PROJECT_DOMAIN_ID + OS_PROJECT_DOMAIN_NAME.

Note: a domain ID never needs to be specified in the same request as a domain name. Both are absolute references that cannot be confused due to namespace conflicts; the only difference between them is that domain IDs are system-defined + immutable and domain names are user-defined + mutable.

And again, the server should never, ever assume domain IDs anywhere for any reason outside of v2 controllers assuming CONF.identity.default_domain_id as the explicit scope. v3 should never make any assumptions about domains: explicit is better than implicit here.

[Jamie Lennox (jamielennox)]

So at least from the keystoneauth perspective this is what we do. With the addition that to handle the default domain case we have the OS_DEFAULT_DOMAIN_ID/NAME environment variables/flags. This would let people do OS_DEFAULT_DOMAIN_ID=default and have this value used for OS_USER_DOMAIN_ID/NAME and OS_PROJECT_DOMAIN_ID/NAME when one is not set.

Whilst i understand the desire to just set the default domain id to default and leave it, i think the OS_DEFAULT_DOMAIN_ID works well because if you are in another domain you can set DEFAULT_DOMAIN_NAME=pepsi.com and never think about it again.

[Steve Martinelli (stevemar)]

Setting middleware and client to invalid, very unlikely they will be affected

[Dolph Mathews (dolph)]

tl;dr Every option that we *require* users to set degrades the user experience.

[Morgan Fainberg (mdrnstm)]

Keystone no longer has v2/v3 split. V3 is always explicit about domain membership (as per the description of the bug). Moving this to "Wont Fix" for the server.