Made in Builder.io

Join us for the biggest Figma-to-code launch of the year

Builder.io logo
Talk to Us
Platform
Developers
Talk to Us

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin


Single Sign-On with Okta

enterprise plans

If your organization is using Okta as an identity provider, you can set up Single Sign-On (SSO) with either OIDC or SAML 2.0. This guide covers both methods of integrating with Okta.

To get the most out of this guide, you must be:

  • On an Enterprise plan
  • An Organization Admin

There are two main steps to setting up SSO with Builder and Okta:

  1. Configuring Okta by creating an application integration
  2. Configuring Builder by adding Okta

1. Go to your Okta Dashboard and expand the Applications section. The redirect URL takes the following format: https://my-org-admin.okta.com/admin/apps/active.

2. Click Applications.

3. Click the Create Application Integration button.

4. In the dialogue that opens, choose OIDC - OpenID Connect for the Sign-in method.

5. For the Application type, choose the type of application you're developing.

6. Click Next.

7. Name the app integration Builder.io.

8. Add the Builder logo. Click the image below to open the logo in a new tab if needed.

Builder Logo

9. Add the Sign-redirect URI:

https://builder.io/login/saml/builder?authDomain=new

10. Select an option in the Assignments section according to your needs. In the example video at the end of this section, we elected to skip that part.

11. Click Save.

The following video demonstrates this process in Okta:

While in Okta, take note of your Client ID and your Issuer URL, which you need when you configure Builder. They are located as follows and as highlighted in the next image.

  • Client ID: Okta Dashboard -> Applications -> General -> Client Credentials.
  • Issuer URL: Click on your name in the upper right. Hover over the domain to copy.
Image of the Applications section of the Okta dashboard. The Client ID and Issuer URL have labels and arrows pointing at them to help locate them.

By default, usernames are not mapped between Builder and identity providers. However, administrators can establish this connection by mapping a specific name field from the identity provider to the name attribute in Builder.

To map usernames in Okta:

  1. Go to your Okta dashboard.
  2. Expand the Applications section and go to Applications.
  3. In the Sign On tab, in the Settings section, click on Configure Profile Mapping.
  4. Choose the field you'd like to map for the users names.

The image below shows the profile mappings in Okta for the name.

Screenshot of the profile mappings in Okta with user dot displayName mapped to Builder's name string.

To integrate Okta with Builder:

  1. Go to your Organization Settings.
  2. Click the Edit button next to Sign Sign-On.
  3. For SSO method, choose OIDC.
  4. Enter a human-friendly display name. This is the name that your users will refer to.
  5. Enter a Provider ID for the SSO Name field. You'll use this to sign into Builder through a URL such as https://builder.io/login/oidc/demo-org.
  6. Enter the Client ID that you noted during the Okta configuration. You can find it in your Okta Admin Dashboard -> Applications -> General -> Client Credentials.
  7. Enter your Issuer URL that you noted during the Okta configuration. Usually, it has the format of your-company.okta.com. You can find it in the menu that displays when you click on your name at the upper right of the Okta dashboard.
Screenshot of the configuration settings for SSO in the Organization Account Settings.

After saving the SSO integration, you can test the login flow by logging out and visiting https://builder.io/login/oidc/<your-sso-name>.

Tip: You cannot use SSO if your browser doesn't support cookies. If you're in an incognito window, ensure that cookies are enabled.

You can optionally add the integration to your Okta dashboard so users can sign into Builder directly from Okta:

  1. Go to the Okta Admin Dashboard -> Applications -> General -> Login.
  2. Add your SSO name that you configured above in the Initiate login URI field. For example, https://builder.io/login/oidc/<your-sso-name>.

The following image illustrates where to add the SSO name:

Screenshot of the Okta Login Settings with Display application icon to users checked, Redirect to app to initiate login (OIDC Compliant) selected, and the login URI entered.

1. Go to your Okta Dashboard and expand the Applications section. The URL takes the following format: https://my-org-admin.okta.com/admin/apps/active.

2. Click Applications.

3. Click the Create Application Integration button.

4. In the dialogue that opens, choose SAML 2.0 for the Sign-in method.

6. Click Next.

7. Name the app integration Builder.io.

8. Add the Builder logo. Click the image below to open the logo in a new tab if needed.

9. Add the Single Sign-On URL:

https://builder.io/login/saml/builder?authDomain=new

10. Add your Audience URI (SP Entity ID).

11. Click Show Advanced Settings.

12. Add your SAML Issuer ID in this format: http://www.okta.com/${org.externalKey}.

13. Click Next.

OpenID Connect (OIDC) builds on OAuth 2.0 so applications can authenticate users and retrieve their basic information in a standardized way. OAuth 2.0 supports different authorization strategies, including:

  • Implicit flow: for browser-based apps. It is less favored as it can expose tokens to the browser.
  • Authorization Code Flow: is preferred for its security, suitable for apps that can manage a Client Secret without exposing it, as it conducts token exchanges away from the user's browser. The Client Secret acts as a password between the app and the authorization server to safely exchange an authorization code for an access token.

When setting up OIDC for SSO in Builder.io, you have the option to include a client secret in your Builder SSO configuration, which indicates that you want to use the code flow. If you don't include a client secret, Builder defaults to using the implicit flow.

To add your IdP's Client Secret to your Builder SSO configuration:

  1. In Okta: Get your Client Secret from Okta. Refer to their docs for finding your application credentials.
  2. In Builder: Go to Builder's Organization Settings.
  3. Click the Edit button for Single Sign-On. Note that you must have SSO enabled for your Organization before this option is available in your Organization Settings.
  4. For the SSO Method, make sure you've selected OpenID Connect.
  5. Paste the Client Secret in the Client Secret field.
  6. Click the Save button.
Screenshot of the SSO dialogue in Builder with a circle around the IdP Client Secret field. It is the fifth field in the dialogue and displays when the selected SSO Method is OpenID Connect.

Due to recent browser updates, if you previously used the Firebase URL, you must update your authentication domain for SSO to ensure compatibility and security.

To accommodate these changes while maintaining existing SSO configurations, use the new URL as well as the authDomain=new param with the login URL:

  1. Replace the previous redirect URL of https://builder-3b0a2.firebaseapp.com/__/auth/handler with the new domain https://builder.io/__/auth/handler. This applies to both SAML and OIDC configurations and must be updated in the Identity Provider (IdP) settings.
  2. Append the query parameter authDomain=new to the login URL. For example, a bookmarked login URL would be formatted as https://builder.io/login/saml/builder?authDomain=new.

Omitting this query parameter will result in incompatibility with the new custom domain. Consequently, SSO may not function with the latest versions of browsers such as Firefox and Safari.

For IdP-initiated logins, the login URL provided by the IdP must also include the authDomain=new parameter to ensure seamless integration.

For more information on adding Builder to your Okta dashboard with the new authentication domain, read Adding Builder to your Okta dashboard.


Looking to hire a third party to help with your project?

Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.

Connect with us

Was this article helpful?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Get the latest from Builder.io

Newsletter

Developer Newsletter

Latest tips, tricks, and news for frontend developers from our blog

Product Newsletter

Latest features and updates on the Builder.io platform

By submitting, you agree to our Privacy Policy