passport-osso
Osso's Passport library passport-osso
helps you integrate your Osso instance with a Connect-based NodeJS application, such as a NodeJS express application. It's a provider strategy for the PassportJS framework thats uses an OAuth 2.0 authorization code grant flow.
#
Examples- osso-node-example - a clean NodeJS express app using passport-osso
- enterprise-oss/saas - fork of a SaaS boilerplate NodeJS express app, using passport-osso
#
Quick startIntegrating passport-osso
is a 3 step process of installation, configuration and handling sign in callbacks from Osso, and providing a sign in mechanism for users.
#
InstallInstall passport-osso
as a runtime dependency with Yarn or NPM:
- Yarn
- NPM
#
Configuration and callbackIn order to configure our NodeJS app to use Osso's passport strategy, we need to setup both passport and Osso as a provider.
You'll need to provide your clientId
, clientSecret
and baseUrl
values for your Osso instance. You specify the callback path, just ensure you add the fully qualified URL to your Osso OAuth Client's allow list in the Osso UI.
The final argument to the strategy constructor is a function that you can use to find or create a user from your database and pass to the callback function, allowing passport to sign the user in.
The passport-osso
middleware handles the intermediate requests - exchanging the authorization_code
for an access_token
and then using the access_token
to request a profile for the user. But we need to handle both the initial request from your frontend, and later Passport passes the return request on to your callback path, and the user is available on req.user
. Here we print the user to the screen as JSON.
#
Sign in UITo kick off a SAML sign in request via Osso, a user must submit a POST request to your server in order for passport to take over and redirect the user to Osso. It's important you don't send your users from your frontend directly to Osso to prevent CSRF attacks.
If you include a query parameter for email
or domain
, the user will be routed to their IDP automatically. Otherwise the user will be shown an Osso hosted login page.
For convenience, let's use Osso's hosted login page by sticking a button on our login page that POSTs to /auth/osso
.
Alternatively we can offer a SAML-only login form, where we ask for the user's email address, which passport-osso
will pass to your Osso instance, allowing Osso to redirect the user to the correct IDP without rendering it's own form.
If we make this change, we need to update our route handler for this POST request to pass email
to Osso.
Later you can more deeply integrate Osso into your main login flow - check out Osso's React library if you use React on your front end.