Enabling single sign-on via SAML 2.0

Introduction

Single sign-on (SSO) with SAML 2.0 lets your organization manage user authentication centrally via an Identity Provider (IdP) such as Okta, Azure AD, OneLogin, Ping, or any SAML 2.0–compliant system. When configured, users sign in with their corporate credentials and gain access to Robin without a second password. This guide walks through the end-to-end process to enable SAML SSO for Robin, including practical configuration examples, attribute mappings we commonly recommend, and common troubleshooting tips.

Before you begin, ensure you have administrative access to both your Robin admin console and your IdP dashboard.

Prerequisites

• An active Robin account with admin privileges and access to the organization's settings or security panel.
• A SAML 2.0–compatible Identity Provider (Okta, Azure AD, OneLogin, Ping, Auth0, Shibboleth, etc.).
• The ability to create or edit a SAML application/integration in your IdP (create credentials, upload metadata, and configure attribute mappings).
• An x.509 certificate (PEM) or the ability for the IdP to publish metadata XML including certificate info.
• HTTPS-accessible Assertion Consumer Service (ACS) URL and Entity ID values provided by Robin (these are required by your IdP). If you don't have them, get them from Robin's SSO setup page.

High-level flow

The SAML SSO flow between the browser, your IdP, and Robin (the Service Provider, SP) typically follows these steps:

1. User attempts to access Robin and clicks “Sign in with SSO” (or is redirected automatically).
2. Robin redirects the browser to your IdP (AuthnRequest), or the user begins at the IdP dashboard (IdP-initiated login).
3. After the user authenticates at the IdP, the IdP issues a SAML Assertion containing user identity and attributes, and posts it to Robin’s Assertion Consumer Service (ACS) URL.
4. Robin validates the signature and assertion conditions, maps attributes to a Robin user, and creates or links the account according to your provisioning rules.

Service Provider (Robin) values you need

Robin will provide the following values to configure in your IdP. If not visible in the admin UI, request them from Robin support or your account manager:

Configuring your Identity Provider (IdP)

Below are the common steps for configuring a SAML application in your IdP. The exact UI varies per provider, but the fields are generally the same.

1. Create a new SAML application

1. Log into your IdP admin console and create a new SAML 2.0 application (often called “SAML app”, “enterprise app”, or “Custom SAML”).
2. Set the application name (e.g., “Robin SSO”).
3. Provide the ACS (Assertion Consumer Service) URL and SP Entity ID supplied by Robin.

2. Configure NameID & attributes

Choose the NameID format and attributes Robin expects. Common settings:

• NameID format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress or unspecified depending on Robin's requirements.
• Required attributes: At minimum, provide a unique identifier and email. Typical attribute names:

3. Set signing / encryption

Most IdPs will sign SAML Assertions by default. Robin will typically require signed assertions — confirm whether Robin expects signature on the assertion or on the response. Upload or copy the IdP signing certificate (PEM) into Robin’s SSO settings if required.

4. Configure Single Logout (optional)

If you want single logout, configure the SingleLogout URL in both Robin and the IdP and ensure the binding (POST or Redirect) matches. Note that logout flows are harder to debug and sometimes are best left disabled until initial SSO is stable.

Configuring Robin (Service Provider)

In Robin’s admin or security settings, you will add IdP metadata and select desired behavior for account provisioning and group mapping. The typical steps are:

1. Open Robin Admin → Security → Single Sign-On (or similar).
2. Choose “Enable SAML” and paste your IdP metadata XML or provide the IdP SSO URL, IdP Entity ID, and the x.509 signing certificate.
3. Set the expected NameID format and confirm attribute names match those you configured in the IdP (email, firstName, lastName, groups).
4. Decide on provisioning behavior:
   • Just-in-time (JIT) provisioning: Robin creates users automatically the first time they sign in (recommended for small/medium orgs).
   • Manual provisioning: Require pre-created Robin user accounts and map SAML assertions to existing accounts (recommended for strict access control).
5. Optionally upload the IdP certificate fingerprint or certificate to verify signed assertions.
6. Save and enable the configuration.

Sample SAML snippets (examples)

These snippets are illustrative. Replace values with your actual tenant-specific endpoints and certificates.

Example minimal SP metadata

<EntityDescriptor entityID="https://app.robin.com/saml/metadata" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
  <SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://app.robin.com/saml/consume" index="0" />
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://app.robin.com/saml/logout" />
  </SPSSODescriptor>
</EntityDescriptor>

