1. Home >
2. Developer Blogs >
3. Getting started with OneLogin APIs using Ruby

Customers often tell us that one of the main attractions of OneLogin is that it makes it fast and easy to manage user identities. The easier they can do this, the better experience their users will have in terms of quickly accessing their apps.

While OneLogin provides a web UI to do this, our more advanced customers like to use code for user management. Because of that, we recently released new API client SDKs that make performing user administration tasks with OneLogin faster and easier than ever before.

The goal of this post is to give you a quick start on how to use the OneLogin Ruby gem to access the OneLogin API and speed up some common Identity and Access Management tasks.

It contains sample code so if you want to follow along you will need a OneLogin account and valid API credentials. If you don’t have a OneLogin account or just want a sandbox to play with you can sign up for a free developer account here.

API Credentials

Every endpoint on the OneLogin API requires a valid OAuth2 access_token. A benefit of using the OneLogin Ruby gem is that it takes care of the authentication side for you.

That being said, your API credentials need to have been configured with the appropriate level of authorization for the requests that you intend to make.

For the purpose of these samples we will go with the highest authorization level, “Manage All,” but it’s always good practice to limit authorization to the minimum required for the tasks that you want to achieve.

You can generate API credentials by doing the following:

1. Log into Onelogin (https://yourcompany.onelogin.com)
2. Navigate to your OneLogin admin console
3. Go to Settings > API
4. Click on New Credential. You’ll see a screen like the one below.

You can find the required authorization scopes for each request in the API documentation. E.g. To update a user you need “Manage All” or “Manage Users”.

Source & Install

The source code for the OneLogin Ruby gem, along with a full list of available methods, is on GitHub. Feel free to contribute or report issues with the gem there.

Once you have a working Ruby environment running Ruby version 1.9.3 or higher, open Terminal (on Mac OS) or PowerShell (on Windows), and install the OneLogin gem via RubyGems.

Setting up the Client

Next step is to setup the OneLogin client in your Ruby code. The minimum requirement for setting up the client is to provide the client_id and client_secret that were generated by OneLogin when you setup the API Credentials in the previous step.

The optional region parameter is the location of your OneLogin instance and defaults to us. If your instance is located in our European data centers then set this to eu.

require 'onelogin'

client = OneLogin::Api::Client.new(
    client_id: '',
    client_secret:'',
    region: 'us'
) 

Managing Users

A common use case for the OneLogin API is to list, create, and update users. It’s also possible to assign groups, roles, reset passwords, and many other admin type tasks but lets kick off with listing users.

Listing Users

To list all users in your account you will call get_users. It also supports filtering and paging to enable looping through your entire user base. See the API docs for a complete list of available filters.

Try the following Ruby code to list the full name of every user in your account.

client.get_users.each do |user|
    puts "#{user.firstname} #{user.lastname}"
end

Or perhaps just the first 5 users with a last name of Smith

# List the first 5 users with the name of Joe
client.get_users(lastname: 'Smith').take(5).each do |user|
    puts "#{user.firstname} #{user.lastname}"
end

Changing a user’s password

Resetting a password via API is a common task and we find that the reason varies between customers so we won’t jump into why you might want to do it but will cover how.

First of you will need to obtain the unique identifier for the user that you want to reset password for. You can do this by filtering by their email address and remember that get_users returns a list so you will want to fetch the first result. Let’s go into our Ruby code editor:

Now take that user and set a new password.

Note that unless you’re using a third party provided user directory, by default any password policies or minimum password requirements will be ignored when using this admin API. However, you can enforce password policy validation by setting the the final attribute of the method to true.

Using the console

This was a quick start on using the official OneLogin Ruby SDK with the goal of helping to get you set up and making requests. If you want to further explore the SDK and our APIs without having to build an entire app I recommend using a nifty command line console that is included with the gem.

To do this you will need to pull the source for the SDK from GitHub, using Terminal or PowerShell:

Then jump into the code you just pulled down and do a one time setup. On Terminal it will look like this:

Now enter the console:

And you’re ready to start making request with the sdk already being “required” for you. In Ruby we can write the following:

client = OneLogin::Api::Client.new(
    client_id: '',
    client_secret:''
)

latest_event = client.get_events.first

Summary

This was a quick start to using the OneLogin for Ruby SDK and had the main goal of getting you setup and making requests to the OneLogin API. We didn’t dive deep into all of the functionality provided by our APIs but we intend to cover more specific use cases in subsequent posts.

If you can’t wait for the next blog post then you can jump in and explore the API reference and quickly make test calls via the SDKs built in console.

Enjoy!

Rich Chetwynd founded Litmos, the market-leading learning technology company, as well as ThisData, a data security company leading the way in Account Takeover (ATO) attack detection. After ThisData was acquired by OneLogin in Summer 2017, Rich began working with the OneLogin engineering team with a focus on adaptive authentication.