Module: WorkOS::SSO

Extended by:
T::Sig, Base, Client
Defined in:
lib/workos/sso.rb

Overview

The SSO module provides convenience methods for working with the WorkOS SSO platform. You'll need a valid API key, a project ID, and to have created an SSO connection on your WorkOS dashboard.

See Also:

Constant Summary collapse

PROVIDERS = 
WorkOS::Types::Provider.values.map(&:serialize).freeze

Instance Attribute Summary

Attributes included from Base

#key

Class Method Summary collapse

Methods included from Client

client, execute_request, handle_error_response, post_request, user_agent

Class Method Details

.authorization_url(project_id:, redirect_uri:, domain: nil, provider: nil, state: {}) ⇒ String

Generate an Oauth2 authorization URL where your users will authenticate using the configured SSO Identity Provider.

Examples:

WorkOS::SSO.authorization_url(
  domain: 'acme.com',
  project_id: 'project_01DG5TGK363GRVXP3ZS40WNGEZ',
  redirect_uri: 'https://workos.com/callback',
  state: {
    next_page: '/docs'
  }
)

=> "https://api.workos.com/sso/authorize?domain=acme.com" \
   "&client_id=project_01DG5TGK363GRVXP3ZS40WNGEZ" \
   "&redirect_uri=https%3A%2F%2Fworkos.com%2Fcallback&" \
   "response_type=code&state=%7B%3Anext_page%3D%3E%22%2Fdocs%22%7D"

Parameters:

  • domain (String) (defaults to: nil) —

    The domain for the relevant SSO Connection configured on your WorkOS dashboard. One of provider or domain is required

  • provider (String) (defaults to: nil) —

    A provider name for an Identity Provider configured on your WorkOS dashboard. Only 'Google' is supported.

  • project_id (String) —

    The WorkOS project ID for the project where you've configured your SSO connection.

  • redirect_uri (String) —

    The URI where users are directed after completing the authentication step. Must match a configured redirect URI on your WorkOS dashboard.

  • state (Hash) (defaults to: {}) —

    An aribtrary state object that is preserved and available to the client in the response.

Returns:

  • (String) 


62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/workos/sso.rb', line 62

def authorization_url(
  project_id:, redirect_uri:, domain: nil, provider: nil, state: {}
)
  validate_domain_and_provider(provider: provider, domain: domain)

  query = URI.encode_www_form({
    client_id: project_id,
    redirect_uri: redirect_uri,
    response_type: 'code',
    state: state,
    domain: domain,
    provider: provider,
  }.compact)

  "https://#{WorkOS::API_HOSTNAME}/sso/authorize?#{query}"
end

.profile(code:, project_id:) ⇒ WorkOS::Profile

Fetch the profile details for the authenticated SSO user.

Examples:

WorkOS::SSO.profile(
  code: 'acme.com',
  project_id: 'project_01DG5TGK363GRVXP3ZS40WNGEZ'
)
=> #<WorkOS::Profile:0x00007fb6e4193d20
      @id="prof_01DRA1XNSJDZ19A31F183ECQW5",
      @email="demo@workos-okta.com",
      @first_name="WorkOS",
      @connection_type="OktaSAML",
      @last_name="Demo",
      @idp_id="00u1klkowm8EGah2H357",
      @access_token="01DVX6QBS3EG6FHY2ESAA5Q65X"
     >

Parameters:

  • code (String) —

    The authorization code provided in the callback URL

  • project_id (String) —

    The WorkOS project ID for the project where you've configured your SSO connection

Returns:



108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/workos/sso.rb', line 108

def profile(code:, project_id:)
  query = URI.encode_www_form(
    client_id: project_id,
    client_secret: WorkOS.key!,
    grant_type: 'authorization_code',
    code: code,
  )

  response = client.request(post_request(path: "/sso/token?#{query}"))
  check_and_raise_profile_error(response: response)

  WorkOS::Profile.new(response.body)
end