README — Documentation for onelogin (1.6.0) (2024)

This SDK will let you execute all the API methods, version/1, describedat https://developers.onelogin.com/api-docs/1/getting-started/dev-overview.

The toolkit is hosted on github. You can download it from:

• Lastest release: https://github.com/onelogin/onelogin-ruby-sdk/releases/latest
• Master repo: https://github.com/onelogin/onelogin-ruby-sdk/tree/master

Installation

Add this line to your application's Gemfile:

gem 'onelogin'

And then execute:

$ bundle

Or install it yourself as:

$ gem install onelogin

Dependencies

• httparty

Getting started

You'll need a OneLogin account and a set of API credentials before you get started.

If you don't have an account you can sign up for a free developer account here.

require 'onelogin'client = OneLogin::Api::Client.new( client_id: '', client_secret:'', region: 'us')# Now you can make requestsclient.get_users

For all methods see Rubydoc of this SDK published at:http://www.rubydoc.info/github/onelogin/onelogin-ruby-sdk

Usage

Errors and exceptions

OneLogin's API can return 400, 401, 403 or 404 when there was any issue executing the action. When that happens, the methods of the SDK will include error and errorMessage in the client. Use error and error_description of the Client to retrieve them.

users = client.get_usersif users.nil? puts client.error puts client.error_descriptionend

In some scenarios there is an attribute not provided or invalid that causes the error,when that happens in addition to the error_description a error_attribute is availablewith the name of the attribute that caused the issue. Accesible at the client like:

client.error_attribute

Authentication

By default methods call internally to get_access_token if there is no valid access_token. You can also get tokens etc directly if needed.

# Get an AccessTokentoken = client.get_access_token# Refresh an AccessTokentoken2 = client.regenerate_token# Revoke an AccessTokentoken3 = client.get_access_token

Paging

All OneLogin API endpoints that support paging are returned as enumerations to save you keeping track of the paging cursor.

User take to limit the results or get all results by enumerating.

e.g.

# List the first name of all usersclient.get_users.each do |user| puts user.firstnameend# List the first name of all users starting with the 2nd user# `each` accepts a start param to skip first x resultsclient.get_users.each(1) do |user| puts user.firstnameend# List the first 5 users with the name of Joeclient.get_users(firstname: 'Joe').take(5).each do |user| puts "#{user.firstname} #{user.lastname}"end# Get 10 event idsclient.get_events.take(10).map{|event| event.id }# Get all rolesclient.get_roles.to_a

For safety where some collections (e.g. get_events) have large numbers of resources there is alimit of 1000 total results returned. You can override this with the max_results param during Client initialization.

client = OneLogin::Api::Client.new( client_id: '', client_secret:'', max_results: 50000)client.get_events.map {|event| event.id}

Available Methods

