Note: Please go to to access the current RightScale documentation set. Also, feel free to Chat with us!
Home > Guides > RightScale API 1.5 > Examples > End-to-End Examples > SAML Provisioning API E2E

SAML Provisioning API E2E


To become familiar with the basics of RightScale's Provisioning API through the use of SAML SSO. This includes understanding how to search for SAML identity providers, create users, grant and revoke privileges, and perform other various tasks through the RightScale API.

Table of Contents


  • You must have an Enterprise plan.
  • You must have the 'admin' permission enabled for every account whose users and permissions you wish to manage.
  • You must have a SAML identity provider configured to a RightScale account. For more information, see Getting Started with SAML.


This tutorial will outline how to use the RightScale API to create users configured with SAML. This end-to-end tutorial will walk you through how to locate you SAML identity provider information, create a user, and set up permissions for a newly created user via HTTP/curl calls. Additionally, it will explain how to update a current RightScale users with SAML and, at the end of the tutorial, will point to an advanced example that explains how RightScale manages and provisions a large number of internal users.
  • Some code examples below contain a "\" character to allow a single curl command to continue for several lines in the editor. This is done for readability so the shell will interpret the script's curl command as a single line. 
  • Each section that contains a code example starts with a heading that corresponds to the auto-generated reference information of the RightScale API. For example, the section Create Permissions is an example based off of the Create Permissions reference information. You can use the headings as a way to navigate the RightScale API Reference information for more information about parameters, filters, or other calls that can be made with a resource. 
  • If you are using OpenID, you will not be able to use SAML. Disable OpenID before following the steps to set up SAML.



You must be able to log in to your Enterprise account using SAML. See Getting Started with SAML on how to setup your account with this feature. 

Before making any API requests, you should enable OAuth 2.0 API access to each of your accounts. 

Note: You can also login to the API using an email address and password, as described in Authentication, but for the purposes of this tutorial, it is assumed that you are using SAML and have disabled password-based authentication to RightScale.

Follow the steps below to enable OAuth:

  1. Make sure you're in the account you want to enable with OAuth.
  2. Go to SettingsAccount Settings > API Credentials.
  3. In Status, click enable.
  4. Obtain the API refresh token in order to make API requests without logging in. It's important that this token is protected.

Note: The hostname of the "Token Enpoint (API 1.5)" may vary between RightScale accounts depending on the geographical region in which each account is hosted. Make sure to use the correct endpoint for your account when making API request, both OAuth and otherwise. 

Once set up, you can make the following request. Note that this token does not expire until it is "disabled." When it is "enabled," a new token will be generated.

Warning! Anyone with this token can log in to the API and perform API requests on your behalf, with all the permissions you have access to. Protect this token appropriately.

Example Call

curl -i -H X-API-Version:1.5 -X POST \
 -d refresh_token='cda1fe275610b099d0d901fb2c60512e0f2565e5' \
 -d grant_type='refresh_token' \

Example Response

{ "access_token":"eNotkMuOg...8vf4A2GhbCA==", "expires_in":7200, "token_type":"bearer" }

Use the access_token in place of a session cookie when you make API requests. As documented in the OAuth 2.0 Reference Documentation, this is a bearer-type token, meaning that you should include it as an Authorization header with every request.

Note: With the exception of the first example below, the access_token will not be displayed in other examples for readability sake.

Create a RightScale User with SAML

Get the SAML Identity Provider Href 

List Identity Providers

After SAML is set up for your enterprise account, and you have been authenticated, you have to search for the identity provider associated with your account. This is so you can have the necessary information when creating a RightScale SAML user. The information you need first is the identity_provider_href. The identity_provider_href is the href of your SAML identity provider as known by RightScale. 

Note: There is usually only one identity provider associated with an account.

Example Call

curl -i -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" \
Example Response
<?xml version="1.0" encoding="UTF-8"?>
    <created_at>2013/01/04 23:31:06 +0000</created_at>
    <updated_at>2013/01/04 23:38:40 +0000</updated_at>
    <name>Docs and Ed Test Provider</name>
      <link href="/api/identity_providers/64" rel="self"/> 
Make note of the self-link href that is associated with the identity provider you want. You will specify this href when creating users that are linked to this identity provider. The identity provider href never changes after it is created, so discovering your provider is generally a one-time operation.

Preconfigure a New User with SAML

Create a User

Before a user is created in RightScale, make sure the user is set up with an account with your SAML identity provider. You can only create or modify a user's authentication settings in RightScale when they are connected to your SAML identity provider. Creating a user with SAML access in RightScale is similar to creating a non-SAML user, the only difference being the two additional parameters that need to be specified: identity_provider_href and principal_uid. The identity_provider_href is what is returned from the GET identity_providers request. The principal_uid has to be the unique identity information (the SAML NameID or Subject) that your identity provider associates to the user. This is usually an email address, but its format can change depending on how you have configured your identity provider.


  • It's possible to enable a current RightScale user's with SAML settings. See Update a Current RightScale User with SAML to do this.
  • Be careful using special characters when you input information, for example, adding "-" or "()" to the phone number can cause errors. 
Example Call
curl -i -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" -X POST \
 -d user[email] \
 -d user[company]='Example Company' \
 -d user[phone]=1234567890 \
 -d user[first_name]=John \
 -d user[last_name]=Doe \
 -d user[identity_provider_href]='/api/identity_providers/64' \
 -d user[principal_uid]='' \

Example Response

HTTP/1.1 201 Created
Server: nginx/1.0.14
Date: Tue, 08 Jan 2013 18:07:15 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Status: 201 Created
Location: /api/users/64522
X-Runtime: 488
X-Request-Uuid: 63ddefa1840844a1a2069efb8546270a
Cache-Control: no-cache

