V3 Identity API: 'Methods' on auth needs better documentation

I completely agree. The best existing documentation that I'm aware of is here (see the "methods" attribute):

  https://github.com/openstack/identity-api/blob/master/openstack-identity-api/v3/src/markdown/identity-api-v3.md#tokens

> What happens if the method list is omitted, but e.g. password data is provided?

I would expect a 400 Bad Request, as I expect "methods" to be a required object in the request. However, it doesn't appear to be documented that way. And yes, it's completely redundant with the methods that are actually presented.

> What happens if two methods result in different outcomes?

I'm not sure this is defined at the API level (this is arguably a concern for the implementation?) but I would expect a 401.

> Do the methods have to be tried in order and then 'first success returns'?

Again, I don't think this is defined at the API level, but in this case, I think it should be. All authentication methods should be validated and fail fast.

> I think supporting multiple methods in one call is going to be incredibly difficult to get right.

Agree!

> What is the motivation here? Is this supposed to support multi-factor auth?

Yes, "methods" is explicitly intended to support multi-factor authentication.

In terms of a "bug," I'm marking this as 'wishlist' but it should be relatively high priority work to clearly define these behaviors.

V3 auth is intended to be a pluggable framework to enable multi-factor and multi-roundtrip (i.e. challenge-response) authentications.

"methods" let the server know which (auth) methods the client is authenticating with. If server does not support a method on the list, it should failed with a 401 and body of the response must contain a list of methods the server supports. If methods is omitted in the request, server must response with a 400.

All methods in the request must be succeeded in order for the server to issue a token. Otherwise, server must return a 401 with additional information in the response if one or more methods in the request did not succeeded. For example, server may issue a challenge such as next token code in order to fulfill the authentication.

Keystone defines two standard methods, "password" and "token". I would expect additional methods to be started off in contrib, with detail documents on with the method payloads, for both initial request and addition challenge/response if any. If a cloud provider support additional methods that are not in Keystone rep, it is the cloud provider's responsibility to get them documented.

Keystone does not dictate how many or which methods the client must used to authenticate a given user. That's up to the cloud provider/deployer the client is interacting with. Keystone will authenticate whatever methods the client presented and let the client know the methods used to obtain the token in the token data response. It is up to the cloud provider/deployer to determine what that token can and cannot do. For example, a token that was obtained with a multi-factor method may have access to additional services then a token that was obtain with a password method.

Hello everyone! I'd like to work on this bug, but I'm not really sure which repository I should update...

Since this is a documentation bug - we could add more information to https://github.com/openstack/keystone/tree/master/api-ref/source or https://github.com/openstack/keystone/tree/master/doc