Documentation error - Identity API v3 (CURRENT) in Identity API Reference

[nigel cook]

This bug tracker is for errors with the documentation, use the following as a template and remove or add fields as you see fit. Convert [ ] into [x] to check boxes:

- [x] This doc is inaccurate in this way: The Keystone API documentation shows use "id" in the scoped token payload examples for domain with a domain name vs numeric id. In some examples usage is "domain":{ "name" : "Default" } (which is valid) in other cases (as the project scoped token below) with an "id". In the example below
"domain": {
                    "id": "b6e5540447cb3741900000000"
                },

OR

"domain": {
                    "name": "default"
                },

Currently posted on the site is:

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": {
            "project": {
                "domain": {
                    "id": "default"
                },
                "name": "admin"
            }
        }
    }
}

- [ ] This is a doc addition request.
- [ ] I have a fix to the document that I can paste below including example: input and output.

If you have a troubleshooting or support issue, use the following resources:

 - Ask OpenStack: http://ask.openstack.org
 - The mailing list: http://lists.openstack.org
 - IRC: 'openstack' channel on Freenode

-----------------------------------
Release: v3.11 on 'Fri Nov 30 09:43:25 2018, commit c975568'
SHA:
Source: Can't derive source file URL
URL: https://developer.openstack.org/api-ref/identity/v3/

[Colleen Murphy (krinkle)]

Using either a name or an ID to identify a domain are both valid. A domain ID of the string "default" is also valid, we create the default domain with that ID. All other domains have UUIDs as IDs. Are you seeing an error when trying to get a token with a domain identified by ID?

[nigel cook (nigelcook)]

Thanks.

I had suspected the Id: default was also valid due to some behavior seen
when users didn't have a default project specified.

May be some additional examples or additional explanatory text around the
scoped token fields would help.

On Dec 3, 2018 3:15 AM, "Colleen Murphy" <email address hidden> wrote:

Using either a name or an ID to identify a domain are both valid. A
domain ID of the string "default" is also valid, we create the default
domain with that ID. All other domains have UUIDs as IDs. Are you seeing
an error when trying to get a token with a domain identified by ID?

** Changed in: keystone
       Status: New => Incomplete

--
You received this bug notification because you are subscribed to the bug
report.
https://bugs.launchpad.net/bugs/1806195

Title:
  Documentation error - Identity API v3 (CURRENT) in Identity API
  Reference

Status in OpenStack Identity (keystone):
  Incomplete

Bug description:
  This bug tracker is for errors with the documentation, use the
  following as a template and remove or add fields as you see fit.
  Convert [ ] into [x] to check boxes:

  - [x] This doc is inaccurate in this way: The Keystone API documentation
shows use "id" in the scoped token payload examples for domain with a
domain name vs numeric id. In some examples usage is "domain":{ "name" :
"Default" } (which is valid) in other cases (as the project scoped token
below) with an "id". In the example below
  "domain": {
                      "id": "b6e5540447cb3741900000000"
                  },

  OR

  "domain": {
                      "name": "default"
                  },

  Currently posted on the site is:

  {
      "auth": {
          "identity": {
              "methods": [
                  "password"
              ],
              "password": {
                  "user": {
                      "id": "ee4dfb6e5540447cb3741905149d9b6e",
                      "password": "devstacker"
                  }
              }
          },
          "scope": {
              "project": {
                  "domain": {
                      "id": "default"
                  },
                  "name": "admin"
              }
          }
      }
  }

  - [ ] This is a doc addition request.
  - [ ] I have a fix to the document that I can paste below including
example: input and output.

  If you have a troubleshooting or support issue, use the following
  resources:

   - Ask OpenStack: http://ask.openstack.org
   - The mailing list: http://lists.openstack.org
   - IRC: 'openstack' channel on Freenode

  -----------------------------------
  Release: v3.11 on 'Fri Nov 30 09:43:25 2018, commit c975568'
  SHA:
  Source: Can't derive source file URL
  URL: https://developer.openstack.org/api-ref/identity/v3/

To manage notifications about this bug go to:
https://bugs.launchpad.net/keystone/+bug/1806195/+subscriptions

[Colleen Murphy (krinkle)]

There are already two examples of using a domain name or ID when the domain is the scope target:

https://developer.openstack.org/api-ref/identity/v3/?expanded=password-authentication-with-scoped-authorization-detail#domain-scoped-with-domain-id-example
https://developer.openstack.org/api-ref/identity/v3/?expanded=password-authentication-with-scoped-authorization-detail#domain-scoped-with-domain-name-example

Granted the project-scoped example only uses a domain with ID. There are already five request examples in that section and I think another one would get lost.

There is explanatory text for the scope parameter:

"...A domain scope may be specified by either the domain’s ID or name with equivalent results."

Would it help if this was expanded to mention that this applies whether the domain is the scope target or just the namespace of the project target?

[nigel cook (nigelcook)]

I think you could explain the content of the scoped token in more detail.
What are the permissible fields and values.

Also mention that while id is usually numeric "default" is a valid value
and what it means, and assumption associated with use (you must have a
default project assigned or you will be a non authorized error .. as an
example)

On Fri, Dec 7, 2018, 8:00 AM Colleen Murphy <<email address hidden> wrote:

