Okta enterprise connection (OpenID Connect or SAML)

If your customers or users work at companies that use Okta to manage sign-in, their IT team may ask for an enterprise connection, so their people can sign in to your website or app with their Okta account and only the people they allow can. Bread & Butter supports two ways to set this up: OpenID Connect and SAML. This article helps you choose, then walks through each one.

In short: An enterprise connection lets people sign in through their organization's Okta account, under rules their IT team controls. OpenID Connect is the simpler option: in the Okta Admin Console, create an OIDC web application with the sign-in redirect URI https://api.breadbutter.io/callback  , choose who can use it, copy the Client ID and Client Secret, and note your Okta URL. SAML is for IT teams that require it: create a SAML 2.0 app with the single sign-on URL set to the same address and your Bread & Butter App ID as the Audience URI, add the email, first name, last name and user ID attribute statements, copy the issuer, sign-on URL and X.509 certificate from the IdP metadata, and assign your users. Then paste those values into Bread & Butter under Settings, then Global Conversion Methods, then Enterprise Connections.

Need a hand? Setting up an enterprise connection can feel a bit overwhelming. We offer a free 15-minute onboarding session to help you get this configured. Book your session with a specialist here.

OpenID Connect or SAML?

Both let people sign in with their Okta account. Choose one.

  • OpenID Connect is the simpler, more modern option, and the one to choose if nobody has asked for SAML. It's also the one to use if your site needs Okta access or refresh tokens.
  • SAML is the one to choose when a customer's IT team requires it.

Two things work differently with SAML. You replace a certificate instead of a client secret, and Return Authorization Data isn't available, so Bread & Butter can't pass an Okta access token to your site. See What are scopes and access tokens, and how do I request more access from a sign-in provider?

What you'll need

  • An Okta administrator account, with permission to create app integrations and assign users.
  • Your Bread & Butter dashboard.

Set up OpenID Connect

In Okta

Step 1

Log in to your Okta account as an administrator.

Step 2

In the left navigation, click the Applications dropdown, then click on Applications.

Step 3

On the Applications page, click the Create App Integration button above the app list.

Step 4

  • For Sign-in method, select OIDC - OpenID Connect.
  • For Application type, select Web Application.
  • Click Next.

Step 5

  • For App integration name, use your organization's name.
  • Select Use Okta-generated client ID.
  • For Sign-in redirect URIs, enter: https://api.breadbutter.io/callback  

Step 6

  • Under Assignments, select and configure the controlled access option that suits your needs.
  • Click Save.

Step 7

Optional: complete this step if your site will need a refresh token from Okta.

  • Go to the General tab.
  • Click Edit next to General Settings.
  • Enable Refresh Token under the Grant type section.
  • Click Save.

Note: This setting can be updated at any time. To receive tokens on your site, also turn on Return Authorization Data for this connection in Bread & Butter (see the scopes article linked above).

Step 8

At the top of the General tab, copy and save the Client ID and Client Secret for the Bread & Butter setup below.

Step 9

Take note of your Okta account URL, also called the base URL (for example, https://company1.okta.com/  ). You can find it on the Sign On tab, as the Issuer field under OpenID Connect ID Token.

Step 10

Assign your users to the app. Note: You can skip this step if you've enabled Federation Broker Mode.

In Bread & Butter

Step 11

  1. Log in to your Bread & Butter dashboard: https://app.breadbutter.io
  2. Go to Settings in the left menu, then go to the Global Conversion Methods tab.
  3. Click the Okta button under Enterprise Connections.
  4. Choose OpenID Connect for the protocol.
  5. Enter a name.
  6. Enter a description (optional).
  7. Using your Okta base URL, enter the Login URL as [BASEURL]/oauth2/v1/authorize  , for example https://company1.okta.com/oauth2/v1/authorize  .
  8. Enter the Token URL as [BASEURL]/oauth2/v1/token  , for example https://company1.okta.com/oauth2/v1/token  .
  9. Enter your Client ID and Client Secret from the Okta steps above.
  10. Click Save.
  11. Enable Okta by clicking the new entry in the Okta connections list.

Set up SAML

In Okta

Step 1

Log in to your Okta account as an administrator.

Step 2

In the left navigation, click the Applications dropdown, then click on Applications.

Step 3

On the Applications page, click the Create App Integration button.

Step 4

  • For Sign-in method, select SAML 2.0.
  • Click Next.

Step 5

For App name, enter your organization's name. Then click Next.

Step 6

  • For Single sign-on URL, enter: https://api.breadbutter.io/callback  
  • For Audience URI (SP Entity ID), enter your Bread & Butter App ID. You'll find it in Bread & Butter under Settings, on the App & Domains tab.

Step 7

Click Show Advanced Settings, and make sure the following are set:

  • Response set to Signed
  • Assertion Signature set to Signed
  • Assertion Encryption set to Unencrypted

Click Next.

Step 8

  • Select This is an internal app that we have created.
  • Click Finish.

Step 9

Go to the Sign On tab, scroll down to Attribute Statements, and expand Show legacy configuration. Add the following under Profile attribute statements:

Name Value
email   user.email  
first_name   user.firstName  
last_name   user.lastName  
uid   user.id   (type this value; it isn't in the dropdown)

Click Save.

Step 10

  • On the Sign On tab, scroll down to SAML Signing Certificates.
  • Click Actions, then View IdP metadata for the active certificate.

Step 11

In the metadata, take note of these three values for step 13:

  • The entityID: this is your Identity Provider Issuer.
  • The Location: this is your Identity Provider Single Sign-On URL.
  • The X509Certificate value.

Step 12

Go to the Assignments tab and assign your users or groups to this Okta app.

In Bread & Butter

Step 13

  1. Log in to your Bread & Butter dashboard: https://app.breadbutter.io
  2. Go to Settings in the left menu, then go to the Global Conversion Methods tab.
  3. Click the Okta button under Enterprise Connections.
  4. Choose SAML for the protocol.
  5. Enter a name.
  6. Enter a description (optional).
  7. Enter the Identity Provider Single Sign-On URL from step 11.
  8. Enter the Identity Provider Issuer from step 11.
  9. Enter the X.509 Certificate from step 11. Do not include -----BEGIN CERTIFICATE-----   and -----END CERTIFICATE-----  .
  10. Click Save.
  11. Enable Okta by clicking the new entry in the Okta connections list.

Keep your credentials current

Client secrets and SAML signing certificates can expire or be rotated by your IT team. When either changes in Okta, paste the new value into the matching connection in Bread & Butter straight away; until you do, people can't sign in with that connection. If you think a client secret has been exposed, replace it. See What is a client secret, and what do I do if one is compromised?

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.