Welcome to our guide on setting up Security Assertion Markup Language (SAML) for seamless and secure authentication within your organization's systems. In today's interconnected digital landscape, safeguarding sensitive data while ensuring efficient access for users is paramount. SAML stands as a robust solution, streamlining authentication processes and enhancing security measures. This document aims to provide you with a comprehensive step-by-step approach to implementing SAML, empowering you to establish a reliable authentication framework that aligns with your organization's security needs and operational efficiency.
Overview of how Single Sign-On works with Rabbet
Rabbet uses Auth0 (a product of Okta) to manage user authentication, including Single Sign-On integrations. Through Auth0 we gain robust features, strong security posture, flexibility, and ease of integration.
Here is a link to Auth0 documentation on setting up a SAML connection:
User Registration and Permissions
The normal workflow requires an admin user of the Client Organization to first invite each new user via the main Rabbet interface:
The user’s permissions will be mapped via the SSO connection, and are thus not required to be set at this time. In fact they follow the role/permission mapping strictly and cannot be overridden by a user.
After the user receives their invite email, they can register, which will take them through the SSO connection and set their Role / Permissions accordingly.
At this time, we do not support just-in-time user creation, so users must be created via the above method.
SP-Initiated Login
This is the case where the user starts at the Rabbet interface and needs to login. They are initially presented with our general login screen:
After typing in their email address, our login screen will detect that they should login with SSO, based on their email domain. It will change to look like this:
Pressing the Log In button will then take them to your company’s login. And after that is successful, the user will be brought back into Rabbet, authenticated.
IdP-Initiated Login
You may also implement Identity Provider-Initiated login, where after a user is logged into your system, you provide them a link to Rabbet, where they can seamlessly land, logged in.
Under the hood, this is actually accomplished via a SP-initiated login and an extra redirect. It all happens fast enough that the user doesn’t notice.
Changes in User Roles
When a user's role undergoes a change, this modification is recorded and reflected during their next login via the Single Sign-On (SSO) process into Auth0. Subsequently, this update triggers an immediate adjustment in their permission set within Rabbet, ensuring that their access and authorization align accurately with the altered role.
Steps to Integrate
Provide a user Roles → Permissions mapping
Send us your SAML connection info
Configure metadata assertions
Provide a user Roles → Permissions mapping
You will be given a separate file that lists our User Permissions, along with a sample mapping to Roles to follow. Please return this in the format matching the sample mapping.
Note that not all permissions listed in the template may actually be available to you, depending on which features your organization has enabled.
You may use as many different role configurations as you like.
Send us your SAML connection info
We need the following information:
Sign in URL: This will be the login url on your side that we send users to during SP-initiated login
X509 Signing Certificate: The SAMLP public key file, in PEM or CER format
The attribute in the SAML token that will be mapped to the user_id property in Auth0. If not set, then the user_id will be retrieved from the following (in listed order):
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Request Signing settings. The following is common:
Request Template (optional). Here is a sample:
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"@@AssertServiceURLAndDestination@@ ID="@@ID@@" IssueInstant="@@IssueInstant@@" ProtocolBinding="@@ProtocolBinding@@" Version="2.0">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">@@Issuer@@</saml:Issuer>
</samlp:AuthnRequest>
Configure Metadata Assertions
The main ones we use are:
given_name (ex: Alexander)
family_name (ex: Hamilton)
role (ex: Admin, Approver, etc)
Example:
<saml:AttributeStatement>
<saml:Attribute Name="role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue>Admin</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>