Skip to main content

Custom Passwordless Login

This guide details how to set up a passwordless flow. The same flow can be used to configure users to log in with an email address, a phone number, or any other custom flow you might have. You can direct the user to a custom login screen, then use Authress to generate a login code, and then forward the user to that screen to log in with the code.

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 passwordless flow, so no changes are necessary to your web app. As a reminder these are the relevant SDK methods:

(Application UI) Log a user into your application
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.
await loginClient.authenticate({
  connectionId: 'SELECTED_CONNECTION_ID'
});

// 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. Create the passwordless service handler​

To enable password login with Authress, a new special kind of connection will be created. This connection enables you to generate the screens and service endpoints necessary to log a user in with their email or other data.

Generate a new Authress Service Client. Enter a name for the client, and select the option to Grant the client OAuth user impersonation. This allows your passwordless login screens to directly communicate with the Authress login API to request user identity tokens.

Enable the passwordless authress login

2. Enter your passwordless login UI URL​

Your login screen has a UI associated with identifying the user. This should be an email, phone number, or any other login prompt requesting the user's email for a magic login token based flow. Set the Authorization Url to be this URL.

Create a passwordless 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 email, you'll ask the user to provide their email. Call your api service represented by the service client with the entered email address.

  • Take the entered email address and send that to your service.
  • Call Authress to generate a code
  • Send an email to the user with the code
  • The user should be directed to retrieve the code, and then redirected back your identity UI.
  • The UI should pass the code to your 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 and code parameter. Both of these parameters must be passed back to Authress in the next step. This code is sensitive but it is not credentials and therefore should be treated with care but should not be treated as a replacement for a secure identity.

4. Generating the Authress Assertion​

Your 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 from the generate state and code. (Note: this happens inside your service, not in the user's UI)

(Application Service API) Redirect the user to Authress to complete login
import { ServiceClientTokenProvider } from '@authress/sdk';

/**
 * @param {string} state The state value passed to the identity service as part of user login. Found in the query string.
 * @param {string} redirectUri 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