Add a custom OpenID Connect provider

A custom provider puts one more sign-in button on your hosted page, for an identity provider BuildBase has not built in: a Keycloak server, Okta, Auth0, or a sign-in service your company runs itself. It works with any provider that speaks OpenID Connect (OIDC, the standard way one site confirms who someone is for another), or plain OAuth 2.0 with a user info address. The person presses the button, signs in on your provider's page, and comes back to your app signed in. You make a client (an application) in the provider, and swap a few values with BuildBase. The screenshots below use a small test provider named Acme ID, run on its own server, and show a real sign-in through it.

What goes where

Okta calls the last one Sign-in redirect URIs, Auth0 Allowed Callback URLs, and Keycloak Valid redirect URIs.

1. Make a client in your provider

These are the steps the console shows under How to connect your identity provider. In Keycloak, as an example:

1. In your realm, open Clients and choose Create client. Keep OpenID Connect as the type, and give a Client ID, such as acme-analytics.
2. Turn Client authentication on, so the client has a secret, and keep Standard flow, the one that sends the person to the sign-in page and back.
3. Leave Valid redirect URIs for now: you paste BuildBase's at the end of the next part.
4. On the client's Credentials tab, copy the Client secret.
5. Your issuer URL is your Keycloak address with /realms/ and the realm's name, such as https://id.acme.example/realms/acme. In Okta it is your Okta address, and in Auth0 your Auth0 domain with https:// in front.

2. Add the provider in the BuildBase console

1. In the console, open User management, then Authentication under Access, and the Methods tab.
2. Press Add auth method and choose Custom OIDC provider.

3. Fill in the form. Each field:

4. Press Create. BuildBase reads the provider's discovery document before it saves, so a mistyped issuer is refused now rather than at someone's sign-in:

5. With a working issuer, the dialog says One step left and shows the Redirect URL. Press Copy, then Done.

6. In your provider, paste the URL into the client's allowed redirect URLs (Keycloak: Valid redirect URIs) and save.

The redirect URL has this shape:

https://api.console.buildbase.app/api/v1/auth/social/custom/<orgId>/<methodId>/callback

It starts with your BuildBase server, https://api.console.buildbase.app{/* @endstat */} on BuildBase's cloud.

The URL checks

• Discovery or three addresses. Saving with neither an issuer nor all three addresses is refused with "Give an issuer URL, or all three endpoints."
• Every address BuildBase calls must be public. The issuer, and the token, JWKS (signing keys) and user info addresses, including the ones the discovery document names, must resolve to a public address. One that does not is refused with "... does not resolve to a public address BuildBase can reach." A provider on a private network has to be reachable at a public address first. A self-hosted BuildBase may use addresses on its own network; cloud metadata and link-local addresses are refused everywhere.
• The authorization URL is not checked. BuildBase never calls it; it only sends the person's browser there.
• The discovery document must name the same issuer it was fetched for, and list authorization, token and JWKS addresses. Otherwise the save is refused with "The discovery document names a different issuer" or "The discovery document has no authorization, token or JWKS endpoint."
• https:// only on a BuildBase server running in production: a plain http:// address is refused with, for example, "Issuer URL must be an https:// URL." Icon URL is always https://, everywhere: "Icon URL must be an https:// URL."

3. Attach it to your app

1. Open the Settings tab and press Edit on Acme Analytics.
2. Under Methods, tick the provider, listed by its Title, here Acme ID, and press Update.

4. Check the preview

The Preview on the Sign-in page tab shows your look with sample GitHub and Google buttons, not your methods. Press Open the live page for Acme Analytics above it to see the real page with your button.

5. What people see

The hosted sign-in and register pages now have a button with your Button label. With no Icon URL, it shows a key.

On a phone it runs the full width under the form:

Here is a whole first sign-in, for Riley Chen, who has no account yet:

