Single Sign-On

Embed WorkOS.js

Learn how to offer a seamless workflow for users configuring SSO connections

Overview

WorkOS.js allows your end-users to set up and configure SSO connections, all without leaving your application.

This creates a seamless "self-serve" process for upgrading users to SSO, and removes the complex back-and-forth communication otherwise required. It's the fastest and easiest way to get your enterprise users signing in with SSO.

To use WorkOS.js, you'll need to know your Publishable Key. You'll also need to supply the specific domain of an enterprise customer who is creating the new Identity Provider connection. Let's get started.

Set up the Element

Add the script to your application's website.

index.html

file_copy
<script src="https://js.workos.com/v1"></script>

Add a DOM element with the class workos-container where you would like the button to render.

index.html

file_copy

<div
  class='workos-container'
  data-prop-app-name='My Awesome App'
  data-prop-domain='{foo-corp.com}'
  data-prop-name='FooCorp'
  data-prop-publishable-key='{publishableKey}'
/>

Data Attributes

The data attributes passed to the element are comprised of your Publishable Key and the name and domain of the Enterprise client. These attributes are required and kebab-cased.

  • data-prop-publishable-key: Your Publishable Key from the WorkOS Dashboard.

  • data-prop-domain: The primary domain for the current Enterprise account.

  • data-prop-name: An identifier string for the Enterprise account.

  • data-prop-app-name: The name of your application for display within the configuration window. This is displayed to your users.

Confirm new connections with a server-side request

Your Publishable Key is exposed on the frontend of your application. To provide additional security, all actions taken from within WorkOS.js must be confirmed with a server-side API call from your application.

WorkOS.js dispatches a custom event to the parent window when your Enterprise client configures their IdP. This event, workos:providerLinked, will include a token that you must pass to your backend. Subscribe to this event and pass the token to your API.

Subscribe to workos:providerLinked event

file_copy

<script type='text/javascript'>
  document.addEventListener('workos:providerLinked', function (event){
    var xhr = new XMLHttpRequest();
    xhr.open("POST", '/confirm', true);
    xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
    xhr.send("token=" + event.detail.token);
  })
</script>

Confirm the pending connection configuration with a server-side API call authenticated with your Secret Key using a WorkOS SDK for your server.

Confirm pending connection

file_copy

post '/confirm' do
  WorkOS::SSO.promote_draft_connection(
    token: params['token'],
  )
end

View the Connection in your Dashboard.