Enterprise sign-in with WorkOS

​WorkOS is a platform to make your app enterprise-ready, quickly adding common features like SSO/SAML, Directory Sync, Audit Trail, and more. It's like "Stripe for enterprise features."
In this recipe, I’ll show you how to integrate a ScaffoldHub generated application with WorkOS.
For the sake of this recipe, I’ll use the G Suite and Okta single sign-on integrations, but WorkOS allows you to integrate with many other providers.
Thanks to WorkOS, from the ScaffoldHub perspective, what differs from one provider to another is only the domain variable we send to WorkOS.
The integrated application
The integrated application will have those two ways of sign-in/sign-up:
Okta
G Suite
This ensures that your application is only available for your enterprise users.
Okta
GSuite
ScaffoldHub Users
GitHub repository
Repository:
https://github.com/scaffoldhub/documentation/tree/master/recipes/workos
github.com
Differences:
https://github.com/scaffoldhub/documentation/commit/0d452d4f1872c964dcc14f57df8f8ba4626f1ff9
github.com
If you own a ScaffoldHub license and don't have access to the repository yet, please email us at [email protected] with your GitHub profile.
Requirements
Please follow the Setup section and make sure your application is up and running on the localhost.
Create a WorkOS account
Go to https://workos.com/ and create a new account.
Single Sign-On (SAML) setup
Once you sign-in, on the Single Sign-On (SAML), click on Get Started.
Install the WorkOS SDK
Open a new console at the backend folder of your project and run:
1
npm install --save @workos-inc/node
Copied!
Add your SSO Redirects URIs
Add this as the Redirect URI: 
​http://localhost:8080/api/workos/callback​
We will configure this callback later.
Set up your Identity Providers
​
Configuring the backend
This section describes the changes needed on the backend for the integration. The direction of changes is from the API -> Database.
Environment Variables
First things first, we must set the environment variables with the WorkOS configuration.
More about WorkOS keys: https://workos.com/docs/keys.
1
WORKOS_SECRET_KEY = "..."
2
WORKOS_PROJECT_ID = "..."
3
WORKOS_REDIRECT_URI = "http://localhost:8080/api/workos/callback"
Copied!
Endpoints
backend/src/api/workos/workosSignIn.ts
The sign-in endpoint is responsible for getting the authorization URL of the provider - G Suite, Okta, etc - and redirect the user to its sign-in page.
Note the req.query.domain that receives the domain the user wants to authenticate from the front-end.
1
import ApiResponseHandler from '../apiResponseHandler';
2
import WorkOS from '@workos-inc/node';
3
import { getConfig } from '../../config';
4
import { databaseCloseIfIndividualConnectionPerRequest } from '../../database/databaseConnection';
5
​
6
const client = new WorkOS(getConfig().WORKOS_SECRET_KEY);
7
​
8
export default async (req, res) => {
9
  try {
10
    const url = client.sso.getAuthorizationURL({
11
      domain: req.query.domain,
12
      redirectURI: getConfig().WORKOS_REDIRECT_URI,
13
      projectID: getConfig().WORKOS_PROJECT_ID,
14
    });
15
​
16
    // This is unrelated to WorkOS, but because we are not calling
17
    // the ApiResponseHandler, we must close the database connection
18
    // if needed
19
    await databaseCloseIfIndividualConnectionPerRequest(
20
      req,
21
    );
22
​
23
    res.redirect(url);
24
  } catch (error) {
25
    await ApiResponseHandler.error(req, res, error);
26
  }
27
};
Copied!
backend/src/api/workos/workosCallback.ts
The callback endpoint receives a code that enables us to fetch the user profile of the authenticated user. This allows us to find or create the user on our database using the WorkOS information: https://workos.com/docs/sso/api-reference#example-response.
The AuthService.signinWithWorkos method performs the operations needed on the database and returns a JWT token.
The user is then redirected to the frontend page with the auth token.
If an error occurs, it is redirected to the application sign-in page with the error message passed as a parameter.
1
import WorkOS from '@workos-inc/node';
2
import { getConfig } from '../../config';
3
import { databaseCloseIfIndividualConnectionPerRequest } from '../../database/databaseConnection';
4
import AuthService from '../../services/auth/authService';
5
​
6
const client = new WorkOS(getConfig().WORKOS_SECRET_KEY);
7
​
8
export default async (req, res) => {
9
  try {
10
    const { code } = req.query;
11
    const profile = await client.sso.getProfile({
12
      code,
13
      projectID: getConfig().WORKOS_PROJECT_ID,
14
    });
15
​
16
    const authToken = await AuthService.signinWithWorkos(
17
      profile,
18
      req,
19
    );
20
​
21
    await databaseCloseIfIndividualConnectionPerRequest(
22
      req,
23
    );
24
​
25
    res.redirect(
26
      `${
27
        getConfig().FRONTEND_URL
28
      }?workos=true&authToken=${authToken}`,
29
    );
30
  } catch (error) {
31
    res.redirect(
32
      `${
33
        getConfig().FRONTEND_URL
34
      }/auth/sign-in?errorMessage=${encodeURIComponent(
35
        error.message,
36
      )}`,
37
    );
38
  }
39
};
40
​
Copied!
backend/src/api/workos/workosOnboard.ts
This is specific to ScaffoldHub, but once a user is created, it must pass through the onboarding process, where it joins the user on the workspace.
1
import ApiResponseHandler from '../apiResponseHandler';
2
import AuthService from '../../services/auth/authService';
3
​
4
export default async (req, res, next) => {
5
  try {
6
    const payload = await AuthService.handleOnboard(
7
      req.currentUser,
8
      req.body.invitationToken,
9
      req.body.tenantId,
10
      req,
11
    );
12
​
13
    await ApiResponseHandler.success(req, res, payload);
14
  } catch (error) {
15
    await ApiResponseHandler.error(req, res, error);
16
  }
17
};
Copied!
backend/src/api/workos/index.ts
We must declare the endpoints we created at the workos/index.ts file.
1
export default (app) => {
2
  app.get(
3
    `/workos/callback`,
4
    require('./workosCallback').default,
5
  );
6
  app.get(
7
    `/workos/sign-in`,
8
    require('./workosSignIn').default,
9
  );
10
  app.post(
11
    `/workos/onboard`,
12
    require('./workosOnboard').default,
13
  );
14
};
Copied!
backend/src/api/index.ts
And also add the WorkOS index to the main API index. 
1
...
2
require('./workos').default(routes);
3
...
Copied!
backend/src/api/auth/index.ts
We will no longer use the standard email/password sign-up, so remove those routes.
Authentication Service
Once we have the profile of the authenticated user, we must fetch them from the database using the email, which is the unique key for the user.
If the user has one email, but a differentworkosId, it means that the user is trying to sign-in using a different provider from the first one he used.
If the user does not exist on the database yet, we must create it.
The application then generates a JWT token and returns it to the endpoint.
backend/src/services/auth/authService.ts
SQL
MongoDB
1
  /**
2
   * Signs in a user from WorkOS.
3
   * @param {*} email
4
   * @param {*} password
5
   * @param {*} [options]
6
   */