1. Riley presses Acme ID. Their browser goes to the provider's own page, which asks them to sign in, and the first time to share their name and email address with your app.

2. The provider sends them back, and BuildBase makes their account with the name and address the provider sent. Trust is still Never, so BuildBase has not taken the address on the provider's word: the sign-in page asks Riley to type a 6-digit code sent to it. With When it sends email_verified: true and a provider that says so, this step is skipped.

3. After the usual Trust this device? question (and the passkey offer, if your app offers passkeys), Riley is in your app.

Riley now appears under Users in the console, with Sam Rivera from the next section:

Trusting its email addresses

Trust decides whether this provider may sign someone into an account that already has the same email address. BuildBase knows nothing about a provider you added, so it starts at Never.

Trust a provider only if it checks that people own the addresses it sends. Trusting one where anyone can type in any address lets anyone sign into anyone's account.

With Never, Sam Rivera, who already has an account at [email protected], is turned away when he first tries the button:

Sam can sign in as before and connect Acme ID from the Security screen of your app. Or, for a provider that checks addresses, change the trust: press the edit button on the provider's row in Methods, choose When it sends email_verified: true, and press Save.

Sam's next press of the button signs him into his own account and connects Acme ID to it, so later sign-ins find him by the provider's user ID:

What BuildBase reads from your provider

With discovery, BuildBase checks the ID token: its signature against the provider's JWKS (RS256, ES256 or PS256), the issuer, the audience (your client ID) and the sign-in's nonce. The request carries a PKCE challenge, and the client signs in at the token address with HTTP Basic, unless the provider supports only client_secret_post. Without discovery, the profile comes from the user info address, and the client secret goes in the form.

Edit, do not replace. People who signed in with the provider are linked to it. A new custom provider starts with no links, so after deleting and adding one again, those people are found only by email, which needs the trust above. Change the issuer, keys or label with the edit button instead.

In your app

Nothing changes in your code. People connect and remove the provider on the SDK's Security screen, listed under its button label: see Account security screens.

import { useSaaSAuth } from '@buildbase/sdk/react';

export function SecurityButton() {
  const { openWorkspaceSettings } = useSaaSAuth();
  return (
    <button onClick={() => openWorkspaceSettings('security')}>Security</button>
  );
}

Check it works

• Saving the provider succeeded, so BuildBase could read its discovery document.
• The redirect URL is in the client's allowed redirect URLs at the provider.
• The provider is ticked on your app, and Open the live page shows your button.
• A new person can sign in and lands in your app; they appear under Users.
• Trust its email addresses is what you decided, not left at Never by accident if your provider verifies addresses.

Things to watch out for

• ID tokens must be signed with RS256, ES256 or PS256. A client set to sign with a shared secret (HS256) fails every sign-in with "Sign-in with that provider failed." In Auth0, keep the application's JSON Web Token signature algorithm on RS256.
• The issuer must match the provider's own. Copy the issuer value from the discovery document. In Keycloak it ends with /realms/ and the realm's name. A slash at the end is ignored, anything else is not.
• Trusting addresses can hand over accounts. Always and When it sends email_verified: true let the provider sign into any existing account with the same address. Choose them only for a provider that checks people own the addresses it sends.
• Deleting the provider unlinks everyone. People are linked to this one provider. A new one starts with no links, so edit the existing provider to change its issuer, keys or label.
• Changes at your provider can take an hour to reach BuildBase. BuildBase keeps the discovery document it read for up to an hour.
• Finish at your provider within 10 minutes. A sign-in left open on your provider's page for more than 10 minutes cannot finish: BuildBase sends the browser to your sign-in page, with a note that the sign-in expired. Start again from your app's Sign in button.

If something goes wrong

Next steps

• Social providers - the reference for the custom provider and every built-in one.
• Who can sign up - who a provider may create accounts for.
• Account security screens - connected accounts inside your app.
• Set up sign-in, step by step - every sign-in guide, and the order to set them up in.