Skip to content

Authentication

Configure Single Sign-On (SSO) to enable seamless authentication for staff and students using your institution's existing identity provider.

Overview

Arbol supports SAML 2.0 authentication, allowing your users to log in with their institutional credentials. Our flexible configuration works with all major identity providers including:

  • Microsoft Active Directory / Azure AD
  • Okta
  • Shibboleth
  • Google Workspace
  • PingFederate
  • Any SAML 2.0 compliant provider

Configuration Sections

Navigate to Authentication in the Arbol platform to configure SSO. The page is organized into four main sections:

1. Arbol Details

From your Authentication page in Arbol, you can retrieve these values to provide to your Identity Provider Administrator. Each field includes a copy button for easy sharing.

Field Example Value Description
Your Metadata URL https://api.growarbol.com/auth/saml/{tenant_id}/metadata Arbol SP Metadata Endpoint
Entity ID https://api.growarbol.com/auth/saml/metadata Service Provider identifier
Assertion Consumer Service (ACS) URL https://api.growarbol.com/auth/saml/{tenant_id}/acs Arbol SP Assertion Endpoint
Single Logout Service (SLO) URL https://api.growarbol.com/auth/saml/{tenant_id}/sls Arbol SP Logout Endpoint
Arbol Public Certificate X.509 certificate (downloadable as .PEM) SAML signing certificate from Metadata URL

Dynamic URLs

The {tenant_id} in the URLs above will be replaced with your institution's unique identifier. Copy the exact URLs from your Arbol Authentication page - they will already have your tenant ID populated.

Quick Setup

Most identity providers can auto-configure by importing our metadata URL directly. Simply provide the metadata URL to your IdP administrator and they can configure all settings automatically.

2. Institution Configuration

Configure your Identity Provider's SAML settings in Arbol:

Provide your Identity Provider's metadata endpoint URL for automatic configuration updates:

https://your-idp.example.edu/metadata

Option 2: Upload Metadata File

Upload a static XML metadata file from your Identity Provider if a URL endpoint is not available.

SAML Assertion Signing

All SAML assertions must be signed by your Identity Provider. Arbol will extract your IdP's public signing certificate from the metadata you provide (either via URL or file upload). This will be used to verify the authenticity of SAML assertions during authentication.

Metadata File Limitations

If you upload a static metadata file instead of providing a URL, you must manually re-upload the file whenever your IdP certificate changes. Metadata URLs are recommended long-term because Arbol can automatically refresh the configuration.

3. Just-In-Time User Provisioning

Use the toggle switch to enable or disable automatic user creation:

  • When enabled: New user accounts are automatically created the first time a user logs in via SSO.
  • When disabled: Users must be pre-imported via CSV before they can authenticate.

JIT provisioning allows for seamless authentication, but plan to use User Import followed by Bill Import to populate financial data for students before they engage with Arbol.

User Import for Billing & Financial Aid Data

Even with JIT provisioning enabled, use of our billing data upload will still require you to import users via CSV if you want to load billing data reliably and before a user has had a chance to login.

JIT only creates basic user accounts once they have logged in (billing data requires the account to exist first). Make sure the User Import file you upload includes any user accounts being reported as non-existent from the bill upload.

Welcome Email Timing

SSO users do not receive the set-password / "activation link" email that non-SSO users get. Instead, Arbol fires a welcome email at one of two moments:

Trigger When the welcome fires
User Import with notifications on At the moment the row is processed, provided the user has not already completed an SSO sign-in.
First successful SSO sign-in For JIT-provisioned users and for users imported with notifications off — fires once, on the sign-in that flips them from unverified to verified.

Verification model. A successful SSO sign-in is the verification event for the account — equivalent to clicking the email-verification link in the password-based flow. Until that sign-in happens, the account is "unverified" from Arbol's perspective. Schools cannot trigger verification by setting the SSO Identifier in import or admin; only the user signing in does it.

No duplicate welcomes. Once User Import has sent the welcome for a row (and stamped the user record accordingly), the first SSO sign-in for that user will quietly verify them without re-sending the welcome. If Import did not send the welcome (notifications off, or the user came in via JIT), the sign-in path sends it instead.