Example attribute statement in an assertion (IdP side)

<AttributeStatement>
  <Attribute Name="email">
    <AttributeValue>alice@example.com</AttributeValue>
  </Attribute>
  <Attribute Name="firstName">
    <AttributeValue>Alice</AttributeValue>
  </Attribute>
  <Attribute Name="lastName">
    <AttributeValue>Jones</AttributeValue>
  </Attribute>
  <Attribute Name="groups">
    <AttributeValue>engineering</AttributeValue>
    <AttributeValue>admins</AttributeValue>
  </Attribute>
</AttributeStatement>

Testing SSO

Follow this checklist to validate configuration before rolling out to all users:

1. Create a test user in the IdP with the expected attributes and an email that either maps to an existing Robin user (for manual provisioning) or is allowed to JIT provision.
2. Try IdP-initiated login: Launch the app from your IdP dashboard and confirm you are redirected to Robin and signed in.
3. Try SP-initiated login: From the Robin sign-in page, click “Sign in with SSO” and authenticate via the IdP.
4. Confirm attribute mapping: Verify user’s display name, email, and group/role mapping in Robin profile.
5. Verify signature and conditions: Robin must accept signed assertions with valid NotBefore/NotOnOrAfter timestamps, matching Audience, and correct Recipient/ACS.
6. Check logs: Use Robin’s SSO logs and your IdP logs to inspect AuthnRequests and Assertions for mismatches if sign-in fails.

Troubleshooting common issues

Assertion signature validation failed

• Confirm the IdP's public signing certificate uploaded to Robin exactly matches the one used to sign the assertion.
• Check for certificate rotation — if the IdP rotated keys recently, update the certificate on Robin.

Incorrect NameID or attribute mapping

• Ensure the IdP sends the NameID in the format Robin expects (usually emailAddress).
• Map the IdP attribute names to the SP attributes — many IdPs let you remap attribute names in the application settings.

Time skew / assertion conditions error

• Check that the IdP and Robin servers have correct system time (NTP). Even small clock skew can cause failed assertions because of NotBefore / NotOnOrAfter constraints.

User provisioning mismatch

• If Robin is set to manual provisioning and a user doesn't exist, they will be denied. Either enable JIT provisioning for the app (if appropriate) or pre-create users in Robin.

Logout not working

• Confirm the SLO (Single Logout) endpoints and bindings match on both sides. Some IdPs require the SP to sign logout requests; others require signed logout responses from the IdP.
• Consider disabling SLO during initial rollout if it introduces complexity.

Security best practices

• Always use signed assertions. Prefer signing the assertion (and sometimes the response) using a strong x.509 certificate.
• Rotate signing certificates periodically and automate metadata updates where possible.
• Use HTTPS for all endpoints and disable support for weak ciphers on IdP and SP endpoints.
• Limit attributes to the minimum required for account creation and provisioning.
• Use SCIM or an automated provisioning connector (if available) to manage user lifecycle (onboarding/offboarding) rather than relying solely on JIT provisioning.
• Log and monitor SSO activity (successful and failed assertions) for suspicious behavior and auditability.

Frequently asked questions

Q: Do we need to enable SAML for all users at once?

A: No — you can enable SSO for your organization and test with a pilot group. Many customers run the IdP app in parallel to allow both SSO and legacy username/password logins during rollout.

Q: What if our IdP uses encrypted assertions?

A: If the IdP encrypts assertions, Robin must be configured with the SP private key to decrypt them. Confirm whether Robin supports assertion decryption and provide the correct SP decryption key if required.

Q: How do we handle role/permission mapping?

A: Map IdP groups or roles into Robin roles by sending a groups attribute in the assertion and configuring group-to-role mapping in Robin’s admin panel. Alternatively, use SCIM for richer provisioning and role assignment.

Next steps & checklist

1. Collect Robin SP values (ACS URL, Entity ID, optional SLO URL).
2. Create the SAML app in your IdP and enter the SP values.
3. Map attributes (email, firstName, lastName, groups) and choose NameID format.
4. Upload IdP metadata or certificate to Robin and save settings.
5. Test with a pilot user (IdP-initiated and SP-initiated flows).
6. Verify logs and monitoring, then roll out to production users.

If you run into issues, consult the debugging tools mentioned earlier (SAML-tracer, IdP logs, browser devtools) and contact Robin Support with sanitized logs and a description of the failed step. Good SSO hygiene — signed assertions, careful attribute mapping, automated provisioning for lifecycle management — will help your deployment be reliable and secure.