Identity API v2.0 and v3 History¶

I am a deployer¶

You’ll need to ensure the v3 API is included in your Paste pipeline, usually etc/keystone-paste.ini. Our latest sample configuration includes the v3 application pipeline.

First define a v3 application, which refers to the v3 application factory method:

[app:service_v3]
use = egg:keystone#service_v3

Then define a v3 pipeline, which terminates with the v3 application you defined above:

[pipeline:api_v3]
pipeline = ... service_v3

Replace “…” with whatever middleware you’d like to run in front of the API service. Our latest sample configuration documents our tested recommendations, but your requirements may vary.

Finally, include the v3 pipeline in at least one composite application (but usually both [composite:main] and [composite:admin]), for example:

[composite:main]
use = egg:Paste#urlmap
/v3 = api_v3
...

Once your pipeline is configured to expose both v2.0 and v3, you need to ensure that you’ve configured your service catalog in Keystone correctly. The simplest, and most ideal, configuration would expose one identity with unversioned endpoints (note the lack of /v2.0/ or /v3/ in these URLs):

• Service (type: identity)
  • Endpoint (interface: public, URL: http://identity:5000/)
  • Endpoint (interface: admin, URL: http://identity:35357/)

If you were to perform a GET against either of these endpoints, you would be greeted by an HTTP/1.1 300 Multiple Choices response, which newer Keystone clients can use to automatically detect available API versions.

$ curl -i http://identity:35357/
HTTP/1.1 300 Multiple Choices
Vary: X-Auth-Token
Content-Type: application/json
Content-Length: 755
Date: Tue, 10 Jun 2014 14:22:26 GMT

{"versions": {"values": [ ... ]}}

With unversioned identity endpoints in the service catalog, you should be able to authenticate with keystoneclient successfully.

I have a Python client¶

The Keystone community provides first-class support for Python API consumers via our client library, python-keystoneclient. If you’re not currently using this library, you should, as it is intended to expose all of our HTTP API functionality. If we’re missing something you’re looking for, please contribute!

Adopting python-keystoneclient should be the easiest way to migrate to Identity API v3.

I have a non-Python client¶

You’ll likely need to heavily reference our API documentation to port your application to Identity API v3.

The most common operation would be password-based authentication including a tenant name (i.e. project name) to specify an authorization scope. In Identity API v2.0, this would be a request to POST /v2.0/tokens:

{
    "auth": {
        "passwordCredentials": {
            "password": "my-password",
            "username": "my-username"
        },
        "tenantName": "project-x"
    }
}

And you would get back a JSON blob with an access -> token -> id that you could pass to another web service as your X-Auth-Token header value.

In Identity API v3, an equivalent request would be to POST /v3/auth/tokens:

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "domain": {
                        "id": "default"
                    },
                    "name": "my-username",
                    "password": "my-password"
                }
            }
        },
        "scope": {
            "project": {
                "domain": {
                    "id": "default"
                },
                "name": "project-x"
            }
        }
    }
}

Note a few key differences when compared to the v2.0 API:

• A “tenant” in v2.0 became a “project” in v3.
• The authentication method (password) is explicitly identified.
• Both the user name (my-username) and project name (project-x) are namespaced by an owning domain (where id = default). The “default” domain exists by default in Keystone, and automatically owns the namespace exposed by Identity API v2.0. Alternatively, you may reference users and projects that exist outside the namespace of the default domain, which are thus inaccessible to the v2.0 API.
• In v3, your token is returned to you in an X-Subject-Token header, instead of as part of the request body. You should still authenticate yourself to other services using the X-Auth-Token header.