Skip to main content

How to set up employee and Admin SSO via OIDC

Step-by-step instructions for setting up SSO as a login for both employees and Admins

Cocoon Support avatar
Written by Cocoon Support
Updated over 2 weeks ago

Important note

If you currently have Admin-only SSO enabled via Okta, you will need to update your configuration to enable SSO for employees ➡️ See here for instructions

How does SSO work with Cocoon?

Cocoon currently supports employee and employer admin SSO via OpenID Connect (OIDC).

Cocoon does not currently support SAML, auto-provisioning via SCIM or API, or auto-assignment of permissions for Employer Admin accounts.

Important note

The email address passed to Cocoon via SSO must match the email address used to create the Cocoon account and email address provided in the census. For example, if an employee would use "[email protected]" to create their account, the email address passed via SSO must be "[email protected]".

Employee login experience with SSO

  • To register, employees can either:

    • Access Cocoon via your company’s unique Cocoon signup link (app.cocoon.com/COMPANY). We will verify who they are with their work email address, then prompt them to add their personal email and create a password.

    • Access Cocoon via SSO to create their account upon first login. We will verify who they are with their work email address, then prompt them to add their personal email and create a password.

  • For all subsequent logins after registration, employees will be able to log in to Cocoon via SSO or with their personal email address and password.

Admin login experience with SSO

  • Employer Admins must be invited to set up their account

  • To register, Admins will sign up with their work email and create a password

  • For all subsequent logins, Admins will be able to log in to Cocoon via SSO or via their work email address and password

  • For more information on the Employer Admin experience including how to link an Employee account to an Admin account, please see our article on Switching between your Admin and employee accounts in Cocoon.

How to configure SSO via OIDC

Do you want to enable SSO via ADP Workforce Now®, Okta, or Microsoft Entra ID?

For generic OIDC instructions, refer to the instructions below.

Cocoon has validated OIDC SSO via these providers:

  • Okta

  • Cloudflare Access

  • OneLogin

  • Microsoft Entra ID

💡 Tip: You’ll need to copy values between Cocoon and your SSO Provider, so we recommend opening two side-by-side windows here.

Part I: Configure your SSO Provider

  1. Create a new OIDC application in your SSO provider

  2. Fill in the following information, which you can find in Part II below:

    1. Redirect URL, which will be in this format: https://app.cocoon.com/login/callback/{SSO_PROVIDER}?tenantId={ORG_NAME}

      1. Example: https://app.cocoon.com/login/callback/okta?tenantId=mycompany

    2. (If available) Signout URL: https://app.cocoon.com/logout

    3. IdP-initiated login URL, which is the same as the Redirect URL. This may be in another section or tab. Format: https://app.cocoon.com/login/callback/{SSO_PROVIDER}?tenantId={ORG_NAME}

      1. Example: https://app.cocoon.com/login/callback/okta?tenantId=mycompany

  3. Copy the Client ID, Client Secret, and Issuer URL into Cocoon as described in the section below

Part II: Configure SSO in Cocoon

Important note

If you don't see SSO available on your Cocoon Settings page, please reach out to your Customer Success Manager or [email protected].

  1. Go to the SSO Setup page:

    1. If you are an existing Cocoon customer: Click on "Settings" in the bottom of the side navbar in your Cocoon Dashboard, then choose "SSO"

    2. If you are currently onboarding: You'll see an optional task labeled "Set up SSO" in your onboarding dashboard. Click the "Start" button to see this page.

  2. Select your SSO Provider from the "SSO Provider Name" dropdown. If it isn't listed, choose Generic OIDC SSO.

  3. Next, copy the “Client ID” from your SSO provider and paste it into the corresponding field in the SSO settings screen

  4. Then, copy the “Client Secret” from your SSO provider and paste it into the corresponding field in the SSO settings screen. If your provider has both a “Secret ID” and “Secret Value”, please use the “Secret Value” here.

  5. Finally, copy the “Issuer URL” from your SSO provider and paste it into the corresponding field in the SSO setting screen

