OAuth Applications

OAuth applications are designed for applications where the actor being authenticated is a User. These include web applications, mobile, desktop, and CLI tools. OAuth applications use the underlying authorization_code OAuth flow which is supported by many libraries and frameworks out of the box.

When creating OAuth applications, the level of trust is chosen: first-party or third-party.

First-party is the appropriate choice when the application is one that the team controls, such as supporting services deployed separately from the main application that still need access to user identities. Examples include community forums or customer support portals.

Third-party is the appropriate choice when the application is one built by customers or partners, where the integrating application is not directly controlled. For this reason, third-party applications must also be associated with an Organization that represents the customer or partner.

A third-party OAuth application will generally have a “Sign in with [the application]” button on its login page, in the same way many sites have a “Sign in with Google” button, allowing similar functionality to be offered to customers or partners. Unlike first-party applications, users are prompted in AuthKit to explicitly authorize the application before their identity is shared.

After an application has been issued credentials from a Connect Application, it can receive identity and access tokens using the OAuth 2.0 authorization_code flow.

Many OAuth and OIDC libraries support Connect applications out of the box, needing only configuration:

import * as client from 'openid-client';
import { Strategy as OidcStrategy } from 'openid-client/passport';
import * as passport from 'passport';

const config = await client.discovery(
  'https://<subdomain>.authkit.app',
  process.env.OAUTH_APP_CLIENT_ID,
  process.env.OAUTH_APP_CLIENT_SECRET,
);

passport.use(
  new OidcStrategy(
    {
      config,
      scope: 'openid profile email offline_access',
    },
    (_tokenset, _userinfo, _done) => {
      // Your code to persist tokenset and retrieve user info
    },
  ),
);

By default, OAuth applications are confidential and must authenticate with a client secret when exchanging authorization codes for tokens. However, certain types of applications cannot securely store client secrets, such as command-line tools or mobile applications.

For these use cases, an OAuth application can be configured as Public. Public applications:

• Cannot securely store client secrets
• Must use Proof Key for Code Exchange (PKCE) in order to authenticate with the Token Endpoint

OAuth applications can be set as Public during creation in the WorkOS Dashboard.

The application must verify the tokens sent by OAuth applications using the JWKS for the environment. User information in the token can be used to look up related resources and perform further access control checks.

import { jwtVerify, createRemoteJWKSet } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://<subdomain>.authkit.app/oauth2/jwks'));

const bearerTokenMiddleware = async (req, res, next) => {
  const authHeader = req.headers.authorization;
  const token = authHeader?.match(/^Bearer (.+)$/)?.[1];

  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }

  try {
    const { payload } = await jwtVerify(token, JWKS, {
      issuer: 'https://<subdomain>.authkit.app',
      audience: 'client_123456789',
    });

    req.user = await findUserById(payload.sub);

    next();
  } catch (err) {
    return res.status(401).json({ error: 'Invalid token' });
  }
};

// Example protected route
app.get('/api/protected', bearerTokenMiddleware, (req, res) => {
  res.json({ data: 'Protected resource', user: req.user });
});

In addition to fast stateless verification, the Token Introspection API can be used to synchronously check whether a token is still valid.

When a user who is a member of multiple Organizations authorizes an OAuth Application, they will be prompted to select one of their Organizations to grant access to. Or, if the user only has a single Organization membership, that Organization will be automatically selected.

The selected Organization is made available as the org_id claim in the issued access token, which the application can use to scope the access of requests made using the token.

OAuth applications require the following configuration:

This is the final location users are redirected to after successful authentication. Clients use the Token Endpoint to exchange the code for tokens at this location.

For third-party OAuth applications, the name and logo are displayed to users when they are prompted to authorize access. Both light and dark-mode logos are supported.

OAuth applications use the client_id and client_secret from a credential to authenticate to the OAuth-based Connect APIs.

• Connect API Reference – Complete API documentation