IdentityServices provides authentication and authorization. More...

Public Member Functions
	__construct ($url)
	Build a new IdentityServices object.
	url ()
	Get the endpoint URL.
	authenticate (array $ops)
	Send an authentication request.
	authenticateAsUser ($username, $password, $tenantId=NULL, $tenantName=NULL)
	Authenticate to Identity Services with username, password, and either tenant ID or tenant Name.
	authenticateAsAccount ($account, $key, $tenantId=NULL, $tenantName=NULL)
	Authenticate to HPCloud using your account ID and access key.
	token ()
	Get the token.
	tenantId ()
	Get the tenant ID associated with this token.
	tenantName ()
	Get the tenant name associated with this token.
	tokenDetails ()
	Get the token details.
	isExpired ()
	Check whether the current identity has an expired token.
	serviceCatalog ($type=NULL)
	Get the service catalog, optionaly filtering by type.
	user ()
	Get information about the currently authenticated user.
	tenants ($token=NULL)
	Get a list of all tenants associated with this account.
	rescope ($tenantId)
	rescopeUsingTenantId ($tenantId)
	Rescope the authentication token to a different tenant.
	rescopeUsingTenantName ($tenantName)
	Rescope the authentication token to a different tenant.

Public Attributes
const	API_VERSION = '2.0'
	The version of the API currently supported.
const	ACCEPT_TYPE = 'application/json'
	The full OpenStack accept type.

Protected Member Functions
	handleResponse ($response)
	Given a response object, populate this object.

Protected Attributes
	$endpoint
	The URL to the CS endpoint.
	$tokenDetails
	The details sent with the token.
	$catalog = array()
	The service catalog.
	$userDetails

Detailed Description

IdentityServices provides authentication and authorization.

IdentityServices (a.k.a. Keystone) provides a central service for managing other services. Through it, you can do the following:

Authenticate
Obtain tokens valid accross services
Obtain a list of the services currently available with a token
Associate with tenants using tenant IDs.

AUTHENTICATION

The authentication process consists of a single transaction during which the client (us) submits credentials and the server verifies those credentials, returning a token (for subsequent requests), account information, and the service catalog.

Authentication credentials:

Username and password
Account ID and Secret Key

Other mechanisms may be supported in the future.

TENANTS

Services are associated with tenants. A token is returned when authentication succeeds. It may be associated with a tenant. If it is not, it is called "unscoped", and it will not have access to any services.

A token that is associated with a tenant is considered "scoped". This token can be used to access any of the services attached to that tenant.

There are two different ways to attach a tenant to a token:

During authentication, provide a tenant ID. This will attach a tenant at the outset.
After authentication, "rescope" the token to attach it to a tenant. This is done with the rescope() method.

Where do I get a tenant ID?

There are two notable places to get this information:

A list of tenants associated with this account can be obtain programatically using the tenants() method on this object.

HPCloud customers can find their tenant ID in the console along with their account ID and secret key.

EXAMPLE

The following example illustrates typical use of this class.

<?php
// You may need to use \HPCloud\Bootstrap to set things up first.
use \HPCloud\Services\IdentityServices;
// Create a new object with the endpoint URL (no version number)
$ident = new IdentityServices('https://example.com:35357');
// Authenticate and set the tenant ID simultaneously.
$ident->authenticateAsUser('butcher@hp.com', 'password', '1234567');
// The token to use when connecting to other services:
$token = $ident->token();
// The tenant ID.
$tenant = $ident->tenantId();
// Details about what services this token can access.
$services = $ident->serviceCatalog();
// List all available tenants.
$tenants = $ident->tenants();
// Switch to a different tenant.
$ident->rescope($tenants[0]['id']);
?>

PERFORMANCE CONSIDERATIONS

The following methods require network requests:

Serializing

IdentityServices has been intentionally built to serialize well. This allows implementors to cache IdentityServices objects rather than make repeated requests for identity information.