Re-engaging a user who has not signed in. Re-running a User Import with notifications on against an unconfirmed user (one who has not yet completed an SSO sign-in) re-sends the welcome each time and refreshes the engagement timestamp. This mirrors the behavior schools rely on for the non-SSO set-password flow — re-imports re-notify users who have not yet engaged.

Re-engaging a user who has signed in. Re-imports with notifications on are not re-sent to users who have already completed an SSO sign-in. If you need to re-engage such a user (rare), contact Arbol support.

SSO Identifier Assignment

The SSO identifier in Arbol is always set from the SAML NameID sent by your Identity Provider. This is the value in the <saml:NameID> element of the SAML assertion, which you configure in your IdP separately from your attribute mappings.

Common NameID configurations:

  • Email address (most common default in Okta and similar IdPs) — simple but tied to the user's email
  • Persistent UUID or institutional username (best practice) — opaque, stable, survives email changes

The NameID value should remain stable for the same user across logins. If you change your IdP's NameID source after users have already authenticated, existing users will continue to work because Arbol falls back to email-based matching, but you may want to review the Attribute Update Behavior section below.

4. Attribute Mapping

Map SAML attributes from your Identity Provider to Arbol user fields.

Arbol Field Configuration Required Common Examples Notes
Unique User ID (NameID) Subject (fixed - not configurable) Yes N/A Your IdP must send a Subject attribute containing the user's SSO identifier
Email Enter your IdP's attribute name Yes mail, email, emailAddress, Email Required for account creation and notifications. Email matching is case-insensitive — Arbol stores all emails in lowercase.
First Name Enter your IdP's attribute name Yes givenName, firstName, fname, FirstName Used for user profile display
Last Name Enter your IdP's attribute name Yes sn, surname, lastName, LastName Used for user profile display
Institution ID Enter your IdP's attribute name Required for students employeeNumber, studentId, bannerId, StudentID Student ID for student accounts. If your institution does not have a separate ID system for students, configure this attribute to send the user's email address as the Institution ID. Staff users do not require this field.
User Type Enter your IdP's attribute name Recommended userType, role, accountType, Role Determines if user is student or staff. If omitted, defaults to student during JIT creation. For existing users, an explicitly-provided value that does not match the account's existing user type will be rejected (see Role Mismatch Protection).

Subject Attribute Required

Critical requirement: Your Identity Provider's SAML assertion must include a Subject attribute. This is not configurable in Arbol's mapping interface.

  • The Subject attribute must contain the user's unique SSO identifier

Flexible Attribute Mapping

For all other fields (Email, First Name, Last Name, Institution ID, User Type), you can use any attribute names your IdP provides. The attribute names in the "Common Examples" column are just suggestions.

How it works:

  1. Your IdP sends a SAML assertion with various attributes (e.g., mail, givenName, sn, employeeNumber, role)
  2. You configure the mapping by entering your IdP's exact attribute names in the Arbol interface
  3. Arbol reads those specific attributes from the SAML response and maps them to our user fields

Examples: - If your IdP sends email as emailAddress, enter emailAddress in the Email field - If your IdP sends first name as given_name, enter given_name in the First Name field - If your IdP sends student ID as emplid, enter emplid in the Institution ID field - Attribute names are case-sensitive - enter them exactly as your IdP sends them

User Type Attribute Behavior

  • Arbol recognizes only two user types: student and staff
  • If the User Type attribute is blank or not provided during JIT creation, the user will default to student role
  • For existing users, see Role Mismatch Protection below — providing a User Type that doesn't match the existing account will reject the login

Role Mismatch Protection

To prevent role downgrade attacks and configuration errors, Arbol rejects SSO logins when the IdP claim's User Type does not match the existing account's role.

Account Type Claim's User Type Result
Staff staff (or omitted) ✅ Login proceeds
Staff student ❌ Rejected with role_mismatch error
Student student (or omitted) ✅ Login proceeds
Student staff ❌ Rejected with role_mismatch error

