Authress Login SDK for UIs
The Authress Universal Login SDK for javascript app websites and user identity authentication. Used to integrate with the authentication as a service provider Authress at https://authress.io.
Usage
npm install @authress/login
Then required the package:
import { LoginClient } from '@authress/login';
Troubleshooting usage
Troubles with esbuild or another bundler, checkout the build tools troubleshooting page.
Getting Started
Part 0: Setup Authress Login
You'll want to create:
Part 1: Web App UI
On every route change check to see if the user exists, and if they don't redirect them to a login prompt.
import { LoginClient } from '@authress/login';
const loginClient = new LoginClient({ authressApiUrl: 'https://login.application.com', applicationId: 'YOUR_APPLICATION_ID' });
const isUserLoggedIn = await loginClient.userSessionExists();
if (!isUserLoggedIn) {
window.location.assign('/login');
}
In your app's login screen when the user selects how they would like to login, direct them there. And also specify where you would like Authress to redirect the user to after login. By default this is the user's current location.
await loginClient.authenticate({ connectionId: 'SELECTED_CONNECTION_ID', redirectUrl: window.location.href });
await loginClient.authenticate({ tenantLookupIdentifier: 'tenant-subdomain.app.com', redirectUrl: window.location.href });
return;
Then get the user access token associated with the user's login to be used for authorization in the next part:
const userToken = await loginClient.ensureToken();
Part 2: User Authentication in Service APIs
To authenticate the user in your service API, the token generated by the library in Part 1
needs to be passed to your service. The standard is pulling it from the loginClient, and putting it into an Authorization
header:
const userToken = await loginClient.ensureToken();
const result = await fetch('https://api.application.com/v1/route', {
method: 'GET',
headers: {
'Authorization': `Bearer ${userToken}`
}
})
On the service API side, pull in the Authress service client companion library, and then verify the access token.
- First install the companion library:
npm install authress-sdk
- Then verify the incoming tokens from the Authorization header:
const { TokenVerifier } = require('authress-sdk');
try {
const userToken = request.headers['Authorization'];
const userIdentity = await TokenVerifier('https://login.application.com', userToken);
} catch (error) {
console.log('User is unauthorized', error);
return { statusCode: 401 };
}
Platform Extension Login
The goal of the platform extension is to make it easy for your platform extension developers to login with Authress. Embed the ExtensionClient
in your javascript UI SDK, and pass in the extensionId
.
const { ExtensionClient } = require('@authress/login');
const extensionClient = new ExtensionClient('https://login.application.io', extensionId);
const { accessToken } = await extensionClient.login(redirectUrl);
const { accessToken } = await extensionClient.login(redirectUrl);
await userData = await this.getUserIdentity();
Advanced
Curious exactly how these methods work and when they should be used? We have some advanced guidance available for each of the methods on the:
Method documentation
Contributing
If you are interested in contributing to the @authress/login SDK, feel fere to read the contribution.md guide.