Skip to content
This repository has been archived by the owner on Dec 14, 2018. It is now read-only.

Home

Jump to bottom
charlieholder edited this page Jan 12, 2013 · 24 revisions

Stormpath PHP SDK

The Stormpath PHP SDK allows any PHP-based application to easily use the Stormpath cloud Identity Management service for all authentication and access control needs.

When you make SDK method calls, the calls are translated into HTTPS requests to the Stormpath REST+JSON API. The Stormpath PHP SDK therefore provides a clean object-oriented paradigm and alleviates the need to know how to make REST+JSON requests.

This SDK was implemented based on the 5.3.10 version of PHP.

Table of Contents

QuickStart
Client
Error Handling
Managing Applications
Managing Directories
Managing Accounts
Managing Groups
Group Membership

Quick Start

  1. Follow the installation/configuration directions located on the README.md file.

  2. Ensure you have an API Key so your application can communicate with Stormpath.

    Because Stormpath generates an apiKey.properties file and PHP tends to work better with YAML files, you'll want to create an apiKey.yml file. Copy your existing apiKey.properties file to a new file and make sure it is readable only by you:

     > cd $HOME/.stormpath
 > cp apiKey.properties apiKey.yml
 > chmod go-rwx apiKey.yml

    Then open and edit apiKey.yml to change its contents to use a colon : delimiter for key/value pairs instead of the equals = delimiter to ensure it is YAML compliant:

     apiKey.id: 144JVZINOF5EBNCMG9EXAMPLE
 apiKey.secret: lWxOiKqKPNwJmSldbiSkEbkNjgh2uRSNAb+AEXAMPLE

    More information on different ways to configure and retrieve information from this file can be found in the Client Builder API documentation.

  3. Configure your application to create a Stormpath SDK Client instance based on your API Key. The Client instance is your starting point for all operations with the Stormpath service. For example:

     $path = '/home/myhomedir/.stormpath/apiKey.yml';
 $builder = new Services_Stormpath_Client_ClientBuilder;
 $client = $builder->setApiKeyFileLocation($path)->build();

  4. Use the Client instance to interact with your tenant data, such as Applications, Directories, and Accounts:

     $tenant = $client->getCurrentTenant();
 
 $applications = $tenant->getApplications();
 
 foreach ($applications as $application) {
    echo 'Application ' . $application->getName();
 }
 
 $directories = $tenant->getDirectories();
 
 foreach ($directories as $directory) {
     
     echo 'Directory ' . $directory->getName();

     $accounts = $directory->getAccounts();

     foreach ($accounts as $account) {
        echo 'Account ' . $account->getGivenName();
     }
 }

Client

The root entry point for SDK functionality is the Client instance. Using the Client instance, you can access all of your tenant's data, such as applications, directories, groups, accounts, etc.

Preferred Configuration

There are different ways to create a Client instance to interact with your resources. The preferred mechanism is by reading a secure apiKey.yml file as shown above in the Quick Start, sections 2 and 3, where the ClientBuilder implementation is being used:

$apiKeyFile = '/home/myhomedir/.stormpath/apiKey.yml';
$builder = new Services_Stormpath_Client_ClientBuilder;
$client = $builder->setApiKeyFileLocation($apiKeyFile)->build();

This is heavily recommended if you have access to the file system.

Single URL Configuration

The above QuickStart assumes you have easy access to an apiKey.yml file. Some applications however may not have access to the file system (such as Heroku) applications. In these cases, you can also create a Client instance using a single URL, where often the URL is available as an environment variable (e.g. $_ENV).

This technique requires embedding the API Key ID and Secret as components in a URL. This allows you to have a single URL that contains all necessary information required to construct a Client.

WARNING: Do not use this technique if you have access to a file system. Depending on the environment, environment variables are less secure than reading a permission-restricted file like apiKey.yml.

If you do not have access to the file system to read an apiKey.yml file, then this technique might be useful to you:

You can use the Services_Stormpath_Client_ClientApplicationBuilder instead of the Services_Stormpath_Client_ClientBuilder. The Services_Stormpath_Client_ClientApplicationBuilder accepts a single URL of your Application's Stormpath HREF with the API Key information embedded in the URL. For example:

