3.2. Sample Authentication Request and Response

3.2.1. Service Types in the Service Catalog
3.2.2. Suggested Workflow for Processing a Service Catalog Response

The sample request and response in this section illustrate a general case. In your authentication request, use your own credentials rather than the sample values shown here for username, password. and tenantId. When you authenticate successfully, the response to your authentication request will include a catalog of the services to which you have subscribed rather than the sample values shown here.

Example 3.1. Authentication Request with Headers: JSON

POST /v2.0/tokens HTTP/1.1
Host: identity.api.rackspacecloud.com
Content-Type: application/json
Accept: application/xml

{
  "auth": {
    "passwordCredentials": {
      "username": "demoauthor",
      "password": "mypass"
    },
    "tenantId": "1234"
  }
}

This is the username you use to login to the Rackspace Cloud Control Panel at http://mycloud.rackspace.com/.

This is the password you use to login to the Rackspace Cloud Control Panel.

Tenant is an optional specification. Some services use multi-level authentication, with service-specific credentials in addition to vendor-specific credentials. In such cases, associating a user with a tenant can be a method of passing that additional level of identifying information to the service.

A successful authentication response includes a token and a service catalog. For each service in the service catalog, only relevant details are returned, so the description of one service may include a different set of details than the description of another service. For example, some services' endpoints may be associated with a default region; if there is no default region for that endpoint, region is omitted.

Example 3.2. Service Catalog in Authentication Response with Headers: XML

HTTP/1.1 200 OKAY
Date: Mon, 12 Nov 2010 15:55:01 GMT
Content-Length:
Content-Type: application/xml; charset=UTF-8


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<access 
    xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
    xmlns="http://docs.openstack.org/identity/api/v2.0"
    xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
    xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
    xmlns:common="http://docs.openstack.org/common/api/v1.0"
    xmlns:ksgrp="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
    xmlns:rax-kscatalog="http://docs.openstack.org/identity/api/ext/OS-KSCATALOG/v1.0"
    xmlns:atom="http://www.w3.org/2005/Atom">
    <token 
        id="aaaaa-bbbbb-ccccc-dddd" 
        expires="2012-04-13T13:15:00.000-05:00"/>
    <user
        xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
        id="161418" name="demoauthor" rax-auth:defaultRegion="DFW">
        <roles>
            <role id="3" name="identity:user-admin" 
                description="User Admin Role."/>
        </roles>
    </user>
    <serviceCatalog>
        <service type="rax:database" name="cloudDatabases">
            <endpoint region="DFW" tenantId="12345"
                publicURL="https://dfw.databases.api.rackspacecloud.com/v1.0/12345"/>
            <endpoint region="ORD" tenantId="12345"
                publicURL="https://ord.databases.api.rackspacecloud.com/v1.0/12345"/>
        </service>
        <service type="rax:load-balancer" name="cloudLoadBalancers">
            <endpoint region="ORD" tenantId="12345"
                publicURL="https://ord.loadbalancers.api.rackspacecloud.com/v1.0/12345"/>
            <endpoint region="DFW" tenantId="12345"
                publicURL="https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/12345"/>
        </service>
        <service type="rax:object-cdn" name="cloudFilesCDN">
            <endpoint region="DFW" tenantId="MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
                publicURL="https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
            />
            <endpoint region="ORD" tenantId="MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
                publicURL="https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
            />
        </service>
        <service type="rax:monitor" name="cloudMonitoring">
            <endpoint tenantId="12345"
                publicURL="https://monitoring.api.rackspacecloud.com/v1.0/12345"/>
        </service>
        <service type="object-store" name="cloudFiles">
            <endpoint region="DFW" tenantId="MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
                publicURL="https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
                internalURL="https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
            />
            <endpoint region="ORD" tenantId="MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
                publicURL="https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
                internalURL="https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbbbb-ccccc-ddddd"
            />
        </service>
        <service type="compute" name="cloudServers">
            <endpoint tenantId="12345"
                publicURL="https://servers.api.rackspacecloud.com/v1.0/12345">
                <version id="1.0" info="https://servers.api.rackspacecloud.com/v1.0"
                    list="https://servers.api.rackspacecloud.com/"/>
            </endpoint>
        </service>
        <service type="compute" name="cloudServersOpenStack">
            <endpoint region="DFW" tenantId="12345"
                publicURL="https://dfw.servers.api.rackspacecloud.com/v2/12345">
                <version id="2" info="https://dfw.servers.api.rackspacecloud.com/v2"
                    list="https://dfw.servers.api.rackspacecloud.com/"/>
            </endpoint>
            <endpoint region="ORD" tenantId="12345"
                publicURL="https://ord.servers.api.rackspacecloud.com/v2/12345">
                <version id="2" info="https://ord.servers.api.rackspacecloud.com/v2"
                    list="https://ord.servers.api.rackspacecloud.com/"/>
            </endpoint>
        </service>
        <service type="rax:dns" name="cloudDNS">
            <endpoint tenantId="12345"
                publicURL="https://dns.api.rackspacecloud.com/v1.0/12345"/>
        </service>
    </serviceCatalog>
