[api] document "belongsTo" query for HEAD/GET tokens on v2

[Steve Martinelli]

Apparently there is a query parameter -- belongsTo -- that can be used on GET/HEAD requests to /v2.0/tokens/{token_id} -- it's not documented in the API reference at all.

Here's what it does:

 def _token_belongs_to(self, token, belongs_to):
        """Check if the token belongs to the right tenant.

        This is only used on v2 tokens. The structural validity of the token
        will have already been checked before this method is called.

        """
        if belongs_to:
            token_data = token['access']['token']
            if ('tenant' not in token_data or
                    token_data['tenant']['id'] != belongs_to):
                raise exception.Unauthorized()

https://github.com/openstack/keystone/blob/0340cd0150af04f950e2b868c932dfee2dbf8530/keystone/token/provider.py#L354-L365

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/375097
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=7f3f5963518c2b3da16911bee696ceee15de8d58
Submitter: Jenkins
Branch: master

commit 7f3f5963518c2b3da16911bee696ceee15de8d58
Author: Lance Bragstad <email address hidden>
Date: Thu Sep 22 20:29:46 2016 +0000

    Fix the belongsTo query parameter

    The belongsTo query parameter is only supported by the v2.0
    token validation API. It would check the ID of the project passed
    to the belongsTo parameter against the project a token was scoped to.

    This commit corrects the implementation, tests, and adds
    documentation. It also moves the check to keystone.token.controller
    since belongsTo is a v2-ism and doesn't belong in the
    keystone.token.provider.

    Closes-Bug: 1627085
    Closes-Bug: 1626794
    Change-Id: I4a06a498112b81093d7e5ef3142bb1e2d0f78138

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/keystone 11.0.0.0b1 development milestone.