Frona supports Single Sign-On through OpenID Connect (OIDC). This lets users log in with their existing identity provider, such as Google, Okta, Auth0, Keycloak, or any OIDC-compatible provider.

How SSO works

1. The user clicks "Sign in with SSO" on the login page
2. They're redirected to your identity provider (Google, Okta, etc.)
3. After authenticating, the IdP redirects back to Frona
4. Frona validates the token and creates a session

Configuration

Set these in your environment or config file:

FRONA_SSO_ISSUER_URL: "https://accounts.google.com"
FRONA_SSO_CLIENT_ID: "your-client-id"
FRONA_SSO_CLIENT_SECRET: "your-client-secret"
FRONA_SSO_SCOPES: "openid,email,profile"

Setting	Description
FRONA_SSO_ISSUER_URL	The OIDC issuer URL from your identity provider
FRONA_SSO_CLIENT_ID	Your OAuth client ID
FRONA_SSO_CLIENT_SECRET	Your OAuth client secret
FRONA_SSO_SCOPES	Comma-separated OIDC scopes (default: openid,email,profile)

Setting up with Google

1. Go to the Google Cloud Console
2. Create a new project (or select an existing one)
3. Navigate to APIs & Services → Credentials
4. Click Create Credentials → OAuth 2.0 Client ID
5. Select Web application as the application type
6. Add your callback URL under "Authorized redirect URIs":

   https://your-domain.com/api/auth/sso/callback

7. Copy the Client ID and Client Secret
8. Set your environment variables:

   FRONA_SSO_ISSUER_URL: "https://accounts.google.com"
   FRONA_SSO_CLIENT_ID: "your-client-id.apps.googleusercontent.com"
   FRONA_SSO_CLIENT_SECRET: "your-client-secret"

Setting up with Keycloak

1. In your Keycloak admin console, create a new client in your realm
2. Set the client protocol to openid-connect
3. Set the redirect URI to:

   https://your-domain.com/api/auth/sso/callback

4. Set your environment variables:

   FRONA_SSO_ISSUER_URL: "https://keycloak.example.com/realms/your-realm"
   FRONA_SSO_CLIENT_ID: "your-client-id"
   FRONA_SSO_CLIENT_SECRET: "your-client-secret"

Setting up with other providers

Any OIDC-compatible provider works. The general steps are:

1. Create an OAuth/OIDC application in your provider's admin console
2. Set the redirect URI to https://your-domain.com/api/auth/sso/callback
3. Find the OIDC issuer URL (usually documented in the provider's setup guide)
4. Set the environment variables with your client ID, secret, and issuer URL

Common providers: Okta, Auth0, Azure AD, OneLogin, Authentik.

Account matching

When a user logs in via SSO for the first time:

• FRONA_SSO_SIGNUPS_MATCH_EMAIL=true (default). If an existing account has the same email, the SSO login is linked to that account.
• FRONA_SSO_SIGNUPS_MATCH_EMAIL=false. A new account is always created.

Email matching is case-insensitive and ignores surrounding whitespace, so an IdP that returns Alice@Example.COM still links to an account stored as alice@example.com. (This applies to local accounts too — emails are normalized everywhere.)

If the ID token doesn't carry an email, or its email doesn't match any account, Frona falls back to the provider's UserInfo endpoint and retries the match. This makes SSO work with identity providers that emit bare-sub ID tokens and only expose email and name from UserInfo. If you rely on this, make sure your FRONA_SSO_SCOPES includes profile so the name comes through. A failed UserInfo fetch is non-fatal — login proceeds on the ID token alone.

Display names

Frona fills the new account's display name from the first claim that's present, in order: name, then given_name + family_name, then preferred_username, then the part of the email before the @. Only if none of those exist does it fall back to a generic "SSO User".

Email verification

By default, Frona only accepts verified email addresses from the IdP. If your provider doesn't always include verification status, you can relax this:

FRONA_SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION: true

WARNING

Use this with caution. It trusts email addresses that haven't been verified by the identity provider.

Troubleshooting

• "Redirect URI mismatch". The callback URL in your provider doesn't match https://your-domain.com/api/auth/sso/callback. Check for trailing slashes and http vs. https.
• "Email not verified". The IdP didn't mark the email as verified. Either verify the email in the IdP, or set FRONA_SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION=true.
• SSO button doesn't appear. Make sure all four SSO environment variables are set. The login page only shows the SSO option when configuration is complete.
• Account already exists. If FRONA_SSO_SIGNUPS_MATCH_EMAIL=true, the SSO login links to the existing account. If you want separate accounts, set it to false.

Next steps

• Setting Up Authentication. Local auth and token configuration.
• Managing Secrets & API Keys. How agents access your credentials.