What to do if you see this error:

  • If a user changed roles (e.g., student became staff), an Arbol administrator must manually update the user's role in Arbol's admin panel before SSO will work
  • If your IdP is misconfigured to send the wrong User Type, fix the attribute mapping in your IdP
  • If you don't want this check, omit the User Type attribute from your IdP claim entirely

Attribute Update Behavior

User attributes from the IdP claim are handled in three different ways depending on how sensitive they are to identity binding.

Synced on every successful login (no admin action needed):

  • First Name — updated when the claim differs from the stored value
  • Last Name — updated when the claim differs from the stored value
  • Institution ID — updated when the claim differs, subject to a uniqueness check at the school. If another user at the same school already has the incoming Institution ID, the update is skipped silently and the login still proceeds. Case is preserved exactly as your IdP sends it.

Set once during bootstrap, then locked to admin control:

  • SSO Identifier (NameID) — set automatically the first time a user authenticates via SSO if their SSO Identifier is currently blank (the "bootstrap" path — see below). After the SSO Identifier is set, it is only changeable by an administrator. If your IdP starts sending a different NameID for an already-bound user (e.g., you reconfigured NameID source from email to UUID), that user will not be able to authenticate via SSO until an administrator updates their SSO Identifier in Arbol.

Never synced from the IdP:

  • Email — once an account is created, the email is permanent in Arbol regardless of what your IdP sends. To change a user's email, contact Arbol support.

Why email and SSO Identifier are protected

These two fields are the foundation of identity binding between your IdP and Arbol. If either could be silently updated by the IdP, a misconfigured or compromised IdP could effectively reassign Arbol accounts to different people without admin awareness. By requiring administrator action for changes, a compromised IdP cannot silently take over a user's Arbol account — the worst case is locked-out users, not hijacked accounts, and the cause is auditable.

Updating SSO Identifier After It's Set

If your IdP changes the NameID it sends for an existing user (common after NameID source reconfiguration or IdP migration), the user will encounter user_not_provisioned or user_creation_failed errors on their next login. To restore access:

Preferred: User Import via Data Management

  1. Navigate to Data Management in Arbol
  2. Export the affected users to CSV (or use your existing user roster file)
  3. Update the SSO Identifier column with the new NameID value(s)
  4. Re-upload the CSV via User Import
  5. Affected users can now log in via SSO

This is the recommended approach for any update affecting more than a handful of users — it gives you an auditable record of the change in your import history.

For a single user: ActiveAdmin

Arbol staff can update an individual user's SSO Identifier directly via the user edit page in ActiveAdmin if a CSV re-import is impractical.

Fallback: Contact Support