7
  static async signinWithWorkos(
8
    profile,
9
    options: any = {},
10
  ) {
11
    const transaction = await SequelizeRepository.createTransaction(
12
      options.database,
13
    );
14
​
15
    try {
16
      let user = await UserRepository.findByEmail(
17
        profile.email,
18
        options,
19
      );
20
​
21
      if (user && user.workosId !== profile.id) {
22
        throw new Error400(
23
          options.language,
24
          'auth.invalidProvider',
25
        );
26
      }
27
​
28
      if (!user) {
29
        user = await UserRepository.createFromWorkos(
30
          profile,
31
          options,
32
        );
33
      }
34
​
35
      const token = jwt.sign(
36
        { id: user.id },
37
        getConfig().AUTH_JWT_SECRET,
38
        { expiresIn: getConfig().AUTH_JWT_EXPIRES_IN },
39
      );
40
​
41
      await SequelizeRepository.commitTransaction(
42
        transaction,
43
      );
44
​
45
      return token;
46
    } catch (error) {
47
      await SequelizeRepository.rollbackTransaction(
48
        transaction,
49
      );
50
​
51
      throw error;
52
    }
53
  }
Copied!
1
  /**
2
   * Signs in a user from WorkOS.
3
   * @param {*} email
4
   * @param {*} password
5
   * @param {*} [options]
6
   */