Make note of the href of the new user. In the example above, the location specifies the user href: /api/users/64522.

Manage Permissions for a SAML User

Create Permissions

Once a user has been created, you should grant some permissions to that user in one or more accounts so the user can access the RightScale Dashboard. The first permission that must be added for a given account is 'observer.' Observer allows a user to login to the account and view the Dashboard. Even if an 'admin' role is added, the observer role still needs to be set first.

curl -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" \
 -d permission[user_href]='/api/users/64522' \
 -d permission[role_title]=observer \

Once a user has the observer role, you can add additional roles as needed. For information on the roles a RightScale user can have, see User Roles Privileges.

Note that since each permission is modeled as a distinct REST resource, you can only grant one role per API call. Additionally, you can also manage a user's permissions through the RightScale Dashboard by going to Settings > Account Settings > Users.

Note: Before you can manage a user's permissions through the Dashboard, you must first set 'observer' on the user so they appear in the Dashboard as a member of that account.
List Permissions

You can view the permissions available to a specific user by applying a filter on a GET call of the permissions collection. Displaying the permissions assigned to a user is helpful since you need the permission ID to remove an individual permission you previously granted.

Note: Attempting to show permissions on a user that has no permissions set would yield the same view as attempting to show a user that has not been created. In both cases, the response body will contain an empty list.

Example Call

curl -i -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" \
 -X GET -d filter[]="user_href==/api/users/64522"

You will receive an output of all the permissions available to the specific user.

Example Response

<?xml version="1.0" encoding="UTF-8"?>
      <link href="/api/permissions/590219" rel="self"/>
      <link href="/api/accounts/1234" rel="account"/>
      <link href="/api/users/64522" rel="user"/>
    <created_at>2012/10/04 19:25:29 +0000</created_at>
Destroy Permissions

To remove permissions from an account, you will need to delete each permission using the permission IDs that are returned when showing the permissions of a specific user. You can remove all permissions of a user and they will no longer have access to RightScale. If you ever need to grant access to a user that has had all permissions removed, just create permissions for the user. Note that you will need the user's href to do this. If you don't recall the user's herf, you can create the user again and the href associated to the user's email will be returned. A new href will not be created for a user that has been previously created in RightScale.


  • You must remove the 'observer' permission last or you will receive an error. The observer role allows a user to login and view the RightScale Dashboard.
  • Permissions can only be deleted one at a time since you are removing the permission ID associated to the user role.

Update a Current RightScale User with SAML

There are two uses cases that can occur when updating a RightScale user with SAML access.

  • You can have a user linked to your identity provider. If that is done, you have the capability to update that user's information. This will include their email address, name, phone number, and SAML settings.
  • If a user is not linked to your identity provider, you can find information about the user (by listing the user) and can grant or revoke privileges, but you cannot update their information.    

Link a user to your Identity Provider

To link a user to your identity provider, you can have  the user opt in through Authentication Settings in the RightScale Dashboard. 

Note: You can avoid having to have a user opt in through the dashboard, but that would require having to create an entire new account for them (see Create a RightScale User with SAML).

The information below explains how a user can opt in through Authentication Settings:

Getting Started with SAML

List Users

When a user is linked to your identity provider, you can list them to find their information. When you list users, you will see every user that has any permission on the current account. You can apply a filter to help narrow your search. The example below looks for a particular user email. If a user is linked to your SAML identity provider, the identity provider href will be displayed below the user ID information.


  • A user cannot have an account that uses both OpenID and SAML.
  • If a user becomes unlinked from the identity provider, you will no longer be able to update the user information through the provisioning API.


Example Call

curl -i -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" -X GET -d filter[]=""
Example Response
<?xml version="1.0" encoding="UTF-8"?>
    <updated_at>2012/12/28 22:51:34 +0000</updated_at>
      <link href="/api/users/7825" rel="self"/>
      <link href="/api/identity_providers/64" rel="identity_provider"/>
    <created_at>2008/10/14 23:48:55 +0000</created_at>
Make note of the user ID and identity provider ID.
Update Users

The same information is needed for updating a user as it is for creating a user, the only major difference is the call that's made. Instead of a POST to /api/users, you make a PUT request to /api/users/$user_id. You can update some or all of the user's attributes. 

Note: Be careful when changing a user's principal_uid. This could prevent the user from being able to log in with SAML if the wrong value is accidentally provided. Or if you modify a user's identity_provider_href you can also prevent them from being able to log in or even prevent you from updating their information.

The example below updates the listed user's company name and SAML identity provider information.

curl -i -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" -X PUT \
 -d user[current_email] \
 -d user[company]='New Company' \
 -d user[phone]=1234567890 \
 -d user[first_name]=John \
 -d user[last_name]=Doe \
 -d user[identity_provider_href]='/api/identity_providers/76' \
 -d user[principal_uid]='' \$user_id


Note: You will unable to modify a user that is not linked to your identity provider. If you attempt to, you will receive a 403 Forbidden error. 

Update a Current RightScale User's Permissions

You can modify current user's permissions just like you would a newly created user. See Manage Permissions for a SAML User.

Post Tutorial Steps

Now that you have been walked through the basics of how to create and provision users through the RightScale API, you may find it beneficial to see how this is done if you need to manage a large amount of users that need varying levels of permissions to RightScale. A RightScale developer created a RubyGem to help automate this for RightScale's own internal accounts, which can be viewed here: rs_user_policy. 

You can also read this blog post for more information regarding this tool: Manage Large-Scale User-Access Control with the RightScale API. 

You must to post a comment.
Last modified
12:07, 31 Oct 2014



This page has no classifications.



© 2006-2014 RightScale, Inc. All rights reserved.
RightScale is a registered trademark of RightScale, Inc. All other products and services may be trademarks or servicemarks of their respective owners.