</access>

In XML responses only, a list of namespaces identifies API extensions that add functionality to the core API. You can read more about namespaces in Section 3.6, “Namespaces”.

This token can be presented to a service as evidence of authentication. Tokens are valid for a finite duration; a token's default lifespan is twenty-four hours.

The token's expires attribute denotes the time after which the token will automatically become invalid. A token may be manually revoked before the time identified by the expires attribute; expires predicts a token's maximum possible lifespan but does not guarantee that it will reach that lifespan. Clients are encouraged to cache a token until it expires.

Users can be assigned a default region so that, when there is a choice between multiple endpoints associated with a service in the user's catalog, the endpoint for the user's default region will be selected if it is available. In this example, the user's default region is DFW and several of the services in the user's catalog offer endpoints in that region and the ORD region; this user's work will be directed to the DFW region whenever possible.

Users can be assigned multiple roles, with each role providing specific privileges. In this example, joeuser is the administrative user for the account, holding the fully-privileged identity:user-admin role. Other users might hold other roles with different privileges. Roles need not be associated with actual job functions such as Administrator, Operator, Developer, Tester, or Trainer.

The service catalog lists the services this user can access. In this example, the user can access two compute services (Cloud Servers OpenStack and Cloud Servers) and two object storage services (Cloud Files Content Distribution Network (CDN), and Cloud Files), as well as one database service, one DNS service, one loadbalancing service, and one monitoring service. The catalog listing for each service provides at least one endpoint URL for that service. Other information, such as regions and versions and tenants, is provided if it's relevant to this user's access to this service.

The service type attribute identifies services that perform similar functions, whatever those services might be named. In this example, the services named cloudServers and cloudServersOpenstack are both identified as type="compute", identifying them as compute services even though the word "compute" does not appear in their names.

	Important
	Use service type as the primary value for locating a service. If multiple endpoints of the same service type exist in the same region, use service name as the tiebreaker.

The service name attribute identifies each unique service in the catalog. Once a service is created, its name does not change. However, new services of the same service type may be added to the catalog with new names.

Important

If you are programmatically parsing an authentication response, use service type rather than service name as the basis for determining whether a user has access to a particular kind of service. Service type is stable across all releases; new service types may be developed, but existing service types are not renamed. In this example, type="compute" identifies all the available compute services, one of which is named cloudServers and one of which is named cloudServersOpenStack. New compute service names may be added in future releases; whatever the compute services are named, you can always recognize them by parsing for type="compute" in the authentication response's service catalog.

A service may expose endpoints in different regions. Regional endpoints allow clients to provision resources in a manner that provides high availability.

Some services are not region-specific. These services supply a single non-regional endpoint and do not provide access to internal URLs.

Some services recognize specification of a tenant. If a service does recognize tenants, the format of the tenant specification is defined only by the service; for details about whether and how to specify a tenant, check the documentation for the service you are using.

An endpoint can be assigned public and internal URLs. A public URL is accessible from anywhere. Access to a public URL usually incurs traffic charges. Internal URLs are only accessible to services within the same region. Access to an internal URL is free of charge.

Example 3.3. Service Catalog in Authentication Response: JSON