7
  static async signinWithWorkos(
8
    profile,
9
    options: any = {},
10
  ) {
11
    const session = await MongooseRepository.createSession(
12
      options.database,
13
    );
14
​
15
    try {
16
      let user = await UserRepository.findByEmail(
17
        profile.email,
18
        options,
19
      );
20
​
21
      if (user && user.workosId !== profile.id) {
22
        throw new Error400(
23
          options.language,
24
          'auth.invalidProvider',
25
        );
26
      }
27
​
28
      if (!user) {
29
        user = await UserRepository.createFromWorkos(
30
          profile,
31
          options,
32
        );
33
      }
34
​
35
      const token = jwt.sign(
36
        { id: user.id },
37
        getConfig().AUTH_JWT_SECRET,
38
        { expiresIn: getConfig().AUTH_JWT_EXPIRES_IN },
39
      );
40
​
41
      await MongooseRepository.commitTransaction(session);
42
​
43
      return token;
44
    } catch (error) {
45
      await MongooseRepository.abortTransaction(session);
46
​
47
      throw error;
48
    }
49
  }
Copied!
Create User from WorkOS profile
After successful sign-in, WorkOS returns a profile object with the information of the user: 
With this information, we can create a user on the database.
backend/src/database/repositories/userRepository.ts
SQL
MongoDB
1
  /**
2
 * Creates the user based on the auth information.
3
 *
4
 * @param {*} data
5
 * @param {*} [options]
6
 */
7
static async createFromWorkos(profile, options) {
8
  let data = {
9
    email: profile.email,
10
    firstName: profile.first_name,
11
    lastName: profile.last_name,
12
    workosId: profile.id,
13
  };
14
​
15
  const transaction = SequelizeRepository.getTransaction(
16
    options,
17
  );
18
​
19
  const user = await options.database.user.create(data, {
20
    transaction,
21
  });
22
​
23
  delete user.password;
24
  await AuditLogRepository.log(
25
    {
26
      entityName: 'user',
27
      entityId: user.id,
28
      action: AuditLogRepository.CREATE,
29
      values: {
30
        ...user.get({ plain: true }),
31
      },
32
    },
33
    options,
34
  );
35
​
36
  return this.findById(user.id, {
37
    ...options,
38
    bypassPermissionValidation: true,
39
  });
40
}
Copied!
1
/**
2
 * Creates the user based on the WorkOS profile.
3
 *
4
 * @param {*} profile
5
 * @param {*} [options]
6
 */
