SDKS

Ruby SDK

The WorkOS Ruby Gem provides your Ruby applications convenient access to WorkOS integrations

Installation

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

Terminal

file_copy
gem install workos

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

Gemfile

file_copy
source 'https://rubygems.org'

gem 'workos'

View the source on GitHub.


Configuration

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

You can do this one of two ways:

The WorkOS Gem will read the environment variable WORKOS_API_KEY:

Ruby

file_copy
$ WORKOS_API_KEY={secretKey} ruby app.rb

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

Ruby

file_copy
WorkOS.key = '{secretKey}'

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.

For further reference, check out the SSO module yard docs.

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 five arguments:

  • domain (string) — the authenticating user's company domain, without protocol (ex. example.com)
  • projectID (string) — your application's WorkOS Project ID (ex. project_01JG3BCPTRTSTTWQR4VSHXGWCQ)
  • provider (optional, string) — optional parameter that specifies the type of Connection to authenticate with. If used, a user of any domain can be authenticated. Only GoogleOAuth is currently supported. Most commonly used for "Signup with Google" buttons.
  • state (optional, hash) — an optional hash used to manage state across authorization transactions (ex. { next_page: '/docs'})
  • redirectURI (string) — a callback URL where your application redirects the user-agent after an authorization code is granted (ex. workos.dev/callback)

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

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

For example, when used in a Sinatra app:

app.rb

file_copy
DOMAIN = '{foo-corp.com}'
PROJECT_ID = '{projectId}'
REDIRECT_URI = '{redirectURI}'

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&domain=foo-corp.com&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:)

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:

Ruby

file_copy
<WorkOS::Profile:0x00007fb6e4193d20
  @id="prof_01DRA1XNSJDZ19A31F183ECQW5",
  @email="[email protected]{foo-corp.com}",
  @first_name="WorkOS",
  @connection_type="OktaSAML",
  @last_name="Demo",
  @idp_id="00u1klkowm8EGah2H357",
  @raw_attributes={
    :id=>"prof_01DRA1XNSJDZ19A31F183ECQW5",
    :email=>"[email protected]{foo-corp.com}",
    :first_name=>"WorkOS",
    :last_name=>"Demo",
    :idp_id=>"00u1klkowm8EGah2H357"
  },
>

The Sinatra app can be extended to use this method:

app.rb

file_copy
DOMAIN = '{foo-corp.com}'
PROJECT_ID = '{projectId}'
REDIRECT_URI = '{redirectURI}'

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.

The AuditTrail Module

The AuditTrail Module provides convenience methods for publishing and reading application events via WorkOS.

For further reference, check out the complete AuditTrail module documentation.

WorkOS::AuditTrail.create_event(event:, idempotency_key: nil)

Create a provided audit trail event.

WorkOS::AuditTrail.create_event accepts two arguments:

  • event (hash) — an event hash containing descriptive attributes that detail your application's event.
  • idempotency_key (string, optional, defaults tonil) — a unique value which the server uses to recognize successive retries of the same request and safely retry requests without creating the same event more than once

For example, publishing a non-idempotent event:

create_event.rb

file_copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
payload = {
  group: 'example.com',
  location: '65.215.8.114',
  action: 'user.login_succeeded',
  action_type: 'R',
  actor_name: '[email protected]{foo-corp.com}',
  actor_id: 'user_01DEQWZNQT8Y47HDPSJKQS1J3F',
  target_name: '[email protected]{foo-corp.com}',
  target_id: 'user_01DEQWZNQT8Y47HDPSJKQS1J3F',
  occurred_at: '2020-09-18T12:19:21.273Z',
  metadata: {
    source: 'Email',
  }
}

WorkOS::AuditTrail.create_event(event: payload)

Results in WorkOS logging the following event:

JSON

file_copy
{
  "id": "evt_04DKH0F9DXZJ312A8G0CKRJ648Y",
  "group": "example.com",
  "location": "65.215.8.114",
  "action": "user.login_succeeded",
  "action_type": "R",
  "actor_name": "[email protected]{foo-corp.com}",
  "actor_id": "user_01DEQWZNQT8Y47HDPSJKQS1J3F",
  "target_name": "[email protected]{foo-corp.com}",
  "target_id": "user_01DEQWZNQT8Y47HDPSJKQS1J3F",
  "occurred_at": "2020-09-18T12:19:21.273Z",
  "metadata": {
    "source": "Email",
  },
}

For details about the specific use of each event attribute, as well as more information about using idempotency keys and metadata, refer to the API Reference.

WorkOS::AuditTrail.get_events(options: {})

Fetch a list of audit trail events.

WorkOS::AuditTrail.get_events accepts the following optional options:

  • before (string) - Event ID to look before
  • after (string) - Event ID to look after
  • limit (integer) - Number of Events to return
  • group[] (array) - List of Groups to filter for
  • action[] (array) - List of Actions to filter for
  • action_type[] (array) - List of Action Types to filter for. Can be one of C, R, U, or D.
  • actor_name[] (array) - List of Actor Name to filter for
  • actor_id[] (array) - List of Actor IDs to filter for
  • target_name[] (array) - List of Target Names to filter for
  • target_id[] (array) - List of Target IDs to filter for
  • occurred_at (string) - ISO-8601 datetime of when an event occurred
  • occurred_at_gt (string) - ISO-8601 datetime of when an event occurred after
  • occurred_at_gte (string) - ISO-8601 datetime of when an event occurred at or after
  • occurred_at_lt (string) - ISO-8601 datetime of when an event occurred before
  • occurred_at_lte (string) - ISO-8601 datetime of when an event occured at or before
  • search (string) - Keyword search

For example, requesting a list of events for successful user logins:

get_events.rb

file_copy
1
WorkOS::AuditTrail.get_events(action: 'user.login_succeeded')

Returns an array of any events that match the query:

JSON

file_copy
[
  {
    "id": "evt_04DKH0F9DXZJ312A8G0CKRJ648Y",
    "group": "foo-corp.com",
    "location": "65.215.8.114",
    "action": "user.login_succeeded",
    "action_type": "R",
    "actor_name": "[email protected]{foo-corp.com}",
    "actor_id": "user_01DEQWZNQT8Y47HDPSJKQS1J3F",
    "target_name": "[email protected]{foo-corp.com}",
    "target_id": "user_01DEQWZNQT8Y47HDPSJKQS1J3F",
    "occurred_at": "2020-09-18T12:19:21.273Z",
    "metadata": {
      "source": "Email",
    },
  },
  {
    "id": "evt_01DGZ0F9DXZJ312H8K0CKRJ64G",
    "group": "foo-corp.com",
    "location": "27.10.230.99",
    "action": "user.login_succeeded",
    "action_type": "R",
    "actor_name": "[email protected]{foo-corp.com}",
    "actor_id": "user_01DGZ0F97X0SXJB6D8KB8R0F7B",
    "target_name": "[email protected]{foo-corp.com}",
    "target_id": "user_01DGZ0F97X0SXJB6D8KB8R0F7B",
    "occurred_at": "2020-09-18T12:19:21.273Z",
    "metadata": {
      "source": "Email",
    },
  }
]