We do provide a demo Clojure ring application - you can view the source or a live demo. The Osso team also worked with the
ring-oauth2 maintainer to ensure this project supported all of Osso's functionality.
You can review ring-oauth2's docs on the project's GitHub repo, and follow along below for a walkthrough of how to integrate Osso to this middleware.
ring-oauth2, add the following to your project
Next, use the middleware function
ring.middleware.oauth2/wrap-oauth2 to wrap your application routes.
This middleware function accepts a map of third party providers. Each provider is identified by a key and requires a map of values that instruct the middleware how to interact with the provider. Here's what this would look like for Osso.
You'll need to replace the
access-token-uri values with your own instance URL, and Client ID and secret values with values from your instance - these should not be placed in version control.
redirect-uri are specific to your application - just be sure to include the redirect URI on your Osso OAuth Client allow list. A user will be redirected to your
ring-oauth2 will handle exchanging the authorization code for an access token. Once the user is authenticated, a new key is added to every request that includes the access token. You are responsible for requesting a profile for the user from Osso in order to sign the user into your application.
You can write a function that calls the Osso API with the access token to get the user profile:
Finally, you can provide a
ring-oauth2. If you use the the landing URI, the user will be redirected there once an access token is available, and you'll need to write your own handler. Alternatively, provide a
redirect-handler. Here our handler calls the Osso API to get the user's profile and prints the json to the browser. You'll instead want to sign the user in and render a logged in state.
With that in place, your users are ready to start signing in when performing an IDP initiated login. But you'll still want to provide a way for your users to kick off the login flow when they come to your website without a current session.
The simplest approach is to use Osso's hosted login page by adding a Sign in with SAML SSO button to your application's login page. The button should submit a POST request to
auth/osso, so we'll stick it in a form. We also should be locking down our POST routes with CSRF protection, so we also need to post an
If we wanted to avoid Osso's hosted login page, we need to ascertain the email or domain from the user and include it as a parameter that we submit to our
launch-uri. The ring middleware will automatically include this parameter when sending the user to your Osso
authorization_url, and Osso will use the included parameter to send the user to the proper IDP.
ring-oauth2to include support for passing additional query params to the authorization URL. Until that's merged, you'll be forced to use Osso's hosted login page. If you need this functionality, help us get our PR merged!
But this is really only appropriate to use if all of your users sign in with SAML, or as a SAML-only login flow. A user who is not configured for SAML will be shown an error page on Osso when they submit this form.
Osso's point of view is that you should offer a single flow that starts with an email input, determines on a submit if that user should be signed in using SAML, and displaying a password input otherwise. You should take care to ensure your login form also supports auto-filling logins with one click from a password manager.
If you use React, Osso provides a login component that offers this functionality. Here's a quick demo of it in action, and check out our Osso React docs to learn more.