See api-docs Menu

v1-v3 APIs have been deprecated

Don't worry, these APIs are deprecated, but they won't be shut off until 2017, at the earliest. Questions? Contact devsupport@onelogin.com.

All new development with APIs should use the newest version of our API: /1. API /1 is based on RESTful principles, is secured by OAuth 2.0, and provides JSON messages, search, pagination, sorting, and filtering.

Use the OneLogin SAML Assertion API with AWS STS

You can use the Generate SAML assertion API to programmatically generate a SAML assertion that you can use in a software integration.

For example, imagine that you are developing an app that enables a set of users in your organization to interact with Amazon Web Services (AWS), such as DynamoDB or S3.

There are a few steps that need to be completed along the way to enable your user to access AWS functionality in your app. See the following flow:

  1. The OneLogin user accesses your app. This action provides your app with OneLogin user credentials.

  2. Your app then calls the Generate SAML Assertion API. Your app passes OneLogin user credentials in exchange for a SAML assertion. This SAML assertion is, in plain words, proof that the user has successfully authenticated with OneLogin. This proof, or SAML assertion, may be verified by any entity, such as AWS Security Token Service (STS), that trusts OneLogin.

  3. Your app then calls the AWS STS AssumeRoleWithSAML operation. Your app passes the SAML assertion to STS, which verifies the SAML and responds with temporary security credentials. Specifically, STS provides your app with an AWS-specific access key ID, secret access key, and security token.

    STS credentials are not necessarily specific to any single service, such as DynamoDB. The credentials can be used to create any instance as long as the resource is permitted by the role and authorization is successful.

    Get more information about AWS STS.

  4. Your app then presents the AWS STS access key ID, secret access key, and security token to the needed AWS service, such as DynamoDB, which can then provide access to your app’s user.

The following sections provide some sample Ruby code that can be used in your app to perform steps 2, 3, and 4 in the flow above. It also performs additional steps to view data in DynamoDB once access has been granted. Let’s walk through the code.

Prerequisites

Before you can get a SAML assertion for AWS access using the Generate SAML assertion API, you must first configure SAML multi-role for AWS.

Step 1: Call the Generate SAML Assertion API to get a SAML assertion

Request

# For making HTTP calls in Rails 
require 'httparty'
# For communicating with Amazon Web Services
require 'aws-sdk'
# Sets the Amazon Resource Name of the AWS role that you want to assume to get 
# temporary security credentials from AWS STS. 
# See AWS-SDK for Ruby doc for details.
role_arn = 'arn:aws:iam::111011000000:role/SSORole'
# Sets the Amazon Resource Name of the SAML provider that will be used to get 
# temporary security credentials from AWS STS. 
# See AWS-SDK for Ruby doc for details.
principal_arn = 'arn:aws:iam::111011000000:saml-provider/SamlProvider'
# Creates a new AWS STS client. region is the AWS region to connect to. 
# access_key_id and secret_access_key values are placeholders. 
# Always load credentials from outside your application and avoid configuring 
# credentials statically. 
# See AWS-SDK for Ruby doc for details.
sts = Aws::STS::Client.new(access_key_id:'AAAAAAAAA1AAAAAAAA1A', secret_access_key: 
'XXxX111xx1XxxXxXXXxxxxX+XxxxxxXxXxxXXxXX', region:'us-west-1')
# Handles request to and response from the Generate SAML Assertion API
class F
# Makes the POST request to the Generate SAML Assertion API. 
# See API doc for details.
def self.saml_assertion
dev_url = 'https://app.onelogin.com/api/v3/saml/assertion'
body_params = {
 :api_key => '11x11xx1111xxx111111xx1111xx11xx11x11xxx',
 :username => 'pavel.lindo@email.com',
 :password => 'P@ssw0rd',
 :app_id => 123456
 }
options = {
:headers =>
{ 'Content-Type' => 'application/json' },
# httparty parameter that says keep trying the request until successful for 12 
# seconds and then stop
 :timeout => 12,
# httparty parameter that formats the body parameters in JSON
 :body => body_params.to_json
 }
response = HTTParty.post(dev_url, options)
resp = parse_response(response)
puts resp
resp
end
# Handles and formats the response. 
# If an error occurs, respond with 'nil'. 
# If the response is a 200 success, provide the content in the data element, 
# including the SAML assertion, as the response and format it as JSON.
def self.parse_response(response)
response_hash = JSON.parse(response.body)
if response_hash['status']['code'] == 200
response_hash['data']
else
nil
end
end
end

Response

Returns the SAML assertion.

Note: Want to take a look at the SAML assertion in cleartext? Use our Code/Decode > Base64 tool available on samltool.com. Copy the SAML assertion value from the data element in the response and paste it into the XML to be Base64 Decode field. Click BASE64 DECODE XML. The decoded content displays in the Base64 Decoded XML field. Use the XML Pretty Print tool, also on samltool.com, to prettify the code. Paste the decoded content into the XML field and click TURN PRETTY. The prettified XML displays in the XML Pretty Printed area.

Step 2: Call the AWS STS AssumeRoleWithSAML operation to get temporary security credentials

Request

Passes the role_arn, principal_arn, and SAML assertion from step 1 to the AssumeRoleWithSAML operation to get the following temporary security credentials for a user from AWS STS: access key ID, a secret access key, and a security token. See AWS-SDK for Ruby doc for details.

resp = sts.assume_role_with_saml(role_arn: role_arn,principal_arn:principal_arn,
saml_assertion:F.saml_assertion)

Response

Returns temporary security credentials for the user from STS, including an access key ID, secret access key, and security token. For example:

XXXxxXxxXxXxx1XxxxXxXXxxxX1x1xXxxXx1XxXxxxxxXXX...

Step 3: Build a client for Amazon DynamoDB

Request

Builds a client for Amazon DynamoDB. region is the region to connect to. access_key_id, secret_access_key, andsession_token refer to temporary security credentials received in Step 2. See AWS-SDK for Ruby doc for details.

dynamodb = Aws::DynamoDB::Client.new(region:'us-west-1',access_key_id:resp.data.credentials.
access_key_id,secret_access_key:resp.data.credentials.secret_access_key,
session_token:resp.data.credentials.session_token)

Response

Confirms client creation and returns a handle to an endpoint.

Step 4: Request list of data in DynamoDB tables accessible by the user

Request

Requests a list of data for all tables accessible by the user.

tab=dynamodb.list_tables

Response

Lists all data for all tables accessible by the user.

=> #<Aws::PageableResponse:0x000x00000x0000 @pager=#<Aws::Paging::Pager:1x111x11111x111
@limit_key=:limit,@tokens={"last_evaluated_table_name"=>"exclusive_start_table_name"}>,@context=#
<Seahorse::Client::RequestContext:...

Step 5: Request data about DynamoDB tables accessible by the user

Request

Requests data about the tables accessible by the user.

tab.data

Response

Lists data about the tables accessible by the user.

=> #<struct table_names=["TableAPITest", "TestAPI", "TestTable"], last_evaluated_table_name=nil>