SAML Provisioning API E2E

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

access_token="eNotkMuOg...8vf4A2GhbCA=="
curl -i -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" \
 -X GET https://my.rightscale.com/api/identity_providers.xml

<?xml version="1.0" encoding="UTF-8"?>
<identity_providers>
  <identity_provider>
    <created_at>2013/01/04 23:31:06 +0000</created_at>
    <discovery_hint>examplecompany.com</discovery_hint>
    <updated_at>2013/01/04 23:38:40 +0000</updated_at>
    <actions></actions>
    <name>Docs and Ed Test Provider</name>
    <links>
      <link href="/api/identity_providers/64" rel="self"/> 
    </links>
  </identity_provider>
</identity_providers>

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.

Note:

• 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. 

curl -i -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" -X POST \
 -d user[email]=john.doe@example.com \
 -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]='john.doe@example.com' \
https://my.rightscale.com/api/users

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
Set-Cookie:
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.

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 \
-X POST https://my.rightscale.com/api/permissions

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.

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 https://my.rightscale.com/api/permissions.xml -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"?>
<permissions>
  <permission>
    <links>
      <link href="/api/permissions/590219" rel="self"/>
      <link href="/api/accounts/1234" rel="account"/>
      <link href="/api/users/64522" rel="user"/>
    </links>
    <created_at>2012/10/04 19:25:29 +0000</created_at>
    <role_title>observer</role_title>
    <actions></actions>
  </permission>
</permissions>

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.

Note:

• 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.

curl -i -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" -X GET https://my.rightscale.com/api/users.xml -d filter[]="email==john.doe@example.com"

<?xml version="1.0" encoding="UTF-8"?>
<users>
  <user>
    <last_name>Doe</last_name>
    <updated_at>2012/12/28 22:51:34 +0000</updated_at>
    <links>
      <link href="/api/users/7825" rel="self"/>
      <link href="/api/identity_providers/64" rel="identity_provider"/>
    </links>
    </links>
    <first_name>John</first_name>
    <email>john.doe@example.com</email>
    <company>ExampleCompany</company>
    <actions></actions>
    <created_at>2008/10/14 23:48:55 +0000</created_at>
    <phone>1234567890</phone>
  </user>
</users>

user_id="7825"
curl -i -H X_API_VERSION:1.5 -H "Authorization: Bearer $access_token" -X PUT \
 -d user[current_email]=john.smith@example.com \
 -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]='examplecompany.com' \
https://my.rightscale.com/api/users/$user_id