> There are already two examples of using a domain name or ID when the
> domain is the scope target:
>
>
> https://developer.openstack.org/api-ref/identity/v3/?expanded=password-authentication-with-scoped-authorization-detail#domain-scoped-with-domain-id-example
>
> https://developer.openstack.org/api-ref/identity/v3/?expanded=password-authentication-with-scoped-authorization-detail#domain-scoped-with-domain-name-example
>
> Granted the project-scoped example only uses a domain with ID. There are
> already five request examples in that section and I think another one
> would get lost.
>
> There is explanatory text for the scope parameter:
>
> "...A domain scope may be specified by either the domain’s ID or name
> with equivalent results."
>
> Would it help if this was expanded to mention that this applies whether
> the domain is the scope target or just the namespace of the project
> target?
>
> --
> You received this bug notification because you are subscribed to the bug
> report.
> https://bugs.launchpad.net/bugs/1806195
>
> Title:
> Documentation error - Identity API v3 (CURRENT) in Identity API
> Reference
>
> Status in OpenStack Identity (keystone):
> Incomplete
>
> Bug description:
> This bug tracker is for errors with the documentation, use the
> following as a template and remove or add fields as you see fit.
> Convert [ ] into [x] to check boxes:
>
> - [x] This doc is inaccurate in this way: The Keystone API documentation
> shows use "id" in the scoped token payload examples for domain with a
> domain name vs numeric id. In some examples usage is "domain":{ "name" :
> "Default" } (which is valid) in other cases (as the project scoped token
> below) with an "id". In the example below
> "domain": {
> "id": "b6e5540447cb3741900000000"
> },
>
> OR
>
> "domain": {
> "name": "default"
> },
>
> Currently posted on the site is:
>
> {
> "auth": {
> "identity": {
> "methods": [
> "password"
> ],
> "password": {
> "user": {
> "id": "ee4dfb6e5540447cb3741905149d9b6e",
> "password": "devstacker"
> }
> }
> },
> "scope": {
> "project": {
> "domain": {
> "id": "default"
> },
> "name": "admin"
> }
> }
> }
> }
>
> - [ ] This is a doc addition request.
> - [ ] I have a fix to the document that I can paste below including
> example: input and output.
>
> If you have a troubleshooting or support issue, use the following
> resour...

[Colleen Murphy (krinkle)]

I can update the bug title to "Identity API Reference should include preamble about namespacing projects and users by domain ID or domain name" which should explain all cases in which you need to include a domain object, not just token requests, does that work?

I'm not sure what you mean by "and assumption associated with use (you must have a
default project assigned or you will be a non authorized error .. as an
example)" - a default project is not required, but a role assignment on some project is required in order to get a token scoped to that project, which I think is implied by "Uses the password authentication method and scopes authorization to a project, domain, or the system."

[Launchpad Janitor (janitor)]

[Expired for OpenStack Identity (keystone) because there has been no activity for 60 days.]

[nigel cook (nigelcook)]

Hi

Thanks for following up on this. Your suggestion is very good. Thank you

On Mon, Dec 10, 2018, 2:11 AM Colleen Murphy <email address hidden> wrote:

> I can update the bug title to "Identity API Reference should include
> preamble about namespacing projects and users by domain ID or domain
> name" which should explain all cases in which you need to include a
> domain object, not just token requests, does that work?
>
> I'm not sure what you mean by "and assumption associated with use (you
> must have a
> default project assigned or you will be a non authorized error .. as an
> example)" - a default project is not required, but a role assignment on
> some project is required in order to get a token scoped to that project,
> which I think is implied by "Uses the password authentication method and
> scopes authorization to a project, domain, or the system."
>
> --
> You received this bug notification because you are subscribed to the bug
> report.
> https://bugs.launchpad.net/bugs/1806195
>
> Title:
> Documentation error - Identity API v3 (CURRENT) in Identity API
> Reference
>
> Status in OpenStack Identity (keystone):
> Incomplete
>
> Bug description:
> This bug tracker is for errors with the documentation, use the
> following as a template and remove or add fields as you see fit.
> Convert [ ] into [x] to check boxes:
>
> - [x] This doc is inaccurate in this way: The Keystone API documentation
> shows use "id" in the scoped token payload examples for domain with a
> domain name vs numeric id. In some examples usage is "domain":{ "name" :
> "Default" } (which is valid) in other cases (as the project scoped token
> below) with an "id". In the example below
> "domain": {
> "id": "b6e5540447cb3741900000000"
> },
>
> OR
>
> "domain": {
> "name": "default"
> },
>
> Currently posted on the site is:
>
> {
> "auth": {
> "identity": {
> "methods": [
> "password"
> ],
> "password": {
> "user": {
> "id": "ee4dfb6e5540447cb3741905149d9b6e",
> "password": "devstacker"
> }
> }
> },
> "scope": {
> "project": {
> "domain": {
> "id": "default"
> },
> "name": "admin"
> }
> }
> }
> }
>
> - [ ] This is a doc addition request.
> - [ ] I have a fix to the document that I can paste below including
> example: input and output.
>
> If you have a troubleshooting or support issue, use the following
> resources:
>
> - Ask OpenStack: http://ask.openstack.org
> - The mailing list: http://lists.openstack.org
> - IRC: 'openstack' channel on Freenode
>
> -----------------------------------
> Release: v3.11 on 'Fri Nov 30 09:43:25 2018, commit c975568'
> SHA:
> Source: Can't derive source file URL
> URL: https://developer.openstack.org/api-ref/identity/v3/
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/keys...