If neither approach works for your situation (e.g., you're locked out of Data Management or unsure of the new NameID values), contact Arbol support and we'll help diagnose and resolve.

Bootstrap path for first-time SSO

When you first enable SSO for a school, users imported via CSV without an SSO Identifier value can still log in. On their first successful SSO login, Arbol matches them by email (only if their SSO Identifier is blank) and automatically populates their SSO Identifier field with the exact NameID value the IdP sent (case preserved). This is the "bootstrap" path — it lets you onboard SSO incrementally without needing every user's NameID up front.

Once SSO Identifier is populated (whether via the bootstrap, by your CSV import, by ActiveAdmin, or by JIT provisioning of a brand-new account), the user is "bound" and only an exact NameID match from your IdP will authenticate them on subsequent logins. Email fallback is no longer available for that user.

Institution ID conflicts

If a student's Institution ID changes in your IdP to a value that another active student at the same school already has, Arbol will skip the Institution ID update silently — the user will still be able to log in, but their Institution ID in Arbol will not be updated. This typically indicates a data quality issue at the IdP that requires manual investigation. Contact support if you need to identify which users are affected.

5. Email Domains

Configure which email domains should trigger a redirect to your IdP login from Arbol's login screen.

How it works:

  1. When a user enters their email on the login page, Arbol checks if the domain matches any configured email domains
  2. If a match is found, the user is redirected to SSO authentication
  3. If no match is found, the user sees the standard username/password login

Adding Email Domains:

  • Enter the domain name (e.g., university.edu) - do not include the @ symbol
  • Click "Add Domain" to add it to your configuration
  • You can add multiple domains for institutions with multiple email systems
  • Domains can be removed by clicking the X button next to each domain

Email Domains Required

You must add at least one email domain for SSO to function. Email domains determine which users will be automatically redirected to SSO login based on their email address.

Testing Your Configuration

The Authentication page provides a walk through to progressively test the full integration with Arbol and your IdP. Refer to the instructions on page to first test the functionality after the redirect would have occurred, then test the experience with a real user from our login screen.

Session Management and Security

Understanding how Arbol manages SSO sessions is important for security planning and user experience.

Session Timeout Behavior

Arbol Local Session:

  • Default session duration: 8 hours with activity-based refresh
  • Session extends automatically if user is active within any 15-minute window
  • Example: A user who clicks or navigates every 10 minutes will maintain their session for the full 8 hours

IdP Session Integration:

  • If your Identity Provider specifies a session timeout in the SAML assertion, Arbol will honor the lower of the two timeouts
  • Example: If your IdP sets a 2-hour session timeout, Arbol will automatically invalidate the local session after 2 hours
  • The IdP timeout is read from the SAML assertion at login time and applied to that specific session

Session Timeout Limitations

Important security consideration:

  • Arbol sessions do not automatically invalidate based on configuration changes made after the initial SAML assertion
  • If your IdP changes session timeout settings, existing Arbol sessions will continue using the timeout from their original login
  • Users must log out and log back in for new timeout settings to take effect

Single Logout (SLO) Behavior

When SLO is Triggered:

Arbol initiates the Single Logout flow only when:

  • The user explicitly clicks the "Log Out" button in the Arbol application
  • The logout action calls your IdP's SLO endpoint to terminate the IdP session

When SLO is NOT Triggered:

Arbol does not initiate SLO when:

  • The local session expires due to timeout (IdP session remains active)
  • The user closes the browser without logging out (IdP session remains active)
  • The Arbol session is invalidated server-side (IdP session remains active)

Session Timeout vs. Single Logout

Key distinction:

  • Session timeout = Local Arbol session invalidation only
  • Manual logout = Calls IdP SLO endpoint to terminate both sessions

When an Arbol session times out (either due to our 8-hour limit or your IdP's timeout), we only invalidate the local session. The user's IdP session may still be active, which means they could re-authenticate to Arbol without entering credentials again if the IdP session hasn't expired.

Security Considerations for Shared Devices

Important for Public/Shared Computer Environments

If your IdP does not support Single Logout (SLO):

  • Users must be educated to always click "Log Out" when finished
  • Simply closing the browser will leave both the Arbol and IdP sessions active
  • The next user on the same device may be able to access the previous user's account
  • This is especially critical in:
    • Library computer labs
    • Shared office workstations
    • Public kiosks
    • Any multi-user environment

Recommended actions:

  1. Verify if your IdP supports SLO before deploying SSO in shared environments
  2. Configure a shorter session timeout in your IdP's SAML assertion to reduce the window of exposure (e.g., 1-2 hours instead of 8 hours)
  3. Provide clear user training on the importance of clicking "Log Out"
  4. Consider posting physical reminders near shared computers
  5. If your IdP doesn't support SLO, consider whether SSO is appropriate for public computer access

Session Security Summary

Scenario Arbol Session IdP Session SLO Called?
User clicks "Log Out" Terminated Terminated Yes
8-hour timeout reached Terminated Active No
IdP timeout reached (per assertion) Terminated May be active No
User closes browser Active (until timeout) Active No
Inactivity (>15 min, <8 hours) Active Active No

Maintenance and Certificate Management

Annual Metadata Refresh

SAML certificates have expiration dates and must be refreshed regularly to maintain secure authentication.

Required Annual Tasks

Both parties must refresh metadata at least once per year:

Your Responsibility:

  • Refresh Arbol's metadata in your Identity Provider at least once per year
  • Use the metadata URL: https://api.growarbol.com/auth/saml/metadata
  • This ensures your IdP has our current certificate and configuration

Arbol's Responsibility:

  • Arbol will automatically refresh your metadata once per year if you provide a metadata URL
  • This ensures we have your current certificate and configuration
  • If using a static metadata file upload, you must manually re-upload when your certificate changes

Certificate Rotation

If you need to rotate your IdP certificate before the annual refresh:

Early Certificate Rotation Options

Option 1: Dual Certificate Support (Recommended)

  • Configure your IdP to support both the old and new certificates during the transition period
  • Update your metadata URL to include both certificates
  • Arbol will automatically pick up the new configuration on our next metadata refresh
  • Remove the old certificate after confirming the new one is working

Option 2: Manual Sync

  • If your IdP cannot support dual certificates, you must manually trigger a metadata refresh in Arbol
  • Log into the Arbol Authentication configuration page
  • Re-enter your metadata URL or upload a new metadata file
  • Click Save to force an immediate metadata refresh
  • Test the new configuration before removing the old certificate from your IdP

Best Practice

Plan certificate rotations at least 30 days before expiration and maintain dual certificate support during the transition to avoid authentication disruptions.

Troubleshooting

Authentication Errors

When SSO authentication fails, Arbol will display an error message on the sign-in page. The URL will include an error query parameter indicating the failure reason.

Error Code Likely Cause Self-Service Remediation
authentication_failed SAML signature invalid, certificate expired, or assertion validation failed Verify your IdP certificate is current and matches the metadata Arbol has on file. Refresh metadata if needed.
sso_not_configured School has no SSO configuration or the configuration is inactive Verify your Authentication page settings are saved and SSO is toggled on.
sso_identifier_mismatch An Arbol user with this email exists, but their SSO Identifier is bound to a different value than the IdP sent Update the user's SSO Identifier to match the IdP's current NameID via User Import (preferred) or ActiveAdmin (see Updating SSO Identifier After It's Set).
user_not_provisioned User does not exist in Arbol and JIT provisioning is disabled Enable JIT provisioning, or import the user via User Import before they attempt to log in.
user_creation_failed JIT tried to create a user but validation failed (e.g., duplicate Institution ID conflict at the school) Resolve the underlying conflict before retry. Most commonly this means another student at the school already has the Institution ID being claimed.
role_mismatch The IdP claim's User Type does not match the existing Arbol account's role See Role Mismatch Protection — update the user's role in Arbol's admin or fix the IdP attribute mapping.
invalid_school The tenant ID in the SAML callback URL does not match a known school Verify the ACS URL configured in your IdP is correct (it must include your school's tenant ID).
saml_processing_error Unexpected exception during SAML response processing Contact support with the timestamp of the failure.

Error Investigation Required

If users encounter SSO authentication errors and the self-service remediation does not resolve the issue:

  • Contact Arbol support at support@growarbol.com for investigation
  • When contacting support about authentication issues, include:
    • Identity Provider Name (e.g., "Okta", "Azure AD", "Shibboleth")
    • Error code from the URL query parameter (?error=...)
    • Email of affected user(s)
    • Timestamp of the failed login attempt
    • Screenshot of the error message (if possible)
    • Whether the issue affects all users or specific users

Authentication Logs

SSO authentication logs are currently only accessible via Arbol support. Contact support to request log analysis for troubleshooting authentication issues. Self-service log access will be added in a future release.

Support will investigate server-side logs and SAML response details to diagnose the issue.

Debug Tools

For troubleshooting SAML issues, these browser tools can help capture SAML requests and responses:

  • SAML-tracer (Firefox extension) - Captures SAML messages
  • SAML Chrome Panel (Chrome extension) - Captures SAML messages
  • Browser Developer Tools - Network tab for viewing SAML responses

Debugging with Browser Tools

When working with support to diagnose SSO issues, SAML-tracer or similar tools can capture the full SAML assertion from your IdP, which helps identify:

  • Which attributes your IdP is actually sending
  • Whether Subject is included in the assertion
  • The exact attribute names being used
  • Any missing required attributes

Share these SAML captures with support (remove sensitive data first) to expedite troubleshooting.