Definition at line 132 of file IdentityServices.php.

Constructor & Destructor Documentation

__construct ( $url )

Build a new IdentityServices object.

Each object is bound to a particular identity services endpoint.

For the URL, you are advised to use the version without a version number at the end, e.g. http://cs.example.com/ rather than http://cs.example.com/v2.0. The version number must be controlled by the library.

Attention: If a version is included in the URI, the library will attempt to use that URI.

<?php
$cs = new \HPCloud\Services\IdentityServices('http://example.com');
$token = $cs->authenticateAsAccount($accountId, $accessKey);
?>

Parameters

string $url An URL pointing to the Identity Services endpoint. Note that you do not need the version identifier in the URL, as version information is sent in the HTTP headers rather than in the URL. The URL should always be to an SSL/TLS encrypted endpoint..

Definition at line 208 of file IdentityServices.php.

References IdentityServices\API_VERSION.

Member Function Documentation

authenticate ( array $ops )

Send an authentication request.

Remarks: EXPERT: This allows authentication requests at a low level. For simple authentication requests using account number or username, see the authenticateAsUser() and authenticateAsAccount() methods.

Here is an example of username/password-based authentication done with the authenticate() method:

<?php
$cs = new \HPCloud\Services\IdentityServices($url);
$ops = array(
  'passwordCredentials' => array(
    'username' => $username,
    'password' => $password,
  ),
  'tenantId' => $tenantId,
);
$token = $cs->authenticate($ops);
?>

Note that the same authentication can be done by authenticateAsUser().

Parameters

array $ops An associative array of authentication operations and their respective parameters.

Return values

string

Returns: string The token. This is returned for simplicity. The full response is used to populate this object's service catalog, etc. The token is also retrievable with token().

Exceptions

HPCloud::Transport::AuthorizationException	If authentication failed.
HPCloud::Exception	For abnormal network conditions. The message will give an indication as to the underlying problem.

Definition at line 272 of file IdentityServices.php.

References IdentityServices\handleResponse(), IdentityServices\token(), and IdentityServices\url().

Referenced by IdentityServices\authenticateAsAccount(), and IdentityServices\authenticateAsUser().

authenticateAsAccount	(	$account,
		$key,
		$tenantId = `NULL`,
		$tenantName = `NULL`
	)

Authenticate to HPCloud using your account ID and access key.

Given an account ID and and access key (secret key), authenticate to Identity Services. Identity Services will then issue a token that can be used with other HPCloud services, such as Object Storage (aka Swift).

The account ID and access key information can be found in the account section of the console.

The third and fourth paramaters allow you to specify a tenant ID or tenantName. In order to access services, this object will need a tenant ID or tenant name. If none is specified, it can be set later using rescope(). The tenants() method can be used to get a list of all available tenant IDs for this token.

Other authentication methods:

Parameters

string	$account	The account ID. It should look something like this: 1234567890:abcdef123456.
string	$key	The access key (i.e. secret key), which should be a series of ASCII letters and digits.
string	$tenantId	A valid tenant ID. This will be used to associate a tenant's services with this token.
string	$tenantName	The tenant Name for this account. This can be obtained through the HPCloud console.

Return values

string

Returns: string The auth token.

Exceptions

HPCloud::Transport::AuthorizationException	If authentication failed.
HPCloud::Exception	For abnormal network conditions. The message will give an indication as to the underlying problem.

Definition at line 396 of file IdentityServices.php.

References $account, $key, $tenantId, and IdentityServices\authenticate().

authenticateAsUser	(	$username,
		$password,
		$tenantId = `NULL`,
		$tenantName = `NULL`
	)

Authenticate to Identity Services with username, password, and either tenant ID or tenant Name.

Given an HPCloud username and password, authenticate to Identity Services. Identity Services will then issue a token that can be used to access other HPCloud services.