$appHref = "https://apiKeyId:[email protected]/v1/applications/YOUR_APP_UID_HERE"

Ensure that the apiKeyId and apiKeySecret components are URL-encoded.

Then you can acquire the Services_Stormpath_Client_ClientApplication using the ClientApplicationBuilder to obtain a Services_Stormpath_Client_Client and a Services_Stormpath_Resource_Application:

$builder = new Services_Stormpath_Client_ClientApplicationBuilder;
$clientApplication = $builder->setApplicationHref($appHre)->build();

$client = $clientApplication->getClient();
$application = $clientApplication->getApplication();

The ClientApplicationBuilder is a powerful utility that can be used in different ways, including all of the ClientBuilder functionalities. To learn more about its usage you can read the ClientApplicationBuilder API documentation.

API Key Configuration

Another way to create a Client is by creating an ApiKey instance with the API credentials and passing this instance to create the Client instance:

$apiKey = new Services_Stormpath_Client_ApiKey('apiKeyId', 'apiKeySecret');
$client = new Services_Stormpath_Client_Client($apiKey);

Or by using the static createClient function of the Services_Stormpath class:

$client = Services_Stormpath::createClient('apiKeyId', 'apiKeyId');

WARNING: DO NOT specify your actual apiKey.id and apiKey.secret values in source code! They are secure values associated with a specific person. You should never expose these values to other people, not even other co-workers.

Only use this technique if the values are obtained at runtime via a configuration mechanism that is not hard-coded into source code or easily-visible configuration files.

Error Handling

Errors thrown from the server are translated to a Services_Stormpath_Resource_ResourceError. This applies to all the requests to the Stormpath API endpoints.

For example, when getting the current tenant from the client you can catch any error that the request might produce the following way:

try {

    $client->getCurrentTenant();

} catch (Services_Stormpath_Resource_ResourceError $re)
{
    echo 'Message: ' . $re->getMessage();
    echo 'HTTP Status: ' . strval($re->getStatus()); 
    echo 'Developer Message: ' . $re->getDeveloperMessage();
    echo 'More Information: ' . $re->getMoreInfo();
    echo 'Error Code: ' . strval($re->getErrorCode());
}

Managing Applications

Listing Applications

To list all applications in your Tenant, we loop over the application list that we get from the current Tenant instance:

$tenant = $client->getCurrentTenant();

$applications = $tenant->getApplications();

foreach($applications as $app)
{
   echo 'Application ' . $app->getName();
   echo 'Application Description ' . $app->getDescription();
   echo 'Application Status ' . $app->getStatus();
}

Retrieving an Application

Most of the time, you will retrieve an Application that is referenced from another resource, for example via the ApplicationList shown above.

But you can also directly retrieve a specific Application via it's href (REST URL) value. For any Application, you can find the Application href in the Stormpath UI Console. This can be particularly useful when you need an application href for the ClientApplicationBuilder shown above.

After you have the href it can be loaded directly as an object instance by retrieving it from the server, using the data store:

$dataStore = $client->getDataStore();
$href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE';
$application = $dataStore->getResource($href, Services_Stormpath::APPLICATION); //the Services_Stormpath class provides the resources' classes' names

Creating Applications

To create applications, we use the "setters" of a new Application's instance to set the values we want. After this, we create the application from the tenant, the following way:

$tenant = $client->getCurrentTenant();

$application = $client->getDataStore()->instantiate(Services_Stormpath::APPLICATION); //the Services_Stormpath class provides the resources' classes' names
$application->setName('Application Name');
$application->setDescription('Application Description');

$application = $tenant->createApplication($application);

Editing Applications

To edit applications, we use the "setters" of an existing Application's instance to set the values we want and call the save method:

$application->setStatus(Services_Stormpath::DISABLED); //the Services_Stormpath class provides the valid status' constants
$application->setName('New Application Name');
$application->setDescription('New Application Description');

$application->save();

Managing Directories

Listing Directories

