The easiest way to integrate Osso with a NextJS app is to use NextAuth.js, an open source library for integrating OAuth providers into a NextJS app. Osso is supported as a Provider in NextAuth.js from version
NextAuth.js provides their own getting started docs, and you can also view an example app that implements Osso as a provider.
next-auth as a dependency with
To handle auth requests, create a file called
pages/api/auth. All requests to
/api/auth/* (signin, callback, signout, etc) will automatically be handed by NextAuth.js.
#Session provider and hook
NextAuth.js provides some tooling for determining whether a user is signed in. First let's wrap our whole application with the NextAuth.js
Provider so that we can share session state across the client app without making additional API calls.
Using the supplied React
<Provider> allows instances of
useSession() to share the session object across components, by using React Context under the hood.
This improves performance, reduces network calls and avoids page flicker when rendering. It is highly recommended and can be easily added to all pages in Next.js apps by using
Then, in your page components, you can implement the
useSession hook to get information about the current user if a user is signed in.
The shape of the session object:
#Sign in UX
Once your routes are set up and you're using NextAuth's tooling for determining whether a user is signed in, you need to provide a way for your SAML SSO users to actually log in.
Depending on your needs, you can begin with a simple button for signing in with SAML SSO, which would then send the user to Osso's hosted login page. If you need more customization, you can implement a SAML-only login flow that sends the user directly to their IDP, bypassing Osso's hosted login page. Finally, you can use Osso's React library to implement a login form that supports SAML SSO and email / password based logins.
#Osso hosted login
NextAuth.js includes a page that renders buttons for each of the Providers you implement. A user who navigates to
/api/auth/signin will be able to click a Sign in with SAML SSO button to kick off the authentication flow.
You can also implement your own log in button with NextAuth's
The login buttons above will take the user to Osso's hosted login page. You can have your users skip that page and instead ascertain either their email or domain, include that in the authorization request to Osso, and send the user straight through to their IDP.
We once again use NextAuth's
signIn function, but this time we need to implement a form field to get the domain from the user and include it in the
signIn call. You could also use an email address and send that to Osso instead.
This is an improvement over using Osso's hosted login, and plenty of companies use this approach for their SAML login flow. It allows email / password based users to use the primary login flow, meaning we aren't breaking support for password managers. But we are asking our SAML SSO users to remember that they sign in with SAML SSO. If we use a login component from Osso's React library we can solve both of these problems.
#React <OssoLogin />
Osso's React library provides a component for a login form that interacts with your Osso instance. The component allows you to provide your own UI elements, like inputs and buttons, and acts as a "headless" component that handles determining whether a user who wants to sign in is configured to sign in with SAML via Osso. The
OssoLogin component also supports password managers for email / password based users, so no type of user is prioritized - everyone gets a great experience.
Here's an example of the component using UI components from Ant. Try
firstname.lastname@example.org for SAML,
email@example.com to reveal the password field, and try to autofill with your password manager - the password field should fill and reveal itself.
First, add Osso's React library with yarn or NPM:
We need to set up the components we want OssoLogin to use. Here we'll use an input and button from Ant, but the Osso react Repo also has examples for MaterialUI, and the API is documented here.
Then we can import the
OssoLogin components, ensuring to wrap our
OssoLogin component with an
OssoProvider configured with your Osso base URL, and providing the UI components we created above to OssoLogin. For now, we'll
console.log the result of our auth handler props.
When a user submits an email address, the OssoLogin component calls your Osso instance to determine if that user can sign in with SAML via Osso. If so, we'll want to kick off that auth process. It's vital that the auth flow pass through your server in order to prevent against CSRF attacks, and NextAuth will enforce that approach. We want to implement this in the
onSamlFound prop, again using
signIn from NextAuth and passing the email address entered by the user.
If a user who cannot sign in with SAML submits an email address, the OssoLogin component will render a password field. When the user again submits the form with a password, the
onSubmitPassword prop function is called.
Without knowing more about your authentication approach we can't instruct you too much here. NextAuth ships with support for email / password based accounts, so let's assume you're using that for simplicity here (note that NextAuth requires some additional config to speak to your database if you take this approach).
We can add another sign in call, this time using
That's it! Your NextJS app now has support for SAML SSO authentication. Our login form makes every type of user happy, we're being secure about how we consume Osso's OAuth server and we aren't forcing our SAML users to remember that they need to sign in with SAML.
Continue reading about NextAuth.js for adding features like a sign out button.