If a tenant ID is provided, this will also associate the user with the given tenant ID. If a tenant Name is provided, this will associate the user with the given tenant Name. Only the tenant ID or tenant Name needs to be given, not both.

If no tenant ID or tenant Name is given, it will likely be necessary to rescope() the request (See also tenants()).

Other authentication methods:

Parameters

string	$username	A valid username.
string	$password	A password string.
string	$tenantId	The tenant ID for this account. This can be obtained through the HPCloud console.
string	$tenantName	The tenant Name for this account. This can be obtained through the HPCloud console.

Exceptions

HPCloud::Transport::AuthorizationException	If authentication failed.
HPCloud::Exception	For abnormal network conditions. The message will give an indication as to the underlying problem.

Definition at line 335 of file IdentityServices.php.

References $tenantId, and IdentityServices\authenticate().

handleResponse ( $response )

protected

Given a response object, populate this object.

This parses the JSON data and parcels out the data to the appropriate fields.

Parameters

object $response HPCloud::Transport::Response A response object.

Return values

HPCloud::Services::IdentityServices

Returns: $this for the current object so it can be used in chaining.

Definition at line 843 of file IdentityServices.php.

References IdentityServices\serviceCatalog(), and IdentityServices\tokenDetails().

Referenced by IdentityServices\authenticate(), IdentityServices\rescopeUsingTenantId(), and IdentityServices\rescopeUsingTenantName().

isExpired ( )

Check whether the current identity has an expired token.

This does not perform a round-trip to the server. Instead, it compares the machine's local timestamp with the server's expiration time stamp. A mis-configured machine timestamp could give spurious results.

Return values

boolean

Returns: boolean This will return FALSE if there is a current token and it has not yet expired (according to the date info). In all other cases it returns TRUE.

Definition at line 513 of file IdentityServices.php.

References IdentityServices\tokenDetails().

rescope ( $tenantId )

See Also: HPCloud::Services::IdentityServices::rescopeUsingTenantId()

Deprecated:

Definition at line 710 of file IdentityServices.php.

References $tenantId, and IdentityServices\rescopeUsingTenantId().

rescopeUsingTenantId ( $tenantId )

Rescope the authentication token to a different tenant.

Note that this will rebuild the service catalog and user information for the current object, since this information is sensitive to tenant info.

An authentication token can be in one of two states:

unscoped: It has no associated tenant ID.
scoped: It has a tenant ID, and can thus access that tenant's services.

This method allows you to do any of the following:

Begin with an unscoped token, and assign it a tenant ID.
Change a token from one tenant ID to another (re-scoping).
Remove the tenant ID from a scoped token (unscoping).

Parameters

string $tenantId The tenant ID that this present token should be bound to. If this is the empty string (`''`), the present token will be "unscoped" and its tenant ID will be removed.

Return values

string

Returns: string The authentication token.

Exceptions

HPCloud::Transport::AuthorizationException	If authentication failed.
HPCloud::Exception	For abnormal network conditions. The message will give an indication as to the underlying problem.

Definition at line 745 of file IdentityServices.php.

References $tenantId, $token, IdentityServices\handleResponse(), IdentityServices\token(), and IdentityServices\url().

Referenced by IdentityServices\rescope().

rescopeUsingTenantName ( $tenantName )

Rescope the authentication token to a different tenant.

Note that this will rebuild the service catalog and user information for the current object, since this information is sensitive to tenant info.

An authentication token can be in one of two states:

unscoped: It has no associated tenant ID.
scoped: It has a tenant ID, and can thus access that tenant's services.

This method allows you to do any of the following:

Begin with an unscoped token, and assign it a tenant ID.
Change a token from one tenant ID to another (re-scoping).
Remove the tenant ID from a scoped token (unscoping).

Parameters

string $tenantName The tenant name that this present token should be bound to. If this is the empty string (`''`), the present token will be "unscoped" and its tenant name will be removed.

