Skip to main content

Custom connection setup guide - Part 3

This guide details how to hook up an internally managed identity provider to Authress to enable consistent token generation. In the case you want to connect a public federated provider instead, follow one of these guides:

An internally managed identity provider usually exists in a legacy platform. You have some architecture today to verify users and generate user identity tokens. If these tokens are already OIDC compliant and are signed by an asymmetric algorithm, then you should follow the Connecting a non-standard public identity provider guide.

This avoids the need for your applications to interoperate between two types of tokens--the ones that Authress generates, and the ones being generated by your legacy identity provider.

Background: The Authress login flow​

The standard Authress login flow, starts in your web app. The user requests to login, which generates a login request using one of your configured Authress connections. The connectionId and applicationId are passed to the login SDK. This is the same flow your application is already using to login with Authress, and it will be reused for your legacy identity provider, so no changes are necessary to your web app. As a reminder these are the relevant SDK methods:

(Application UI) Log user in
import { LoginClient } from '@authress/login';
const loginClient = new LoginClient({
  // Both of these properties can be found and configured at:
  // https://authress.io/app/#/manage?focus=applications
  authressLoginHostUrl: 'https://auth.yourdomain.com',
  applicationId: 'YOUR_APPLICATION_ID'
});

// This will redirect the user to the specified connection login UI,
// track their session with Authress, and then redirect back to your specified
// redirectUrl. By default we redirect users back to where they started,
// however, usually you’ll want to specify the next location they should go.
await loginClient.authenticate({
  connectionId: 'SELECTED_CONNECTION_ID', redirectUrl: window.location.href
});

// Once the user returns to your site, you’ll want to get the necessary credentials.
// These should always be fetched by using the token getter:
const userToken = await loginClient.getToken();

// The full flow is
// 1. Check if the user is logged in on every page.
//     * If not, redirect them to the login page, a route guard is standard.
//     * If there are credentials, get the token => Done.
// 2. Ask the user to select connection/provider, call authenticate
// 3. Get the token from the SDK when you need it
//     * and pass it in the Authorization header in HTTP API requests.

const isUserLoggedIn = await loginClient.userSessionExists();
if (!isUserLoggedIn) {
  window.location.assign('/login');
} else {
  const userToken = await loginClient.getToken();
}

// If route === 'Login'
await loginClient.authenticate({
  connectionId: 'SELECTED_CONNECTION_ID', redirectUrl: window.location.href
});

// After redirect, same check, but now we'll have the token.
const isUserLoggedIn = await loginClient.userSessionExists();
if (!isUserLoggedIn) {
  window.location.assign('/login');
} else {
  const userToken = await loginClient.getToken();
}

1. Linking your identity provider​

To link the identity provider to Authress, a new special kind of connection will be created. This connection treats your existing identity provider with advanced permissions allowing it to request Authress identity tokens.

Generate a new Authress Service Client. Enter a name for the client, and select the option to Enable custom Authress user token generation. This allows this client to directly communicate with the Authress login API to request user identity tokens.

Enable the legacy authorization service

info

You will note a big warning in doing this in the page. This is convey the additional importance in granting the service client this ability. By default most Authess accounts will not to enable this functionality and so a warning exists in the app to deter enabling it there. However, if you are reading this guide then this is the correct procedure. The reason for this security banner is because it essentially will grant this service client Authress-Level privileges when it comes to authentication. Irrespective of the security you use to govern other credentials, such as service client access keys, make sure to take the utmost protections possible with this one.

2. Enter your legacy identity provider URL​

Your identity provider has a UI associated with identifying the user. This may be a username/password prompt or an email prompt requesting the user's email for a magic login token based flow. Set the Authorization Url to be this URL.

Create a legacy authress connection

At this point, it is recommended that you click Test Connection to ensure that the redirect to your identity provider is correct.

3. User agent flow​

When the user client logs in and the Authress Login SDK is invoked via the loginClient.authenticate() method, the user will be redirected to the specific URL from #2 above. They'll begin the flow, whatever this may be. In the case of username/password or a magic token, you'll use the existing logic to direct and navigate the user to the appropriate location. The result of their interactions must be a request to your existing identity service:

  • In the case of username/password, send the username and password to your identity service. The identity service should verify the user's credentials and then generate an Authress assertion to continue the login process.
  • In the case of a magic token, the user should be directed to retrieve the token, and then redirected back your identity UI. The UI should pass the token to your identity service to be verified. Once verified, the service will then generate an Authress assertion to continue the login process.

Important: Authress will send a state parameter to your Authorization URL. This state parameter must be passed back to Authress in the next step. This token is not sensitive and should not be treated as a replacement for a secure identity.

4. Generating the Authress Assertion​

Once the user's identity has been verified, the identity service is ready to hand-off the user to Authress to complete the login flow. This can be done using the generateUserLoginUrl() method from one of the Authress SDKs, which creates the Authress assertion and redirect url. (Note: this happens inside the identity service, not in the user's UI)

Redirect a user to Authress to complete login
import { ServiceClientTokenProvider } from '@authress/sdk';

/**
 * state {string}
 *    The state value passed to the identity service as part of user login. Found in the query string.
 * redirectUri {string}
 *   The redirect_uri value passed to the identity service as part of user login. Found in the query string.
 *   This value will match your custom domain global redirect value, such as: https://auth.yourdomain.com/login
 */
function getUserRedirectUrl(state, redirectUri) {
    const serviceClientId = 'SERVICE_CLIENT_ID';
    const accessKey = 'SERVICE_CLIENT_ACCESS_KEY';

    const tokenProvider = new ServiceClientTokenProvider(accessKey);
    const userId = 'Verified_User_ID';
    const authressLoginUrl = await tokenProvider.generateUserLoginUrl(redirectUri, state, serviceClientId, userId);
    return authressLoginUrl;
}

5. User completes the login flow​

Step #4 generates an assertion in the form of a URL. This URL should be sent back to your user, in the form of a browser redirect. The user will be directed to Authress to complete the assertion, and then will be logged in with an Authress identity token. The token and user will be sent back to the origin application url that started the process.

Last updated on