<OssoLogin />is fully documented and ready for you to use in your application, but portions of this library for adding SAML configuration flows to your application are still under construction.
Osso offers a React library that you can use to deepen your Osso integration with your application. The package includes high level components for things like a login form as well as lower level hooks and utilities for crafting your own login or SAML configuration features. The library is written natively in Typescript and provides it's own type definitions.
- MaterialUI codesandbox
- Ant Design codesandbox
- Osso - Osso uses our own React library to build our Admin UI
- NextJS live demo
- NextJS example source code
@enterprise-oss/osso as a runtime dependency with Yarn or NPM:
After installing the package, you need to use the
<OssoProvider> component to wrap any Osso components to provide them context about your Osso instance. If you're planning on using the
<OssoLogin> component then we suggest placing the
<OssoProvider/> as high up in your application's component tree as possible.
<OssoProvider> requires a client prop with the following properties.
|baseUrl||true||The base URL of your Osso instance, i.e. |
|jwt||false||A JSON web token authenticating an end user. Utilized for self-serve SAML configuration which is under construction 👷🏽♀️|
Osso React components can be divided into two categories - a component for crafting a login form and components that allow your users to configure their own SAML identity providers.
Osso's components make an effort to be "headless" - they handle logic and layout, but allow you to provide your own UI elements to match the look and feel of the rest of your application.
The Osso Login component is designed to allow you to craft a login experience that serves SAML SSO users and email / password users equally well, while not breaking password managers and maintaining the look and feel of your application.
When a user wants to sign in to your application with SAML SSO, Osso needs to route the user to the correct Identity Provider. The simplest way to achieve this is using Osso's hosted login page, but the strongest UX would be for you to ascertain whether a user is configured for SAML SSO and to send them directly to their IDP.
<OssoLogin> allows you to do this without building your own form.
We like to call this component "headless" - it renders layout and handles interaction, but accepts UI components as props in order to match your look and feel.
Here's a code sample:
These are the available props:
|containerClass||false||The className to put on the form container rendered by the component|
|ButtonComponent||false||A UI component for the login form's submit button - see below for API|
|InputComponent||false||A UI component for the login form's inputs - see below for API|
|onSamlFound||true||A function to be called when an IDP is found for the provided email address|
|onSubmitPassword||true||A function to be called when a non-SAML user submits the login form with a password|
By default, Osso will render an HTML button.
Here's a quick example of a button component that fits Osso's requirements, assuming you already have a Button component in your application.
Here are the props OssoLogin will provide to an instance of your ButtonComponent class or function. You should accept all of these props, but the props marked as required are absolutely necessary for functionality.
|children||false||The default button text|
|disabled||false||Will be |
|loading||false||Will be |
|onClick||true||When your button is clicked, it must call the |
|type||false||Osso will provide the expected ARIA role type, one of |
By default, Osso will render an HTML input.
Here's a quick example of a input component that fits Osso's requirements, assuming you already have an Input component in your application.
Here are the props OssoLogin will provide to an instance of your InputComponent class or function. You component should accept all of these props in order to avoid React errors, but the props marked as required are necessary for functionality.
|autoComplete||false||HTML autocomplete type, one of |
|id||false||The ID of the input - useful for a label's |
|label||false||A string for the Input's label - highly recommended you use this|
|onChange||true||A function to be called when the controlled input value changes - must update the value, and provides the actual value rather than the change event|
|required||false||Whether the input is required by the HTML form, highly recommended that you use this|
|type||false||Osso will provide HTML type, one of |
|value||true||A prop for holding the controlled input's value|
The SAML configuration components included in the Osso React library are the same components Osso uses in the Admin UI to allow SAML configuration. The components themselves are relatively stable, but the Osso team is still working through how best to authenticate end-user requests made by these components.
We recommend starting with onboarding customers via the Admin UI. Let us know if moving that configuration flow to your own application is important to your integration.
If Osso's React components don't suit your needs, the library also exposes lower level React hooks that you can use in your own components.
Our hooks aren't yet fully documented and still under construction, but here are a couple you might find useful. You can find th rest in the Osso React Github repository.
useOssoFields hook is useful for relaying data about Osso's supported Identity Providers.
You might use this to construct a flow for SAML self-config, or to tell your users which Identity Providers you support without having to hardcode anything.
The above code would produce the following:
useOssoLogin hook is useful for crafting a login form that supports both SAML and email / password inputs. The hook allows you to call a function that asks the Osso API whether a configured Identity Provider exists for the submitted email. The return tuple for the hook includes this function as well as a
Here's a quick example hooked up to the Osso demo instance:
Osso React provides some utility functions that may be useful to you whether you use an Osso instance or not.
One of the best parts about Osso is our sparkling custom documentation for IDP admins to configure your app in their IDP.
documentationWriter utility function will interpolate the required data into Osso's raw PDF docs to create a custom document for a customer.
The best place to understand how to use this functionality without Osso is taking a look at the unit tests. If you want to use this utility within an OssoProvider, your best bet is to use the
The easiest way to receive SAML config data back from your customer is to have them send you a federated metadata XML file.
This utility parses those XML files from all Osso supported IDPs into a JS object with the required values for finalizing config.