SSO with Okta

1. Create an OIDC application in Okta

1. Sign in to your Okta admin portal at https://your-org-admin.okta.com.
2. In the sidebar, go to Applications → Applications, then click Create App Integration.
3. Sign-in method: OIDC - OpenID Connect. Click Next.
4. Application type: Web Application. Click Next.

2. Configure the application

• App integration name: RepoWarden (or whatever you prefer).
• Grant type: ✅ Authorization Code. Leave others unchecked.
• Sign-in redirect URI: grab this from Team settings → SSO after you click Add SSO connection. It looks like:

  https://api.repowarden.dev/api/auth/sso/callback/sso-<team-slug>-<random>

  Tip: save and come back to fill the redirect URI after RepoWarden generates the unique provider ID. Or just put a placeholder, save in RepoWarden, then update Okta with the exact URI shown on the connection card.
• Sign-out redirect URI: https://repowarden.dev.
• Assignments: "Allow everyone in your organization to access" is fine for getting started.

Click Save.

3. Set the authentication policy

Okta dev orgs default to "Any two factors" which can block users without enrolled MFA. For initial setup, switch to Password only:

1. On the application's Sign On tab, find User authentication and click Edit.
2. Choose an authentication policy that allows password-only access (or create one if none exists — see Okta's docs on authentication policies).
3. Save.

Production deployments should use a stricter policy with MFA. RepoWarden trusts whatever your IdP enforces.

4. Copy the values you'll need

From the application's General tab:

• Client ID — visible at the top.
• Client secret — click to reveal.

Get the Issuer URL from Security → API → Authorization Servers. The default server's Issuer URI looks like:

https://your-org.okta.com/oauth2/default

5. Register the connection in RepoWarden

1. Go to Team settings → SSO.
2. Click Add SSO connection.
3. Fill in:
   • Identity provider: Okta
   • Display name: e.g. "Acme Okta"
   • Issuer URL: the issuer you copied (without a trailing slash)
   • Email domain: your corporate email domain, e.g. acme.com
   • Client ID + Client secret: from Okta
4. Click Test discovery — should show ✓ if the issuer is reachable.
5. Click Save connection.

6. Update the Okta redirect URI

RepoWarden generates a unique providerId when you save. Copy the Provider ID shown on the connection card and replace the placeholder in your Okta app's Sign-in redirect URI with the real one:

https://api.repowarden.dev/api/auth/sso/callback/<providerId>

7. Test the sign-in

1. Open an incognito window.
2. Go to repowarden.dev and click Sign in.
3. Enter the email of an Okta user whose domain matches the one you registered.
4. You should be redirected to Okta, sign in there, and land on the RepoWarden dashboard.

Troubleshooting

"You are not allowed to access this app"

Okta's authentication policy is blocking. Either:

• Edit the policy attached to the app to allow your user, or
• Disable Federation Broker Mode on the app (General tab → uncheck FBM → Save) and explicitly assign the user under the Assignments tab.

"Invalid OIDC configuration. Authorization URL not found"

The issuer URL is wrong or unreachable. Double-check it ends with /oauth2/default (or whatever authorization server you're using) — not just the bare org URL.

Email domain mismatch

The email shown by Okta in the ID token must match the registered domain. If your Okta users have @example.com emails but you registered acme.com, change one to match.

Stuck? Email [email protected] with the time of the failure and we'll trace the request.