Add SSO to Your Ruby on Rails App Using WorkOS

November 19, 2021

If your SaaS product’s backend is built with Ruby on Rails and you want to add SSO functionality for your customers, you can do a dry-run of the SSO integration using our example Ruby on Rails app. It makes use of the WorkOS Ruby SDK to authenticate users via SSO, and is built with Bootstrap, Webpack, and Devise.

If you get stuck while following the steps below and aren't able to resolve the issue by reading our API reference or SSO Setup Guide, please reach out to us at [email protected] so we can help!


Clone the Ruby on Rails app

1. In your CLI, navigate to the directory into which you want to clone the Ruby example app git repo:

2. Clone the main Ruby example app repo:

3. Navigate to the Ruby on Rails SSO example app, located within the cloned repo:

4.  Install the dependencies:

5. Migrate the database:

Securely store the environment variables

6. Obtain and make note of your WorkOS API key and SSO-specific, WorkOS Client ID from the WorkOS Dashboard. The locations of these values are shown in the screenshots below.

7. Run this command to copy the example app’s .env file to ruby-example-applications/ruby-rails-sso-example on your own machine:

8. Open the new .env file with your preferred text editor and replace the placeholder values for WORKOS_API_KEY and WORKOS_CLIENT_ID:

The .env file is listed in this repo's .gitignore file, so your sensitive information will not be checked into version control. This is an important consideration for keeping sensitive information ,such as API keys, private.

The workos gem will read your API key and Client ID from the .env file. Alternatively, you can set the API key and Client ID yourself by adding `WorkOS.key = $YOUR_API_KEY` and `CLIENT_ID = $YOUR_CLIENT_ID` to the sessions_controller.rb file.

Test the server

9. To ensure the example app is served as expected at this stage, start the server:

10. Navigate to http://localhost:5000. You should see a webpage that offers both email-based and SSO-based login options.

11. If you enter a domain in the text field on the right and click the “Sign in with SSO” button, you will see an error page if you haven’t properly configured SSO in the WorkOS dashboard yet. We’ll do the configuration in the next section. For now, stop the server by typing CTRL + c in the CLI.

Set up SSO with WorkOS

12. Create an Organization and an SSO Connection within the Organization in your WorkOS Dashboard.

13. Add http://localhost:5000/sso/callback as a Redirect URI in the Configuration section of the Dashboard. Ensure it is set as the default.

Test the integration

14. Start the server again by running this command in the CLI:

15. Navigate to http://localhost:5000/. On the right side, you’ll see the option to login with SSO. In the corresponding text field, enter the domain of the Organization you added to the WorkOS dashboard (not the whole email address, just the domain). Click the “Sign in with SSO” button. You’ll be prompted to sign in using the identity provider (IdP) you configured during the SSO setup.

16. Once you’re signed in, the webpage will display a JSON object containing the user information for the logged-in user.

Nice work! You just set up SSO for your Ruby on Rails app!

Need help?

If you get stuck while following the steps below and aren't able to resolve the issue by reading our API reference or SSO Setup Guide, please reach out to us at [email protected] so we can help!

Start Integrating Today
Create an account to begin adding enterprise-ready features to your application today.
Get Started

This site uses cookies to improve your experience. Please accept the use of cookies on this site. You can review our cookie policy here and our privacy policy here. If you choose to refuse, functionality of this site will be limited.