Return values

string

Returns: string The authentication token.

Exceptions

HPCloud::Transport::AuthorizationException	If authentication failed.
HPCloud::Exception	For abnormal network conditions. The message will give an indication as to the underlying problem.

Definition at line 803 of file IdentityServices.php.

References $token, IdentityServices\handleResponse(), IdentityServices\token(), and IdentityServices\url().

serviceCatalog ( $type = NULL )

Get the service catalog, optionaly filtering by type.

This returns the service catalog (largely unprocessed) that is returned during an authentication request. If a type is passed in, only entries of that type are returned. If no type is passed in, the entire service catalog is returned.

The service catalog contains information about what services (if any) are available for the present user. Object storage (Swift) Compute instances (Nova) and other services will each be listed here if they are enabled on your account. Only services that have been turned on for the account will be available. (That is, even if you can create a compute instance, until you have actually created one, it will not show up in this list.)

One of the authentication methods MUST be run before obtaining the service catalog.

The return value is an indexed array of associative arrays, where each assoc array describes an individual service.

<?php
array(
  array(
    'name' : 'Object Storage',
    'type' => 'object-store',
    'endpoints' => array(
      'tenantId' => '123456',
      'adminURL' => 'https://example.hpcloud.net/1.0',
      'publicURL' => 'https://example.hpcloud.net/1.0/123456',
      'region' => 'region-a.geo-1',
      'id' => '1.0',
    ),
  ),
  array(
    'name' => 'Identity',
    'type' => 'identity'
    'endpoints' => array(
      'publicURL' => 'https://example.hpcloud.net/1.0/123456',
      'region' => 'region-a.geo-1',
      'id' => '2.0',
      'list' => 'http://example.hpcloud.net/extension',
    ),
  )
);
?>

This will not be populated until after authentication has been done.

Types:

While this is by no means an exhaustive list, here are a few types that might appear in a service catalog (and upon which you can filter):

identity: Identity Services (i.e. Keystone)
compute: Compute instance (Nova)
object-store: Object Storage (Swift)
hpext:cdn: HPCloud CDN service (yes, the colon belongs in there)

Other services will be added.

Todo:: Paging on the service catalog is not yet implemented.

Return values

array

Returns: array An associative array representing the service catalog.

Definition at line 596 of file IdentityServices.php.

Referenced by IdentityServices\handleResponse().

tenantId ( )

Get the tenant ID associated with this token.

If this token has a tenant ID, the ID will be returned. Otherwise, this will return NULL.

This will not be populated until after an authentication method has been run.

Return values

string

Returns: string The tenant ID if available, or NULL.

Definition at line 442 of file IdentityServices.php.

References IdentityServices\tokenDetails().

tenantName ( )

Get the tenant name associated with this token.

If this token has a tenant name, the name will be returned. Otherwise, this will return NULL.

This will not be populated until after an authentication method has been run.

Return values

string

Returns: string The tenant name if available, or NULL.

Definition at line 461 of file IdentityServices.php.

References IdentityServices\tokenDetails().

tenants ( $token = NULL )

Get a list of all tenants associated with this account.

If a valid token is passed into this object, the method can be invoked before authentication. However, if no token is supplied, this attempts to use the one returned by an authentication call.

Returned data will follow this format:

<?php
array(
  array(
    "id" =>  "395I91234514446",
    "name" => "Banking Tenant Services",
    "description" => "Banking Tenant Services for TimeWarner",
    "enabled" => TRUE,
    "created" => "2011-11-29T16:59:52.635Z",
    "updated" => "2011-11-29T16:59:52.635Z",
  ),
);
?>

Note that this method invokes a new request against the remote server.

Return values

array

Returns: array An indexed array of tenant info. Each entry will be an associative array containing tenant details.

Exceptions

HPCloud::Transport::AuthorizationException	If authentication failed.
HPCloud::Exception	For abnormal network conditions. The message will give an indication as to the underlying problem.

