How to deploy Osso

The content of this article applies to the open source version of Osso and is not relevant to our paid plans. If you're already an Osso customer, skip ahead to Configuration.

Osso is an open source service for adding SAML-based Single Sign-On to your stack. You can deploy and manage it yourself or pay for a managed Osso instance.


Osso makes it easy to deploy your instance whether you need a quick deployment to Heroku or a containerized deployment on your own servers.

If you're deploying Osso to a PaaS like Heroku, or with the Osso Docker image, you'll need external services like an SMTP server to send email (i.e. Mailgun), which you configure through environment variables.

If you're deploying Osso to your own infrastructure, you'll need your own services like a postgres database, a build server with the NodeJS runtime, and a Ruby/Rack compatible webserver.


If you want to deploy and manage Osso yourself, the easiest way to get started is with the Deploy to Heroku button. Heroku will run convenient setup scripts and help you set required environment variables to get you up and running quickly.



Our Docker image is under construction - check out our open PR with some in-progress work (help welcome!).

Osso also provides a Docker image (beta).


Osso is a Ruby application that serves a single page React app for the Admin UI. The main Github repository is a simple Ruby application written around the osso-rb gem, which provides the Admin API and the SAML and OAuth login functionality. The client React app provides a robust Admin UI and is written in Typescript, getting its core functionality from React hooks and components in osso-react.

This approach allows developers to customize their Osso instance as needed, while maintaining the ability to get critical updates via package updates with little fuss. Add middleware like tracing, customize the UI theme, and extend the API without worrying about resolving merge conflicts on critical authentication code.