Okta OIDC sign-in

Connect Okta as an OIDC identity provider for your private BSR instance. Once configured, users sign in to the BSR through Okta and the BSR provisions accounts Just-in-Time using the email address Okta provides.

This walkthrough is for an Okta administrator working alongside a BSR administrator with the Admin or Owner role on the BSR organization that owns the instance.

Before you start

• Complete Pro and Enterprise setup, including DNS, so the instance is reachable.
• Know your private BSR instance’s domain name (for example, your-bsr-instance.example.com); the examples below use this placeholder.
• Have the right BSR role: Admin or Owner on the organization that owns the instance.
• Have administrative access to your Okta organization.

Create the Okta application

1. Sign in to your Okta organization.
2. Navigate to Applications > Applications and click Create App Integration.
3. For Sign-in method, select OIDC - OpenID Connect.
4. For Application type, select Web Application.

Configure OIDC

1. Under General Settings, give the integration an App name like “Buf Schema Registry” or “Buf”. Pick a name your users will recognize.

2. Under Grant type, enable Refresh Token in addition to the default authorization code grant.

   

3. Set the redirect URIs:

   • Sign-in redirect URI: https://your-bsr-instance.example.com/oauth2/callback
   • Sign-out redirect URI: https://your-bsr-instance.example.com/logout

   For Application Single Logout, contact Support or your Buf representative.

   

   The BSR provisions users Just-in-Time from the email address Okta provides, so make sure the user profile mappings produce the email you want the BSR account to be matched on.

4. In the Assignments section, select which users or groups should have access to the BSR.

Configure refresh token rotation

The BSR depends on rotating Okta refresh tokens to keep sessions alive across reloads. Configure Okta to rotate tokens with a non-zero grace period; without one, concurrent refreshes from different tabs can invalidate each other and force users to re-authenticate.

1. On your OIDC integration, click Edit in the General Settings card.
2. Scroll down to the Refresh Token section.
3. Select Rotate token after every use and set Grace period for token rotation to 15s. Don’t leave the grace period at 0.

4. Click Save.

   

Update SSO on the BSR instance

The current UI labels this surface SSO Configuration; the URL still uses pro-settings.

1. Open the SSO configuration page at https://buf.build/your-organization/pro-settings, where your-organization is the BSR organization that owns the instance. The page is hosted on buf.build, not on your private BSR hostname.

2. In another browser tab, open the General Settings page on your Okta OIDC integration to copy the Client ID, Client secret, and the Okta domain (your issuer URL).

   

3. Back on the BSR’s SSO configuration page, choose OIDC from the SSO Provider dropdown.

4. Paste the Client ID, Client secret, and Issuer URL. The logout URL is optional.

5. Click Update.

   

Verify sign-in

In an incognito window, open https://your-bsr-instance.example.com and follow the sign-in flow. The browser should redirect to Okta and, after authentication, land back on the BSR signed in as the OIDC identity. Confirm that the existing BSR account is linked (account history and permissions are intact) rather than a new account being provisioned.

Next steps

• User lifecycle: how the BSR provisions, promotes, and deactivates users.