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, you choose the level of trust: first-party or third-party.

Select first-party when the application is one that your team controls, such as supporting services that are deployed separately from your main application but still need access to your users’ identities. Examples include community forums or customer support portals.

Select third-party when the application is one built by your customers or partners, but you do not directly control the integrating application. For this reason, you must also associate third-party applications with an Organization that represents the customer or partner.

A third-party OAuth application will generally have a “Sign in with [your application]” button on their login page, in the same way many sites have a “Sign in with Google” button, allowing you to offer similar functionality to your customers or partners. Unlike first-party applications, your users will be 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, you can configure an OAuth application 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.

Your application must verify the tokens sent by OAuth applications using the JWKS for your 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, you can use the Token Introspection API to synchronously check whether a token is still valid.

OAuth applications require the following configuration:

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

For third-party OAuth applications, the name and logo will be displayed to your 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