Self-Service Single Sign-On (SSO) Configuration Guide

What's changed

• You can now connect your own identity provider - Okta, Microsoft Entra, Google Workspace, or any SAML/OIDC provider - and set it up yourself, without waiting on Acorn.
• Setup happens from your Integrations Hub: generate a one-time link, hand it to your IT team, and they complete a guided wizard.
• One system now handles both SAML and OIDC providers.
• Any SSO connection you already have keeps working exactly as it does today - this is additive, not a migration.

Why it matters

Your users can sign in to Acorn with the same work identity they already use everywhere else - no separate Acorn password to manage or reset. And you're no longer dependent on Acorn's team to stand up the connection: your IT contact drives the whole setup, start to finish, usually in one sitting.

Before you start

You'll need two people, and they can be the same person:

• An Acorn administrator with access to your Integrations Hub - they kick off setup and generate the link.
• Someone with admin access to your identity provider (your IT or IAM team) - they complete the technical setup using the link.

Have your identity provider decided before you start. Supported providers:

• Okta
• Microsoft Entra ID
• Google Workspace
• Any other SAML 2.0 provider (Custom SAML)
• Any other OIDC provider (Custom OIDC)

You can set up up to 3 connections per provider. If you try to add a 4th, you'll see a message pointing you at your existing connections - reach out to your Customer Success manager if you need more.

How to set it up

Step 1: Generate a setup link

1. In Acorn, go to Admin → Integrations Hub.
2. Find the tile for your identity provider (Okta, Microsoft Entra ID, Google Workspace, Custom SAML, or Custom OIDC) and open it.
   
   
3. Give the connection a name (e.g. "Head Office Okta") and click Generate link.
4. Copy the link from the banner at the top of the tile.
   
   

This link is valid for 48 hours and works once. Send it to whoever's completing setup on your IT/identity side as soon as you generate it.

Step 2: Complete the setup wizard

Your IT contact opens the link and works through five steps. They can re-test as many times as they like before going live, and nothing goes live until the last step.

1. Get started - confirms which connection they're setting up.
   
   
2. Create the application in your identity provider's admin console. The wizard provides a downloadable metadata file, plus the Single Sign-On URL and Audience URI to enter by hand if needed. For Okta, Microsoft Entra ID, or Google Workspace, the wizard shows step-by-step guidance for exactly where to click in that provider's console alongside this step. For a custom SAML or OIDC provider, your IT contact will use the provided URLs/metadata to configure their own console.
   
   
3. Map attributes - matches the fields your identity provider sends (name, email, etc.) to the fields on an Acorn user profile. The common fields are pre-filled with sensible defaults; anything else is optional.
   
   
4. Configure the connection - paste in the metadata URL your provider gives you (or upload the metadata file). For OIDC providers, enter the issuer URL, client ID, and client secret instead.
5. Test and enable - run a real sign-in test against the identity provider. On success, the wizard shows exactly what information came through, so your IT contact can confirm it's correct before going live.
   
   

Clicking Enable Connection makes it live - your people can sign in through it from that point on.

What your users see once it's live

The login page automatically shows a way to sign in with your provider:

• One connection → a single "Sign in with..." button.
• More than one → a picker to choose between them, with recognizable logos for Okta, Microsoft Entra, and Google.

Users only ever see the connections that apply to them.

Managing your connection

Once a connection is live, go back to the same tile in the Integrations Hub to maintain it - no need to involve Acorn.

1. Find the connection in the Active connections list and click Manage.
2. This generates a fresh link on the spot, good for 24 hours and one use. If you don't finish in time, just click Manage again for a new one.
3. From there you (or your IT contact) can:
   1. Update the metadata URL if it's moved on your provider's side
   2. Refresh the signing certificate, with its expiry date shown so you can see how soon you'll need to
   3. Update attribute mapping
   4. Run another test sign-in before confirming the change

       

Deleting a connection is available from the same Active connections list, with a confirmation prompt first.

FAQ

Do I need to migrate my existing SSO connection to the new system?

No. If you already have SSO set up, it keeps working unchanged. The new self-serve flow is for setting up new connections - talk to your Customer Success manager if you're interested in moving an existing connection over.

What if my identity provider isn't Okta, Microsoft Entra, or Google?

Use the Custom SAML or Custom OIDC tile. You'll get the same metadata/URL fields to configure your connection, though the wizard won't show provider-specific "click here" guidance the way it does for Okta, Entra, and Google - your IT contact will work from the URLs and metadata provided.

What happens if the setup or manage link expires before we're done?

Just generate a new one from the Integrations Hub - there's no limit on how many times you can do this, and generating a new one doesn't affect anything you've already configured.

Can we have more than one connection to the same provider?

Yes, up to 3 per provider. This is useful if different parts of your organization use separate instances of the same identity provider.

What happens if someone's sign-in fails?

They're returned to the login page with a specific error message (for example, if their account isn't set up to sign in this way yet) rather than a generic failure, and the message clears automatically when the page refreshes.

Can one connection cover multiple parts of our organization?

It can, but that kind of connection is set up by Acorn rather than by you. Contact your Customer Success manager if this applies to you.

Known limitations

• A single connection that covers your entire organization at once isn't something you can set up yourself - Acorn has to configure that for you, so contact your Customer Success manager.
• Up to 3 connections per provider.
• Setup links last 48 hours and work once; manage links last 24 hours and work once.
• Step-by-step "where to click in your provider" guidance is currently available for Okta, Microsoft Entra ID, and Google Workspace. Custom SAML/OIDC providers use the same setup fields but without the inline walkthrough.
• You'll need your own identity provider already in place - Acorn doesn't provision Okta, Entra, or Google accounts for you.