Module: WorkOS::SSO

Extended by:
Client, Deprecation
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 client ID, and to have created an SSO connection on your WorkOS dashboard.

See Also:

Constant Summary collapse

PROVIDERS = 
WorkOS::Types::Provider::ALL

Class Method Summary collapse

Methods included from Client

client, delete_request, execute_request, get_request, handle_error_response, post_request, put_request, user_agent

Methods included from Deprecation

warn_deprecation

Class Method Details

.authorization_url(redirect_uri:, client_id: nil, domain: nil, domain_hint: nil, login_hint: nil, provider: nil, connection: nil, organization: nil, state: '') ⇒ String

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

‘GoogleOAuth’, and ‘MicrosoftOAuth’ are supported. rubocop:disable Metrics/ParameterLists

Examples:

WorkOS::SSO.authorization_url(
  connection: 'conn_123',
  client_id: 'project_01DG5TGK363GRVXP3ZS40WNGEZ',
  redirect_uri: 'https://workos.com/callback',
  state: {
    next_page: '/docs'
  }.to_s
)

=> "https://api.workos.com/sso/authorize?connection=conn_123" \
   "&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:

  • redirect_uri (String) —

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

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

    The WorkOS client ID for the environment where you’ve configured your SSO connection.

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

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

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

    A provider name for an Identity Provider configured on your WorkOS dashboard. Only ‘AppleOAuth’, ‘GitHubOAuth’,

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

    The ID for a Connection configured on WorkOS.

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

    The ID for an Organization configured on WorkOS.

  • state (String) (defaults to: '') —

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

Returns:

  • (String) 


56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/workos/sso.rb', line 56

def authorization_url(
  redirect_uri:,
  client_id: nil,
  domain: nil,
  domain_hint: nil,
  login_hint: nil,
  provider: nil,
  connection: nil,
  organization: nil,
  state: ''
)
  if domain
    warn_deprecation '[DEPRECATION] `domain` is deprecated.
    Please use `organization` instead.'
  end

  validate_authorization_url_arguments(
    provider: provider,
    domain: domain,
    connection: connection,
    organization: organization,
  )

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

  "https://#{WorkOS.config.api_hostname}/sso/authorize?#{query}"
end

.delete_connection(id:) ⇒ Bool

Delete a Connection

Examples:

WorkOS::SSO.delete_connection(id: 'conn_02DRA1XNSJDZ19A31F183ECQW9')
=> true

Parameters:

  • id (String) —

    Connection unique identifier

Returns:

  • (Bool) —

    • returns ‘true` if successful



203
204
205
206
207
208
209
210
211
212
 
# File 'lib/workos/sso.rb', line 203

def delete_connection(id:)
  request = delete_request(
    auth: true,
    path: "/connections/#{id}",
  )

  response = execute_request(request: request)

  response.is_a? Net::HTTPSuccess
end

.get_connection(id:) ⇒ WorkOS::Connection

Get a Connection

Examples:

WorkOS::SSO.get_connection(id: 'conn_02DRA1XNSJDZ19A31F183ECQW9')
=> #<WorkOS::Connection:0x00007fb6e4193d20
      @id="conn_02DRA1XNSJDZ19A31F183ECQW9",
      @name="Foo Corp",
      @connection_type="OktaSAML",
      @domains=
       [{:object=>"connection_domain",
         :id=>"domain_01E6PK9N3XMD8RHWF7S66380AR",
         :domain=>"example.com"}]>

Parameters:

  • id (String) —

    Connection unique identifier

Returns:



183
184
185
186
187
188
189
190
191
192
 
# File 'lib/workos/sso.rb', line 183

def get_connection(id:)
  request = get_request(
    auth: true,
    path: "/connections/#{id}",
  )

  response = execute_request(request: request)

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

.get_profile(access_token:) ⇒ Object

rubocop:enable Metrics/ParameterLists



96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/workos/sso.rb', line 96

def get_profile(access_token:)
  response = execute_request(
    request: get_request(
      path: '/sso/profile',
      auth: true,
      access_token: access_token,
    ),
  )

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

.list_connections(options = {}) ⇒ Hash

Retrieve connections.

Parameters:

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

    An options hash

Options Hash (options):

  • connection_type (String) —

    Authentication service provider descriptor.

  • domain (String) —

    The domain of the connection to be retrieved.

  • organization_id (String) —

    The id of the organization of the connections to be retrieved.

  • limit (String) —

    Maximum number of records to return.

  • order (String) —

    The order in which to paginate records

  • before (String) —

    Pagination cursor to receive records before a provided Connection ID.

  • after (String) —

    Pagination cursor to receive records before a provided Connection ID.

Returns:

  • (Hash) 


146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/workos/sso.rb', line 146

def list_connections(options = {})
  options[:order] ||= 'desc'
  response = execute_request(
    request: get_request(
      path: '/connections',
      auth: true,
      params: options,
    ),
  )

  parsed_response = JSON.parse(response.body)
  connections = parsed_response['data'].map do |connection|
    ::WorkOS::Connection.new(connection.to_json)
  end

  WorkOS::Types::ListStruct.new(
    data: connections,
    list_metadata: parsed_response['listMetadata'],
  )
end

.profile_and_token(code:, client_id: nil) ⇒ WorkOS::ProfileAndToken

Fetch the profile details for the authenticated SSO user.

Parameters:

  • code (String) —

    The authorization code provided in the callback URL

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

    The WorkOS client ID for the environment where you’ve configured your SSO connection

Returns:



115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/workos/sso.rb', line 115

def profile_and_token(code:, client_id: nil)
  body = {
    client_id: client_id,
    client_secret: WorkOS.config.key!,
    grant_type: 'authorization_code',
    code: code,
  }

  response = client.request(post_request(path: '/sso/token', body: body))
  check_and_raise_profile_and_token_error(response: response)

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