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 SSO via OpenID Connect (OIDC), and employer Admin SSO either via OIDC or Okta (instructions here for setting up Admin SSO via Okta).
Cocoon does not currently support SAML, auto-provisioning via SCIM, or auto-assignment of permissions for Employer Admin accounts.
Employee login experience with SSO
To register, employees will 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.
Employees do not need to be provisioned an account
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
Note: At this time, Admins cannot log in as both an Admin and an employee using the same email address or via SSO. We recommend Admins use SSO for their employee account and using an aliased email to create your Employer Admin account (eg: [email protected]). These accounts can continue to login with email and password from https://app.cocoon.com. Cocoon is working to solve this limitation in the near future.
How to configure SSO via OIDC
Do you want to enable SSO via ADP Workforce Now® or Okta?
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
Create a new OIDC application in your SSO provider
Fill in the following information:
Redirect URL, which will be in this format: https://app.cocoon.com/login/callback/{SSO_PROVIDER}?tenantId={ORG_NAME}
(If available) Signout URL: https://app.cocoon.com/logout
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}
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].
Go to the SSO Setup page:
If you are an existing Cocoon customer: Click on "Settings" in the bottom of the side navbar in your Cocoon Dashboard, then choose "SSO"
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.
Enter the SSO provider’s name or alias in the corresponding field, e.g. “OneLogin”
Next, copy the “Client ID” from your SSO provider and paste it into the corresponding field in the SSO settings screen
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.
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
Log in to Okta as an administrator and select “Applications” in the navigation bar.
Create a new application by selecting the "Create App Integration" button.
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
Sign-in redirect URIs: You should've received a callback URL by Cocoon with the format ofhttps://app.cocoon.com/login/callback/{SSO_PROVIDER}?tenantId={ORG_NAME}
Sign-out redirect URIs: https://app.cocoon.com/logout
Assignments: select a group of users who should have access to your company's Cocoon instance.
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
"Issuer URL" is labeled "Issuer" under the "Sign On" tab.
It is commonly https://MYCOMPANY.okta.com or a custom domain such as https://sso.MYCOMPANY.com.
SSO Provider name: Okta
NOTE: If you were previously using Admin-only SSO via Okta 👉 Once you have successfully switched your configuration, please be sure to email [email protected] to let our team know so we can turn it on for employees.
[Optional but recommended] Enable Okta-initiated logins to add Cocoon to employees' Okta login portal
Edit "Login initiated by" field under "General" tab
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}