To list all directories in your Tenant, we loop over the directory list that we get from the current Tenant instance:

$tenant = $client->getCurrentTenant();

$directories = $tenant->getDirectories();

foreach($directories as $dir)
{
   echo 'Directory ' . $dir->getName();
   echo 'Directory Description ' . $dir->getDescription();
   echo 'Directory Status ' . $dir->getStatus();
}

Retrieving a Directory

Most of the time, you will retrieve a Directory that is linked from another resource, for example via the DirectoryList shown above, or as a direct reference, e.g. $account->getDirectory();.

But you can also directly retrieve a specific Directory via it's href (REST URL) value. For any Directory, you can find the Directory href in the Stormpath UI Console.

After you have the href it can be loaded directly as an object instance by retrieving it from the server, using the data store:

$dataStore = $client->getDataStore();
$href = 'https://api.stormpath.com/v1/directories/DIR_UID_HERE';
$directory = $dataStore->getResource($href, Services_Stormpath::DIRECTORY); //the Services_Stormpath class provides the resources' classes' names

Editing Directories

To edit directories, we use the "setters" of an existing Directory's instance to set the values we want and call the save method:

$directory->setStatus(Services_Stormpath::DISABLED); //the Services_Stormpath class provides the valid status' constants
$directory->setName('New Directory Name');
$directory->setDescription('New Directory Description');

$directory->save();

Managing Accounts

Creating Accounts

To create accounts, we use the "setters" of a new Account's instance to set the values we want. Then, we create the account from a Directory the following way:

$href = 'https://api.stormpath.com/v1/directories/DIR_UID_HERE';
$directory = $client->getDataStore()->getResource($href, Services_Stormpath::DIRECTORY);

$account = $client->getDataStore()->instantiate(Services_Stormpath::ACCOUNT);
$account->setEmail('Email');
$account->setGivenName('Given Name');
$account->setPassword('Password');
$account->setSurname('Surname');
$account->setUsername('Username');

$account = $directory->createAccount($account);

If you want to override the registration workflow (account verification via email link) and have the account created with ENABLED status right away, you may pass false as second argument, for example:

$account = $directory->createAccount($account, false);

