Introduction
Foundational supports Single Sign-On (SSO) via multiple Independent Providers (IdPs) who use the industry-standard protocols, SAML 2.0 or OpenID Connect (OIDC).
Generally, you (or whoever has admin rights in Foundational and the IdP) sets up SSO either as part of the First time login process or very soon after that.
We have online wizards for each SSO connection that guide you through the process.
In addition to SAML and OIDC, users can also single sign in using their GitHub, Google or Microsoft account.
Prerequisites
You need to have the Admin role in Foundational and admin permissions in your IdP.
Supported Identity Providers
Identity provider | Supported protocols |
Okta | SAML 2.0, OpenID Connect (OIDC) |
Azure Active Directory | SAML 2.0, OpenID Connect (OIDC) |
Google Workspace | SAML 2.0 |
Ping Identity | SAML 2.0 |
OneLogin | SAML 2.0 |
JumpCloud | SAML 2.0 |
Rippling | SAML 2.0 |
Custom SAML | SAML 2.0 |
SSO Setup parameters
When you set up SSO, Foundational and the IdP each need certain parameters from the other side.
SSO Protocol | Parameter | Description |
SAML 2.0 | SSO URL | The IdP endpoint where Foundational sends authentication requests. |
SAML 2.0 | Entity ID | The unique identifier for your IdP instance. |
SAML 2.0 | X.509 certificate | The IdP’s public key for verifying signed assertions. |
OpenID Connect (OIDC) | Discovery (issuer) URL | The IdP metadata endpoint. |
OpenID Connect (OIDC) | Client ID | The application identifier generated by the IdP. |
OpenID Connect (OIDC) | Client secret | The shared secret for token exchange. |
OpenID Connect (OIDC) | Redirect URI | The callback URL provided by Foundational (must be registered in your IdP). |
Foundational parameters to send to the IdP are listed as part of each on-screen wizard.
Generic SSO workflow
The connection process is similar for all IdPs, but the specific steps in Part 1 and Part 3 are different for each IdP.
Specific workflows for each IdP
We’ve a wizard for each IdP. Here’s how to open the wizard.
Click your avatar, then go to User Management and select the SSO tab.
Click Set up SSO connection. The Setup screen opens.
Click the relevant icon for a SAML IdP or an OIDC IdP.
A wizard opens specifically for the selected IdP and protocol.
Okta (SAML)
Okta (SAML)
This is the start screen that also shows the main process steps.
Azure (SAML)
Azure (SAML)
This is the start screen that also shows the main process steps.
Google
This is the start screen that also shows the main process steps.
onelogin
onelogin
This is the start screen that also shows the main process steps.
PingIdentity
PingIdentity
This is the start screen that also shows the main process steps.
Jumpcloud
Jumpcloud
This is the start screen that also shows the main process steps.
RIPPLING
RIPPLING
This is the start screen that also shows the main process steps.
Custom SAML
Custom SAML
This is the start screen that also shows the main process steps.
Okta (OpenID Connect)
Okta (OpenID Connect)
This is the start screen that also shows the main process steps.
Custom OpenID
Custom OpenID
This is the start screen that also shows the main process steps.
Troubleshoot SSO connections
Here are some possible issues and recommendation actions.
Issue | Cause | Action |
Invalid SSO URL | URL copied incorrectly | Recheck the ACS URL in Foundational. |
Invalid certificate | Certificate expired or corrupted | Upload a new X.509 certificate from your IdP. |
Login loop | Mismatch between Entity ID or ACS URL | Confirm both match in Foundational and your IdP. |
User cannot sign in | User not assigned in IdP | Assign the user or group to the Foundational app. |
OIDC connection fails | Redirect URI missing or not registered | Add the Foundational callback URL to your IdP configuration. |
Profile details missing | User attributes not mapped | Ensure |
Cannot sign in with non-SAML connections |
| See the tip below. |
Troubleshoot non-SAML SSO connections
If you have a non-SAML connection and can’t log in with GitHub, Google or Microsoft, then try this.
Log in to https://www.foundational.io/ and click Sign in.
Enter your email and click Continue.
In a minute or two, you should receive an email with a code to login. Check your Spam folder if needed.
From the email, enter the code you received and click Continue.
That should enable you to log in.
Still can’t connect?
Reach out to customer support. We’re here to help!