workos-ruby

WorkOS official Ruby gem for interacting with WorkOS APIs

Documentation

Complete documentation for the latest version of WorkOS Ruby Gem can be found here.

Installation

To get started, you can install the WorkOS gem via RubyGems with:

gem install workos

If you're using Bundler to manage your application's gems, add the WorkOS gem to your Gemfile:

source 'https://rubygems.org'

gem 'workos'

Configuration

To use the SDK you must first provide your API key from the WorkOS Developer Dashboard.

You can do this through the WORKOS_API_KEY environment variable or by calling WorkOS.key = [your API key].

The WorkOS Gem will read the environment variable WORKOS_API_KEY:

$ WORKOS_API_KEY=[your api key] ruby app.rb

Alternatively, you may set the key yourself, such as in an initializer in your application load path:

# /config/initializers/workos.rb

WorkOS.key = '[your api key]'

The Audit Trail Module

The Audit Trail Module provides methods for creating Audit Trail events on WorkOS.

See our Audit Trail Overview for more information.

payload = {
  group: 'Foo Corp',
  location: '127.0.0.1',
  action: 'user.created',
  action_type: 'C',
  actor_name: 'Foo',
  actor_id: 'user_12345',
  target_name: 'Bar',
  target_id: 'user_67890',
  occurred_at: '2020-01-10T15:30:00-05:00',
  metadata: {
    source: 'Email',
  }
}

WorkOS::AuditTrail.create_event(event: payload)

Idempotency

To perform an idempotent request, provide an additional idempotency_key parameter to the create_event options.

WorkOS::AuditTrail.create_event(event: payload, idempotency_key: 'key123456')

See our API Reference for more information on idempotency keys.

The SSO Module

The SSO Module provides convenience methods for authenticating a Single Sign On (SSO) user via WorkOS. WorkOS SSO follows the Oauth 2.0 specification.

First, you'll direct your SSO users to an authorization_url. They will sign in to their SSO account with their Identity Provider, and be redirected to a callback URL that you set in your WorkOS Dashboard. The user will be redirected with a code URL parameter, which you can then exchange for a WorkOS::Profile using the WorkOS::SSO.get_profile method.

See our Ruby SSO example app for a complete example.

WorkOS::SSO.authorization_url(domain:, project_id:, redirect_uri:, state: {})

Generate an authorization URL to intitiate the WorkOS OAuth2 workflow.

WorkOS::SSO.authorization_url accepts four arguments:

• domain (string) — the authenticating user's company domain, without protocol (ex. example.com)

• project_id (string) — your application's WorkOS Project ID (ex. project_01JG3BCPTRTSTTWQR4VSHXGWCQ)

• state (optional, hash) — an optional hash used to manage state across authorization transactions (ex. { next_page: '/docs'})

• redirect_uri (string) — a callback URL where your application redirects the user-agent after an authorization code is granted (ex. workos.dev/callback). This must match one of your configured callback URLs for the associated project on your WorkOS dashboard.

This method will return an OAuth2 query string of the form:

https://${domain}/sso/authorize?response_type=code&client_id=${projectID}&redirect_uri=${redirectURI}&state=${state}

For example, when used in a Sinatra app:

DOMAIN = 'example.com'
PROJECT_ID = '{projectId}'
REDIRECT_URI = 'http://localhost:4567/callback'

get '/auth' do
  authorization_url = WorkOS::SSO.authorization_url(
    domain: DOMAIN,
    project_id: PROJECT_ID,
    redirect_uri: REDIRECT_URI,
  )

  redirect authorization_url
end

The user would be redirected to:

https://api.workos.com/sso/authorize?response_type=code&client_id={projectID}&redirect_uri=http://localhost:4567/callback

WorkOS takes over from here, sending the user to authenticate with their IDP, and on successful login, returns the user to your callback URL with a code parameter. You'll use WorkOS::SSO.profile to exchange the code for a WorkOS::Profile.

WorkOS::SSO.profile(code:, project_id:)</h4>

Fetch a WorkOS::Profile for an authorized user.

WorkOS::SSO.profile accepts two arguments:

• code (string) — an opaque string provided by the authorization server; will be exchanged for an Access Token when the user's profile is sent

• project_id (string) — your application's WorkOS Project ID (ex. project_01JG3BCPTRTSTTWQR4VSHXGWCQ)

This method will return an instance of a WorkOS::Profile with the following attributes:

<WorkOS::Profile:0x00007fb6e4193d20
  @id="prof_01DRA1XNSJDZ19A31F183ECQW5",
  @email="demo@workos-okta.com",
  @first_name="WorkOS",
  @connection_type="OktaSAML",
  @last_name="Demo",
  @idp_id="00u1klkowm8EGah2H357",
>

Our Sintatra app can be extended to use this method:

DOMAIN = 'example.com'
PROJECT_ID = '{projectId}'
REDIRECT_URI = 'http://localhost:4567/callback'

get '/auth' do
  authorization_url = WorkOS::SSO.authorization_url(
    domain: DOMAIN,
    project_id: PROJECT_ID,
    redirect_uri: REDIRECT_URI,
  )

  redirect authorization_url
end

get '/callback' do
  profile = WorkOS::SSO.profile(
    code: params['code'],
    project_id: PROJECT_ID,
  )

  session[:user] = profile.to_json

  redirect '/'
end

Given the WorkOS::Profile, you can now sign the user in according to your own authentication setup.