Skip to main content

Extension authentication

After a user has enabled an extension for their account. They'll likely navigate to the extension to configure it. To do so they might go to a website created by the extension developer. That website will ask them to log in with their Platform Identity. This will direct them to your Authress managed login page to log in.

Your users will want to log in to these third party built solutions, using their platform identity. The user's platform identity comes from logging in using SSO via your Authress account. Instead of your users logging into your platform, here the users will log into the extension portal. The extension identity is mapped from the user's existing platform identity.

The user's extension identity is used by the extension to verify they are who they say they are, and the extension developers will do this verification using the exact same JWT verification that you do in your services to verify Authress JWTs. The JWT verification can be easily done using the verifyToken method or the TokenVerifier class found in each of the Authress SDKs. (See verifying Authress JWTs for more information.)

Specifically the difference between the platform identity JWT and the extension identity JWT is the issuer claim in the token.

  • User's platform identity JWT issuer: https://auth.yourdomain.com
  • Extension identity JWT issuer: https://auth.yourdomain.com/api/extensions/ext_001

This prevents accidental usage of the extension JWTs within your platform. When the extension wants to request access to your platform's data on behalf of the customer account. The extension will generate a JWT using their service client and the generated API access token they received when creating the extension.

Extensions logging users in​

Extension authentication is OAuth2.1 compliant, and the Authress Login SDK makes this easy for your extension developers to build a UI that enables login via your platform identities. Follow the Authress OAuth API documentation or use this quick setup recommendation for your extension developers to enable login with your platform. We recommend wrapping this code snippet in a custom UI library that you can distribute or providing clear API documentation that matches the OAuth code samples that are in our OAuth API documentation:

Extension UI user login example
import { ExtensionClient } from '@authress/login';

const extensionClient = new ExtensionClient('https://login.application.io', extensionId);

// redirectUrl is where the extension would like to return the user to after login
// * This method will redirect the user to the Authress Login UI screen with an auth code
const { accessToken } = await extensionClient.login(redirectUrl);

// .... After login the user is redirected to the redirectUrl
// * So try the login again:
const { accessToken } = await extensionClient.login(redirectUrl);

// * Or get the user claims from the token
await userData = await this.getUserIdentity();

Extensions accessing user data​

For your extension developers to use these access tokens to call your API, Authress recommends building your SDK. There are instructions for doing this in the building a client SDK section.

The relevant code snippet from that guide is:

Your client SDK (or CLI)
import { ServiceClientTokenProvider } from '@authress/sdk';

// Configure the custom domain: https://authress.io/app/#/settings?focus=domain
const authressCustomDomainUrl = 'https://auth.yourdomain.com';

class myApplicationServiceClient {
  // The customersSecretAccessToken is the private key you generated from Authress
  // to give to your customer as an API key.
  // Generate these by creating a service client and access key at:
  // https://authress.io/app/#/api?route=post-/v1/clients/-clientId-/access-keys
  async sdkApiCall() {
    const tokenProvider = new ServiceClientTokenProvider(
      customersSecretAccessToken, authressCustomDomainUrl);
    const token = await tokenProvider.getToken();
    const headers = { Authorization: `Bearer ${token}` };
    return httpClient.get(url, headers);
  }
}