7
static async createFromWorkos(profile, options) {
8
  let data = {
9
    email: profile.email,
10
    firstName: profile.first_name,
11
    lastName: profile.last_name,
12
    workosId: profile.id,
13
  };
14
​
15
  data = this._preSave(data);
16
​
17
  let [user] = await User(options.database).create(
18
    [data],
19
    MongooseRepository.getSessionOptionsIfExists(options),
20
  );
21
​
22
  await AuditLogRepository.log(
23
    {
24
      entityName: 'user',
25
      entityId: user.id,
26
      action: AuditLogRepository.CREATE,
27
      values: user,
28
    },
29
    options,
30
  );
31
​
32
  return this.findById(user.id, {
33
    ...options,
34
    bypassPermissionValidation: true,
35
  });
36
}
Copied!
Add workosId to User
For the integration to work, we must relate the WorkOS user to the user on the database. We will use the workosId for this relation.
backend/src/database/models/user.ts
SQL
MongoDB
1
...
2
workosId: {
3
  type: DataTypes.STRING(255),
4
  allowNull: true,
5
},
6
...
Copied!
1
...
2
workosId: {
3
  type: String,
4
  maxlength: 255,
5
},
6
...
Copied!
SQL note: If you already have the database created, you must also create this field on the database.
Configuring the frontend
For this example, I'm using the React Ant Design version, but the concept is the same for all versions.
Sign-in page
The key here is the buttons that redirect the user to the WorkOS sign-in endpoint:
1
`${config.backendUrl}/workos/sign-in?domain=foo-corp.com`
Copied!
The domain for each button must correspond to the ones you configured on the WorkOS platform.
Note that it also checks for the errorMessage on the query and displays it to the user in case it exists.
1
import { Button } from 'antd';
2
import React, { useEffect } from 'react';
3
import { useSelector } from 'react-redux';
4
import config from 'src/config';
5
import { i18n } from 'src/i18n';
6
import selectors from 'src/modules/auth/authSelectors';
7
import Content from 'src/view/auth/styles/Content';
8
import Logo from 'src/view/auth/styles/Logo';
9
import Wrapper from 'src/view/auth/styles/Wrapper';
10
import I18nFlags from 'src/view/layout/I18nFlags';
11
import queryString from 'query-string';
12
import Message from 'src/view/shared/message';
13
import { useLocation } from 'react-router-dom';
14
​
15
const SigninPage = (props) => {
16
  const location = useLocation();
17
  const backgroundImageUrl = useSelector(
18
    selectors.selectBackgroundImageUrl,
19
  );
20
  const logoUrl = useSelector(selectors.selectLogoUrl);
21
  const { errorMessage } = queryString.parse(
22
    location.search,
23
  );
24
​
25
  useEffect(() => {
26
    if (errorMessage) {
27
      Message.error(errorMessage);
28
    }
29
    // eslint-disable-next-line react-hooks/exhaustive-deps
30
  }, []);
31
​
32
  return (
33
    <Wrapper
34
      style={{
35
        backgroundImage: `url(${
36
          backgroundImageUrl || '/images/signin.jpg'
37
        })`,
38
      }}
39
    >
40
      <Content>
41
        <Logo>
42
          {logoUrl ? (
43
            <img
44
              src={logoUrl}
45
              width="240px"
46
              alt={i18n('app.title')}
47
            />
48
          ) : (
49
            <h1>{i18n('app.title')}</h1>
50
          )}
51
        </Logo>
52
​
53
        <Button
54
          size="large"
55
          block
56
          href={`${config.backendUrl}/workos/sign-in?domain=foo-corp.com`}
57
          type="primary"
58
        >
59
          {i18n('auth.okta')}
60
        </Button>
61
​
62
        <Button
63
          style={{ marginTop: '16px' }}
64
          size="large"
65
          block
66
          href={`${config.backendUrl}/workos/sign-in?domain=scaffoldhub.io`}
67
        >
68
          {i18n('auth.gsuite')}
69
        </Button>
70
​
71
        <I18nFlags
72
          style={{
73
            marginTop: '24px',
74
          }}
75
        />
76
      </Content>
77
    </Wrapper>
78
  );
79
};
80
​
81
export default SigninPage;
82
​
Copied!
Don't forget to add the I18n labels on the I18n files.
Onboard
After the user creation, it must pass through an onboard process, where he joins the tenant or accepts and invitation.
On the frontend, we must do those modifications:
frontend/src/index.tsx
1
import React from 'react';
2
import ReactDOM from 'react-dom';
3
import { i18n, init as i18nInit } from 'src/i18n';
4
import { AuthToken } from './modules/auth/authToken';
5
import TenantService from './modules/tenant/tenantService';
6
import SettingsService from './modules/settings/settingsService';
7
import AuthService from './modules/auth/authService';
8
​
9
(async function () {
10
  const isWorkosOnboardRequested = AuthService.isWorkosOnboardRequested();
11
  AuthToken.applyFromLocationUrlIfExists();
12
  await TenantService.fetchAndApply();
13
  if (isWorkosOnboardRequested) {
14
    await AuthService.workosOnboard();
15
  }
16
  SettingsService.applyThemeFromTenant();
17
  await i18nInit();
18
​
19
  document.title = i18n('app.title');
20
  const App = require('./App').default;
21
  ReactDOM.render(<App />, document.getElementById('root'));
22
})();
23
​
Copied!
frontend/src/modules/auth/authService.tsx
1
//...
2
​
3
static async workosOnboard() {
4
  const invitationToken = AuthInvitationToken.get();
5
​
6
  const response = await authAxios.post(
7
    '/workos/onboard',
8
    {
9
      invitationToken,
10
      tenantId: tenantSubdomain.isSubdomain
11
        ? AuthCurrentTenant.get()
12
        : undefined,
13
    },
14
  );
15
​
16
  AuthInvitationToken.clear();
17
​
18
  return response.data;
19
}
20
​
21
static isWorkosOnboardRequested() {
22
  const urlParams = new URLSearchParams(
23
    window.location.search,
24
  );
25
​
26
  return Boolean(urlParams.get('workos'));
27
}
28
​
29
//...
Copied!
Test your integration
At this point, you have probably already tested the integration via the application, but you can also run this on the WorkOS setup process, and it will work.
Finish
Well done, your application is now enterprise-ready.