If you want to associate the newly created account to a Group (we'll cover Groups later), you can do it the following way:

$account->addGroup($group);

Retrieving an Account

To retrieve a specific Account you will need its href. After you have the Account's href it can be loaded as an object instance by retrieving it from the server, using the data store:

$dataStore = $client->getDataStore();
$href = 'https://api.stormpath.com/v1/accounts/ACCOUNT_UID_HERE';
$account = $dataStore->getResource($href, Services_Stormpath::ACCOUNT); //the Services_Stormpath class provides the resources' classes' names

Verifying Accounts

If a Directory has the the account verification workflow enabled, a newly created account in the directory will have an UNVERIFIED status until their email address has been verified.

To verify the Account's email address (which will set its status to ENABLED), the verification token in the email needs to be obtained from the link that the account's holder receives in his email inbox. This is achieved by implementing the following logic:

$verificationToken = // obtain it from query parameter, according to the workflow configuration of the link

$tenant = $client->getCurrentTenant();

// when the account is correctly verified it gets activated and that account is returned in this verification
$account = $tenant->verifyAccountEmail($verificationToken);

Authenticating Accounts

To authenticate an account we need to have the Application to where the account will be authenticated against. After we have the Application, the account is authenticated by providing the username and password the following way:

$href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE';
$application = $client->getDataStore()->getResource($href, Services_Stormpath::APPLICATION);

// when the account is authenticated, it produces an Services_Stormpath_Authc_AuthenticationResult instance
$authResult = $application->authenticateAccount(new Services_Stormpath_Authc_UsernamePasswordRequest('username', 'password'));

// from the Services_Stormpath_Authc_AuthenticationResult instance we obtain the Account we just authenticated
$account = $authResult->getAccount();

Listing Accounts

To list accounts you need a directory or a group.

If you need to list the accounts that belong to a specific directory, this is how you do it:

$accounts = $directory->getAccounts();
foreach($accounts as $acc)
{
   echo 'Given Name ' . $acc->getGivenName();
   echo 'Surname ' . $acc->getSurname();
   echo 'Account Status ' . $acc->getStatus();
   echo 'Username ' . $acc->getUsername();
   echo 'Email ' . $acc->getEmail();
   echo 'Middle Name ' . $acc->getMiddleName();
}

Similarly, getting the accounts from a group works the following way:

$accounts = $group->getAccounts();

Editing Accounts

To edit accounts, we use the "setters" of an existing Account's instance to set the values we want and call the save method:

$account->setStatus(Services_Stormpath::DISABLED); //the Services_Stormpath class provides the valid status' constants
$account->setEmail('New Email');
$account->setGivenName('New Given Name');
$account->setPassword('New Password');
$account->setSurname('New Surname');
$account->setUsername('New Username');

$account->save();

If you want to add a group to an account, do the following:

$account->addGroup($group);

Reseting Account's Password

To use the password reset workflow you need to create a token that will be sent via email to the account's holder, and verify the token which returns the account where the password can be updated. This is done from the Application, like the following example:

$href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE';
$application = $client->getDataStore()->getResource($href, Services_Stormpath::APPLICATION);

// creating the password reset token and sending the email
$application->sendPasswordResetEmail('username or email');

After the user clicks the link, the password reset token should be obtained from the query string according to the link's configurations that you set on the password reset workflow, and the password can be changed the following way:

$href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE';
$application = $client->getDataStore()->getResource($href, Services_Stormpath::APPLICATION);

// getting the Account from the token and changing the password
$account = $application->verifyPasswordResetToken('PASS_RESET_TOKEN');
$account->setPassword('New Password');
$account->save();

Managing Groups

Listing Groups

To list all groups on a directory or an account, we loop the groups aggregate that we get from a directory or from an account:

$groups = // $directory->getGroups() or $account->getGroups()

foreach($groups as $group)
{
   echo 'Group ' . $group->getName();
   echo 'Group Description ' . $group->getDescription();
   echo 'Group Status ' . $group->getStatus();
   echo 'Group Tenant ' . $group->getTenant()->getName();
   echo 'Group Directory ' . $group->getDirectory()->getName();
}

Retrieving a Group

To retrieve a specific Group you will need its href. After you have the Group's href it can be loaded as an object instance by retrieving it from the server, using the data store:

$dataStore = $client->getDataStore();
$href = 'https://api.stormpath.com/v1/groups/GROUP_UID_HERE';
$group = $dataStore->getResource($href, Services_Stormpath::GROUP); //the Services_Stormpath class provides the resources' classes' names

Editing Groups

To edit groups, we use the "setters" of an existing Group's instance to set the values we want and call the save method:

$group->setStatus(Services_Stormpath::DISABLED); //the Services_Stormpath class provides the valid status' constants
$group->setName('New Group Name');
$group->setDescription('New Group Description');

$group->save();

If we want to add an existing account to the group, we just do the following:

$group->addAccount($account);

Group Membership

A group membership is the relationship between an Account and a Group

Deleting a group membership

A way to delete a group membership is by searching for it by looping the group membership aggregate of an account and, after it's found, retrieve it and delete it:

$groupHref = 'https://api.stormpath.com/v1/groups/GROUP_UID_HERE';
$group = $this->client->getDataStore()->getResource($groupHref, Services_Stormpath::GROUP);

$accountHref = 'https://api.stormpath.com/v1/accounts/ACCOUNT_UID_HERE';
$account = $this->client->getDataStore()->getResource($accountHref, Services_Stormpath::ACCOUNT);

$groupMembership = false;
// looping the group membership aggregate of the account
foreach($account->getGroupMemberShips() as $tmpGroupMembership)
{
    $tmpGroup = $tmpGroupMembership->getGroup();

    if ($tmpGroup and strrpos($tmpGroup->getHref(), $groupHref))
    {
        $groupMembership = $tmpGroupMembership;
        break;
     }
}

if ($groupMembership)
{
    $groupMembership->delete();
}
Clone this wiki locally