How to configure OIDC SSO using Okta

  1. Log in to Okta as an administrator and select “Applications” in the navigation bar.

  2. Create a new application by selecting the "Create App Integration" button.

  3. Choose "OIDC - OpenID Connect" application:

4. On the next page, fill out the following fields:

  • For Logo, you can download the below image or see here to download as a .png

Information that needs to be configured in Cocoon

Please see Part II: Configure SSO in Cocoon above for how to input this information in Cocoon.

To find each piece of information in Okta:

  • "Client ID" and "Client Secret" are under the General tab

[Optional but recommended] Enable Okta-initiated logins to add Cocoon to employees' Okta login portal

  1. Edit "Login initiated by" field under "General" tab

  2. Initiate login URI: You should've received an "IdP-initiated Login URL" by Cocoon with the format of https://app.cocoon.com/login/callback/{SSO_PROVIDER}?tenantId={ORG_NAME}

How to configure OIDC SSO using Microsoft Entra ID

Prerequisites: You'll need admin access to your organization's Microsoft Entra ID (formerly Azure Active Directory) tenant.

Step 1: Register a new application in Microsoft Entra ID

  1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator

  2. Browse to Identity > Applications > App registrations

  3. Select New registration

  4. Fill out the following fields:

    • Name: Enter "Cocoon" or your preferred application name

    • Supported account types: Select "Accounts in this organizational directory only (Single tenant)"

    • Redirect URI: Select "Web" from the dropdown and enter your callback URL with the format: https://app.cocoon.com/login/callback/microsoftonline?tenantId={ORG_NAME}

      • Example: https://app.cocoon.com/login/callback/microsoftonline?tenantId=mycompany

  5. Select Register

Step 2: Create a client secret

  1. In your newly created app registration, navigate to Certificates & secrets in the left sidebar

  2. Under "Client secrets," select New client secret

  3. Add a description (e.g., "Cocoon SSO") and select an expiration period

  4. Select Add

  5. Important: Copy the secret Value immediately and store it securely. You won't be able to view it again after leaving this page. Make sure to copy the Value and not the ID.

Step 3: Configure API permissions

  1. Navigate to API permissions in the left sidebar

  2. The User.Read permission for Microsoft Graph should already be present

  3. Verify the following delegated permissions are included (if not, add them by selecting Add a permission > Microsoft Graph > Delegated permissions):

    • openid (Required for OIDC authentication)

    • profile (To access user's profile information)

    • email (To access user's email address)

  4. Select Grant admin consent for [your organization] to pre-approve these permissions for all users

Step 4: Gather your configuration details

From the Overview page of your app registration, you'll need the following information to configure Cocoon:

  • Application (client) ID: This is your Client ID

  • Directory (tenant) ID: You'll use this to construct your Issuer URL

  • Endpoints: Select the "Endpoints" button to view available endpoints

For more detailed information about configuring OIDC SSO in Microsoft Entra ID, see Microsoft's documentation on configuring OIDC SSO for custom applications.

Information that needs to be configured in Cocoon

Please see Part II: Configure SSO in Cocoon above for how to input this information in Cocoon.

The values you'll need from Microsoft Entra ID are:

  • SSO Provider: Select "Microsoft Entra ID"

  • Client ID: The Application (client) ID from the Overview page

  • Client Secret: The secret Value you copied in Step 2

  • Issuer URL: https://login.microsoftonline.com/{TENANT_ID}/v2.0 (replace {TENANT_ID} with your Directory (tenant) ID from the Overview page)

[Optional but recommended] Configure Front-channel logout

To ensure users are properly signed out of Cocoon when they sign out of Microsoft Entra ID:

  1. In your app registration, navigate to Authentication

  2. Under "Front-channel logout URL," enter: https://app.cocoon.com/logout

  3. Select Save

Cocoon's logo (.png format)

Attachment icon
Cocoon-logo-green (1).png
Did this answer your question?