{
    "access": {
        "serviceCatalog": [
            {
                "endpoints": [
                   {
                        "publicURL": "https://ord.servers.api.rackspacecloud.com/v2/12345",
                        "region": "ORD",
                        "tenantId": "12345",
                        "versionId": "2",
                        "versionInfo": "https://ord.servers.api.rackspacecloud.com/v2",
                        "versionList": "https://ord.servers.api.rackspacecloud.com/"
                    },
                    {
                        "publicURL": "https://dfw.servers.api.rackspacecloud.com/v2/12345",
                        "region": "DFW",
                        "tenantId": "12345",
                        "versionId": "2",
                        "versionInfo": "https://dfw.servers.api.rackspacecloud.com/v2",
                        "versionList": "https://dfw.servers.api.rackspacecloud.com/"
                    }
                ],
                "name": "cloudServersOpenStack",
                "type": "compute"
            },
            {
                "endpoints": [
                    {
                        "publicURL": "https://ord.databases.api.rackspacecloud.com/v1.0/12345",
                        "region": "ORD",
                        "tenantId": "12345"
                    },
                    {
                        "publicURL": "https://dfw.databases.api.rackspacecloud.com/v1.0/12345",
                        "region": "DFW",
                        "tenantId": "12345"
                    }
                ],
                "name": "cloudDatabases",
                "type": "rax:database"
            },
            {
                "endpoints": [
                    {
                        "publicURL": "https://ord.loadbalancers.api.rackspacecloud.com/v1.0/12345",
                        "region": "ORD",
                        "tenantId": "645990"
                    },
                    {
                        "publicURL": "https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/12345",
                        "region": "DFW",
                        "tenantId": "12345"
                    }
                ],
                "name": "cloudLoadBalancers",
                "type": "rax:load-balancer"
            },
            {
                "endpoints": [
                    {
                        "publicURL": "https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbb-cccc ",
                        "region": "DFW",
                        "tenantId": "MossoCloudFS_aaaa-bbbb-cccc "
                    },
                    {
                        "publicURL": "https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaa-bbbb-cccc ",
                        "region": "ORD",
                        "tenantId": "MossoCloudFS_aaaa-bbbb-cccc "
                    }
                ],
                "name": "cloudFilesCDN",
                "type": "rax:object-cdn"
            },
            {
                "endpoints": [
                    {
                        "publicURL": "https://dns.api.rackspacecloud.com/v1.0/12345",
                        "tenantId": "12345"
                    }
                ],
                "name": "cloudDNS",
                "type": "rax:dns"
            },
            {
                "endpoints": [
                    {
                        "publicURL": "https://servers.api.rackspacecloud.com/v1.0/12345",
                        "tenantId": "12345",
                        "versionId": "1.0",
                        "versionInfo": "https://servers.api.rackspacecloud.com/v1.0",
                        "versionList": "https://servers.api.rackspacecloud.com/"
                    }
                ],
                "name": "cloudServers",
                "type": "compute"
            },
            {
                "endpoints": [
                    {
                        "publicURL": "https://monitoring.api.rackspacecloud.com/v1.0/12345",
                        "tenantId": "12345"
                    }
                ],
                "name": "cloudMonitoring",
                "type": "rax:monitor"
            },
            {
                "endpoints": [
                    {
                        "internalURL": "https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbb-cccc ",
                        "publicURL": "https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbb-cccc ",
                        "region": "DFW",
                        "tenantId": "MossoCloudFS_aaaa-bbbb-cccc"
                    },
                    {
                        "internalURL": "https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbb-cccc ",
                        "publicURL": "https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbb-cccc ",
                        "region": "ORD",
                        "tenantId": "MossoCloudFS_aaaa-bbbb-cccc"
                    }
                ],
                "name": "cloudFiles",
                "type": "object-store"
            }
        ],
        "token": {
            "expires": "2012-04-13T13:15:00.000-05:00",
            "id": "aaaaa-bbbbb-ccccc-dddd"
        },
        "user": {
        "RAX-AUTH:defaultRegion": "DFW",
            "id": "161418",
            "name": "demoauthor",
            "roles": [
                {
                    "description": "User Admin Role.",
                    "id": "3",
                    "name": "identity:user-admin"
                }
            ]
        }
    }
}

A service may expose endpoints in different regions. Regional endpoints allow clients to provision resources in a manner that provides high availability.

Some services are not region-specific. These services supply a single non-regional endpoint and do not provide access to internal URLs.

Important

	Important
	Use service type as the primary value for locating a service. If multiple endpoints of the same service type exist in the same region, use service name as the tiebreaker.

This token can be presented to a service as evidence of authentication. Tokens are valid for a finite duration; a token's default lifespan is twenty-four hours.

Legal notices