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.
- 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
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.
passport-osso as a runtime dependency with Yarn or NPM:
In 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
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.
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.
To 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
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
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
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.