# 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](https://docs.foundational.io/en/articles/12807345-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. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823887632/b7bbf3d5ee28db829fe930772c4d/sso+process+flow.png?expires=1781782200&signature=e21f0a900989d3a5270ede397bc1e7c156e5161d1f9fc617060828e56ab7bf56&req=dSglFcF2modcW%2FMW1HO4zZfIw4EeJ%2BJ6zzTPBOMH0r0C1zCwl0C1e2CP%2B9tS%0AYtttjNEoGn80wlB4qK4%3D%0A) --- # Specific workflows for each IdP We’ve a wizard for each IdP. Here’s how to open the wizard. 1. Click your avatar, then go to **User Management** and select the **SSO** tab. 2. Click **Set up SSO connection**. The **Setup** screen opens. ​ 3. Click the relevant icon for a SAML IdP or an OIDC IdP. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823893887/fa96c3d19ea5aa47c9c6b4ac2d61/sso+set+up+select+sso.png?expires=1781782200&signature=8a304b0248fce7b8f80e869c5beee65302ebd129521f97e365db3107c59b4bd6&req=dSglFcF3nolXXvMW1HO4zZl7bzs0ZathdUBQSQQKSl6g%2BbNLcYiNy%2B9euRqj%0Aur71oOb6XqxEpuNcTrw%3D%0A) A wizard opens specifically for the selected IdP and protocol. **## Okta (SAML)** This is the start screen that also shows the main process steps. ​ ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823895034/5aa60b20685faaff0ac5d6382ce2/sso+saml+app+screen+1.png?expires=1781782200&signature=ed666b0a394a95291c3fd4ec562023286e41dd14f487cba2f876a85ed88ab2f3&req=dSglFcF3mIFcXfMW1HO4zQZaBzKEWLV4S6a9G1esbXUTQNv9rhl4epF71fvh%0AozSP69lrFH87rEfUUw0%3D%0A) **## Azure (SAML)** This is the start screen that also shows the main process steps. ​ ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823895754/f9f05647fb5f63235fc147752c1b/sso+azure+screen+1.png?expires=1781782200&signature=ff16b311469a3686e852624de411d690a22f362e21905b5679dd56c205f0d6d9&req=dSglFcF3mIZaXfMW1HO4zWp69cCeEywGlTcKpPRtCgZ2TtHIworFSfjxe6Ef%0AZkkTKcrS5EOJbG9H13k%3D%0A) **## Google** This is the start screen that also shows the main process steps. ​ ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823896386/26810d67d652c26d609f20194ba7/sso+google+SAML+screen+1.png?expires=1781782200&signature=4abdacf2d990e81662a446cc4d3ebfb9a63d9429b76670296c5012084215cc64&req=dSglFcF3m4JXX%2FMW1HO4za1ODgfTICO62wzxxy%2BC3xYeq9HLQE1JsR0wk6gx%0A1lmyIxC3RIn9a85fy1s%3D%0A) **## onelogin** This is the start screen that also shows the main process steps. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823897620/3efb181e14ce04f71998d0e634b6/sso+onelogin+screen+1.png?expires=1781782200&signature=285773ec563f209aed99a9a176bd75c2248962dfeddb856af111f718f7b127fc&req=dSglFcF3moddWfMW1HO4zclRKlddoW3gm2a%2FJlk0h2y1APqxOiLsi%2BePQrrL%0ADrDXGBTn3d9%2F17K%2FLC0%3D%0A) **## PingIdentity** This is the start screen that also shows the main process steps. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823898228/695d8193aada689fc71cb2415910/sso+pingidentity+screen+1.png?expires=1781782200&signature=e224ba1064c94ac80dcf9618500a3c5d6704e1f5569091181df28d4f9d66a1a8&req=dSglFcF3lYNdUfMW1HO4zRiNj9NvSUfkn89N6CZCpYzvc1KL4PeXLkPHlzMY%0AoSUBkt11w0sT%2BgJ4u1Y%3D%0A) **## Jumpcloud** This is the start screen that also shows the main process steps. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823898720/22de783ee90731f73333c0357f7a/sso+jumpcloud+screen+1.png?expires=1781782200&signature=1b3e35efdcad6a57dfea245721038564850f2ba34ce1498ed58f82d2377657d8&req=dSglFcF3lYZdWfMW1HO4zfp%2FCONBszwTYWQ7LiNBZKx7H9ypKMZb7CwoaLUK%0Anm1hcV7ZrmCeUV4mvWI%3D%0A) **## RIPPLING** This is the start screen that also shows the main process steps. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823899286/416574e5a7d416f1a442f2655eb7/sso+rippling+screen+1.png?expires=1781782200&signature=8351f6ff244f349b1571c0827b280149950c47459d3b8101047cb7dc976ca410&req=dSglFcF3lINXX%2FMW1HO4zTw6BPOXxNpPRlu2wVjaH7UXfFYi41Z7S5%2BnOuMn%0APKWfy8IjBvwwHM%2Fvc5w%3D%0A) **## Custom SAML** This is the start screen that also shows the main process steps. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823899859/933f317f32dded9f3ec0a44b7bd1/sso+saml+custom.png?expires=1781782200&signature=3ff1f19d4f041788f7991b59c03652d87d4d84a9ddd26de64e956023e7cd602b&req=dSglFcF3lIlaUPMW1HO4zfQAne0s17Qna5zdJ4bN9zitnfKBefXYwDG%2FLxkz%0AmAE5OS8cCOwgC6JglDM%3D%0A) **## Okta (OpenID Connect)** This is the start screen that also shows the main process steps. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823900322/89338014a0b3791518f365ac3ea1/sso+okta+oidc+screen+1.png?expires=1781782200&signature=21e8ee626bae4b2050a799e63fa098900364ad95e4efbadc36b976866487160c&req=dSglFcB%2BnYJdW%2FMW1HO4zdf9VEOSsCtgdVdoVuXCZGTfN8FphbLuAJP8wAqg%0A2u%2Bb3O7%2BwMzXKve5Zdk%3D%0A) **## Custom OpenID** This is the start screen that also shows the main process steps. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823901011/dbf0de1acce8a401d48c1c77e949/sso+openid+custom.png?expires=1781782200&signature=9e97505c091294a1f30dc488957a7243d2b745bc2e7092edbde42763b8dee5b8&req=dSglFcB%2BnIFeWPMW1HO4zUzm%2FQj9ZpiorOqkjvGxDIRKPVlMRbJlHqKNMRL2%0AfchlB7tMuHk5mMZTY7w%3D%0A) --- # 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 `email`, `firstName`, and `lastName` attributes are included. | | 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. 1. Log in to [https://www.foundational.io/](http://foundational.iohttps//www.foundational.io/) and click **Sign in**. ​ 2. Enter your email and click **Continue.** ​ ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823904497/015c4bcd461edfdf328daf788e54/sso+sign+in+with+email.png?expires=1781782200&signature=977ff9632b7fef1102081923978f606e5bc3f16ad394079696b909e20b6139c9&req=dSglFcB%2BmYVWXvMW1HO4zQO1T3722H3Z0riAALF%2FEMOjufnXyKfV1FO7fcwn%0Ables%0A) 3. In a minute or two, you should receive an email with a code to login. Check your Spam folder if needed. ​ 4. From the email, enter the code you received and click **Continue**. ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1823904916/683bd2bd0436b58cdd759522ca86/sso+veritification+code+enter.png?expires=1781782200&signature=923bdb2808dd40b27755f493d19e0bb2dca5ade84c88a6b165cbf7afffc452bb&req=dSglFcB%2BmYheX%2FMW1HO4zUDORjoDVh523nRr4iz4szYMNAhubfg0gtXk%2BwHh%0AFK%2Bf%0A) That should enable you to log in. --- # Still can’t connect? Reach out to customer support. We’re here to help!