# Get rate limitsrate_limits = client.get_rate_limits# Get Custom Attributescustom_global_attributes = client.get_custom_attributes# Get Users with no query parametersusers = client.get_users# Get Users with query parametersquery_parameters = { email: "[emailprotected]"}users_filtered = client.get_users(query_parameters)query_parameters = { email: "[emailprotected]"}users_filtered2 = client.get_users(query_parameters)# Get Users with limitquery_parameters = { limit: 3}users_filtered_limited = client.get_users(query_parameters)# Only return the firstname and email fields for each userclient.get_users(fields: 'email,firstname').each do |user| puts "#{user.firstname} - #{user.email}"end# Get User by iduser = client.get_user(users_filtered.first.id)user_mfa = client.get_user(users_filtered2.first.id)# Update User with specific iduser = client.get_user(user.id)update_user_params = user.get_user_paramsupdate_user_params["firstname"] = 'modified_firstname'user = client.update_user(user.id, update_user_params)user = client.get_user(user.id)# Get Global Rolesroles = client.get_roles# Get Rolerole = client.get_role(1234)# Assign & Remove Roles On Usersrole_ids = [ 1234, 5678]result = client.assign_role_to_user(user.id, role_ids)role_ids.popresult = client.remove_role_from_user(user.id, role_ids)user = client.get_user(user.id)# Sets Password by ID Using Cleartextpassword = "Aa765431-XxX"result = client.set_password_using_clear_text(user.id, password, password)# Sets Password by ID Using Salt and SHA-256password = "Aa765432-YyY"salt = "11xxxx1"require 'digest'sha256 = Digest::SHA256.newhashed_salted_password = sha256.hexdigest("#{pw}#{salt}")result = client.set_password_using_hash_salt(user_mfa.id, hashed_salted_password, hashed_salted_password, "salt+sha256", salt) Set Custom Attribute Value to UsercustomAttributes = { custom_global_attributes[0]=> "xxxx", custom_global_attributes[1]=> "yyyy"}result = client.set_custom_attribute_to_user(34687020, customAttributes)# Log Out Userresult = client.log_user_out(user.id)# Lock Userresult = client.lock_user(user.id, 5)# Get User appsapps = client.get_user_apps(user.id)# Get User Rolesrole_ids = client.get_user_roles(user.id)# Generate MFA Tokenmfa_token = client.generate_mfa_token(user.id)# Get all Connectors in a OneLogin account filtering by name*/apps = client.get_connectors({name:'SAML'})# Get all Apps in a OneLogin account using API v1 */apps_v1 = client.get_apps_v1# Get all Apps in a OneLogin account filtering by auth_method*/apps = client.get_apps({auth_method:6})# Create appapp_data = { name: "Created SAML App by API", description:"Created SAML App by API description", notes: "Created SAML App by API notes", auth_method: 2, policy_id: 167865, allow_assumed_signin: false, parameters: { saml_username: { user_attribute_mappings: "email", label: "NameID (fka Email)", } }, connector_id: 110016, visible: true, configuration: { saml_initiater_id: "0", encrypt_assertion: "0", recipient: "http://sp.example.com/acs", saml_notbefore: "3", saml_nameid_format_id: "0", saml_issuer_type: "0", saml_sign_element: "0", consumer_url: "http://sp.example.com/acs", validator: ".*", relaystate: "", logout_url: "http://sp.example.com/sls", saml_encryption_method_id: "0", login: "http://sp.example.com/login", saml_sessionnotonorafter: "1440", generate_attribute_value_tags: "0", saml_notonorafter: "3", audience: "http://sp.example.com/audience", signature_algorithm: "SHA-256" }}app = client.create_app(app_data)# Update appapp_data[:name] = "Created SAML App by API updated"client.update_app(app.id, app_data)# Get appapp = client.get_app(app.id)# Delete appresult = client.delete_app(app.id)# Delete parameter from appresult = client.delete_parameter_from_app(app.id, parameter_id)# Create usernew_user_params = { email: "[emailprotected]", firstname: "testcreate_1_fn", lastname: "testcreate_1_ln", username: "[emailprotected]"}created_user = client.create_user(new_user_params)# Delete Userresult = client.delete_user(created_user.id)# Get EventTypesevent_types = client.get_event_types# Get Eventsevents = client.get_eventsquery_events_params = { limit: 2}events_limited = client.get_events(query_events_params)# Get Eventevent = client.get_event(events[0].id)# Create Eventnew_event_params = { event_type_id: "000", account_id: "00000", actor_system: "00", user_id: "00000000", user_name: "test_event", custom_message: "test creating event from python :)"}result = client.create_event(new_event_params)# Get Filtered Eventsquery_events_params = array( user_id: "00000000")events = client.get_events(query_events_params)# Get Groupsgroups = client.get_groups# Get Groupgroup = client.get_group(groups.first.id)# Get SAMLResponse directlyapp_id = "000000"saml_endpoint_response = client.get_saml_assertion("[emailprotected]", "Aa765431-XxX", app_id, "example-onelogin-subdomain")# Get SAMLResponse after MFAsaml_endpoint_response2 = client.get_saml_assertion("[emailprotected]", "Aa765432-YyY", app_id, "example-onelogin-subdomain")mfa = saml_endpoint_response2.mfaotp_token = "000000"saml_endpoint_response_after_verify = client.get_saml_assertion_verifying(app_id, mfa.devices[0].id, mfa.state_token, "78395727", nil)# Create Session Login Tokensession_login_token_params = { username_or_email: "[emailprotected]", password: "Aa765431-XxX", subdomain: "example-onelogin-subdomain"}session_token_data = client.create_session_login_token(session_login_token_params)# Create Session Login Token MFA , after verifysession_login_token_mfa_params = { username_or_email: "[emailprotected]", password: "Aa765432-YyY", subdomain: "example-onelogin-subdomain"}session_token_mfa_data = client.create_session_login_token(session_login_token_mfa_params)otp_token = "000000" # We get this value from OTP devicesession_token_data2 = client.get_session_token_verified(session_token_mfa_data.devices.first.id,session_token_mfa_data.state_token, otp_token)user_id = 00000000# Get Available Authentication Factorsauth_factors = client.get_factors(user_id)# Enroll an Authentication Factorenroll_factor = client.enroll_factor(user_id, auth_factors.first.id, 'My Device', '+14156456830')# Get Enrolled Authentication Factorsotp_devices = client.get_enrolled_factors(user_id)# Activate an Authentication Factordevice_id = 0000000enrollment_response = client.activate_factor(user_id, device_id)# Verify an Authentication Factorresult = client.verify_factor(user_id, device_id, otp_token="4242342423")# Remove a Factorresult = client.remove_factor(user_id, device_id)# Generate Invite Linkurl_link = client.generate_invite_link("[emailprotected]")# Send Invite Linksent = client.send_invite_link("[emailprotected]")#Get Apps to Embed for a Userembed_token = "30e256c101cd0d2e731de1ec222e93c4be8a1572"apps = client.get_embed_apps("30e256c101cd0d2e731de1ec222e93c4be8a1572", "[emailprotected]")# Get Privilegesprivileges = client.get_privileges()# Create Privilegename = "privilege_example"version = "2018-05-18"statement1 = OneLogin::Api::Models::Statement.new( "Allow", [ "users:List", "users:Get", ], ["*"])statement2 = OneLogin::Api::Models::Statement.new( "Allow", [ "apps:List", "apps:Get", ], ["*"])statements = [ statement1, statement2]privilege = client.create_privilege(name, version, statements)# Update Privilegename = "privilege_example_updated"statement2 = OneLogin::Api::Models::Statement.new( "Allow", [ "apps:List", ], ["*"])statements = [ statement1, statement2]privilege = client.update_privilege(privilege.id, name, version, statements)# Get Privilegeprivileges = client.get_privilege(privilege.id)# Delete Privilegeresult = client.delete_privilege(privilege.id)# Gets a list of the roles assigned to a privilegeassigned_roles = client.get_roles_assigned_to_privilege(privilege.id)# Assign roles to a privilegeresult = client.assign_roles_to_privilege(privilege.id, [role_id1, role_id2])# Remove role from a privilegeresult = client.remove_role_from_privilege(privilege.id, role_id_1)# Gets a list of the users assigned to a privilegeassigned_users = client.get_users_assigned_to_privilege(privilege.id)# Assign users to a privilegeresult = client.assign_users_to_privilege(privilege.id, [user_id1, user_id2])# Remove user from a privilegeresult = client.remove_user_from_privilege(privilege.id, user_id2)

Proxy Servers

If you're stuck behind a proxy then you can still use this SDK by providing at a minimum thehost address of your proxy server.

client = OneLogin::Api::Client.new( client_id: 'some-client-id', client_secret:'some-client-secret', region: 'us', proxy_host: 'https://blah.com', proxy_port: '8080', proxy_user: 'username', proxy_pass: 'password')

• proxy_host - required, the host address of your proxy server
• proxy_port - optional, the port number of your proxy server
• proxy_user - optional, the username for your proxy server
• proxy_pass - optional, the password for your proxy server

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/onelogin/onelogin-ruby-sdk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the OneLogin Ruby Sdk project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.