Definition at line 683 of file IdentityServices.php.

References $token, IdentityServices\token(), and IdentityServices\url().

token ( )

Get the token.

This will not be populated until after one of the authentication methods has been run.

Return values

string

Returns: string The token ID to be used in subsequent calls.

Definition at line 425 of file IdentityServices.php.

References IdentityServices\tokenDetails().

Referenced by IdentityServices\authenticate(), IdentityServices\rescopeUsingTenantId(), IdentityServices\rescopeUsingTenantName(), and IdentityServices\tenants().

tokenDetails ( )

Get the token details.

This returns an associative array with several pieces of information about the token, including:

id: The token itself
expires: When the token expires
tenant_id: The tenant ID of the authenticated user.
tenant_name: The username of the authenticated user.

<?php
array(
  'id' => 'auth_123abc321defef99',
  'tenant' => array(
    'id' => '123456',
    'name' => 'matt.butcher@hp.com',
  ),
  'expires' => '2012-01-24T12:46:01.682Z'
);

This will not be populated until after authentication has been done.

Return values

array

Returns: array An associative array of details.

Definition at line 496 of file IdentityServices.php.

References IdentityServices\$tokenDetails.

Referenced by IdentityServices\handleResponse(), IdentityServices\isExpired(), IdentityServices\tenantId(), IdentityServices\tenantName(), and IdentityServices\token().

url ( )

Get the endpoint URL.

This includes version number, so in that regard it is not an identical URL to the one passed into the constructor.

Return values

string

Returns: string The complete URL to the identity services endpoint.

Definition at line 229 of file IdentityServices.php.

References IdentityServices\$endpoint.

Referenced by IdentityServices\authenticate(), IdentityServices\rescopeUsingTenantId(), IdentityServices\rescopeUsingTenantName(), and IdentityServices\tenants().

user ( )

Get information about the currently authenticated user.

This returns an associative array of information about the authenticated user, including the user's username and roles.

The returned data is structured like this:

<?php
array(
  'name' => 'matthew.butcher@hp.com',
  'id' => '1234567890'
  'roles' => array(
    array(
      'name' => 'domainuser',
      'serviceId' => '100',
      'id' => '000100400010011',
    ),
    // One array for each role...
  ),
)
?>

This will not have data until after authentication has been done.

Return values

array

Returns: array An associative array, as described above.

Definition at line 643 of file IdentityServices.php.

References IdentityServices\$userDetails.

Member Data Documentation

$catalog = array()

protected

The service catalog.

Definition at line 177 of file IdentityServices.php.

$endpoint

protected

The URL to the CS endpoint.

Definition at line 147 of file IdentityServices.php.

Referenced by IdentityServices\url().

$tokenDetails

protected

The details sent with the token.

The exact details of this array will differ depending on what type of authentication is used. For example, authenticating by username and password will set tenant information. Authenticating by account ID and secret, however, will leave the tenant section empty.

This is an associative array looking like this:

<?php
array(
  'id' => 'auth_123abc321defef99',
  // Only non-empty for username/password auth.
  'tenant' => array(
    'id' => '123456',
    'name' => 'matt.butcher@hp.com',
  ),
  'expires' => '2012-01-24T12:46:01.682Z'
);

Definition at line 172 of file IdentityServices.php.

Referenced by IdentityServices\tokenDetails().

$userDetails

protected

Definition at line 179 of file IdentityServices.php.

Referenced by IdentityServices\user().

const ACCEPT_TYPE = 'application/json'

The full OpenStack accept type.

Definition at line 140 of file IdentityServices.php.

const API_VERSION = '2.0'

The version of the API currently supported.

Definition at line 136 of file IdentityServices.php.

Referenced by IdentityServices\__construct().

The documentation for this class was generated from the following file:

src/HPCloud/Services/IdentityServices.php

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation