Connect an Application with SSO

Use this guide when an application speaks OpenID Connect and you want FerrisKey to handle sign-in.

By the end you will have:

• One FerrisKey realm dedicated to the application or organization
• One OpenID Connect client
• A client ID and client secret
• The redirect URI registered in FerrisKey
• The issuer URL and discovery endpoint your application needs

Before you start

Before opening FerrisKey, find these values in the application you want to connect:

Example values

The walkthrough uses these values. Replace them with your own domains and realm name.

Create or select the realm

A realm keeps users, clients, roles, and scopes together. Avoid using master for applications.

Open the realm selector

Click the realm name in the top bar, next to the FerrisKey logo. Pick the realm that will own this application, or Create realm if you need a new one. The selector is searchable, which matters once a deployment holds more than a handful.

Stay in the application realm

After switching, check the realm indicator before creating the client. The client will be created in the realm currently selected in the dashboard.

Create the client

The client is the application entry in FerrisKey. It tells FerrisKey which app is asking users to sign in.

Open Clients

In the sidebar, click Clients, then New client.

The banner at the top of that list is worth reading before you add anything: it names every client that has no redirect URI, because the authorization code flow cannot work without one.

Choose the protocol

Creation starts by asking which protocol the application speaks: OpenID Connect for anything token-based, or SAML 2.0 for applications that speak nothing else.

This choice is final

It decides how the application signs its users in and cannot be changed after creation. An application that later moves from SAML to OIDC needs a new client, not an edited one. See Authentication for what each protocol gives you.

:::

Fill the client details

Use a stable client ID. In this example:

• Client ID: vaultwarden
• Name: Vaultwarden
• Client enabled: Enabled
• Client authentication: Confidential

Client authentication is a choice between Confidential and Public, and it is also final. Pick Confidential for a server-side application that can hold a secret — FerrisKey then generates one. Pick Public for an SPA, a mobile app or a CLI, where a secret would end up in the user’s hands and PKCE carries the protection instead.

Leave both capability switches off for browser SSO: Direct access grants is the deprecated password grant, and the device authorization grant is for browserless clients.

Configure the redirect URI

The redirect URI is where FerrisKey sends the browser after a successful login.

Open the client settings

Open the client you just created and stay on the Settings tab.

Add the redirect URI

Scroll to the Access section and add the exact callback URL from your application. Every entry is saved as you add it — there is no separate save button for this list.

For the example:

https://vault.example.com/identity/connect/oidc-signin

Two neighbours in the same area matter as much as the redirect URI:

• Web origins — the origins this application may call FerrisKey from in a browser. The + button derives them from the redirect URIs you just entered, but only from literal ones: regex patterns are skipped. Removing an origin takes a few minutes to clear browser preflight caches, and up to 30 seconds to propagate to the other API replicas.
• Post-logout redirect URIs, under Logout — where the user lands once the session closes. With no entry, logout ends on the FerrisKey page rather than back in your application.

Copy the client secret

Open Credentials

Open the client’s Credentials tab.

Copy the secret

The secret is masked. Click Reveal to read it, then copy it into the application’s OIDC configuration and treat it like a password.

Revealing a secret is recorded as a security event — client_secret_viewed in SeaWatch — which is intentional: it means an unexplained reveal is visible in the audit trail.

Check the client scopes

Most OIDC applications need openid, profile, and email.

Open Client Scopes

Open the client’s Client Scopes tab.

Confirm required scopes

Each assigned scope carries a default / optional switch. Make sure these three are on default, which means every token gets them without the application asking:

• openid
• profile
• email

If the application needs roles, set roles to default too. A new realm seeds eight scopes, and the remaining ones — address, phone, offline_access — arrive as optional, applied only when a request names them in its scope parameter.

The Evaluate sub-tab next to the assigned list answers the question this step is really about: it shows the claims this client would receive, without you having to run a login first.

Configure the application

Paste these values into the application.

What the discovery endpoint does

The discovery endpoint is where an OpenID Connect application learns how to talk to FerrisKey.

https://sso.example.com/realms/home/.well-known/openid-configuration

When the application opens that URL, FerrisKey returns a JSON document with the realm’s OIDC metadata. That document tells the application:

• Where to redirect users when they click “Sign in”
• Where to exchange the authorization code for tokens
• Which issuer value to expect in tokens
• Where to fetch the public keys used to verify token signatures
• Which scopes and response types are supported

That is why so many applications only ask for an issuer, an authority, or a discovery URL, instead of making you fill in every endpoint by hand.

Test the login

1. Open the application in a private browser window.
2. Click the SSO or OpenID Connect login button.
3. Confirm that the browser redirects to FerrisKey.
4. Sign in with a user from the same realm.
5. Confirm that FerrisKey redirects back to the application.

If the user signs in but the application says the account is not allowed, look at the application’s own signup, domain, group, or role rules. FerrisKey authenticated the user; the application still gets to decide whether that user is welcome.

Troubleshooting

Invalid redirect URI

FerrisKey rejects the login before showing the sign-in page.

Check that the redirect URI in the client settings exactly matches the callback URL sent by the application. Compare the scheme, domain, path, trailing slash, and port.

Discovery endpoint does not load

Open this URL from your browser and from the application container or server:

https://sso.example.com/realms/home/.well-known/openid-configuration

It should return a JSON document. If it does not, check the FerrisKey public URL, reverse proxy, TLS certificate, and realm name.

Issuer mismatch

Some applications validate that the configured authority equals the issuer field returned by the discovery endpoint.

Open the discovery endpoint and copy the issuer value. Use that exact value as the application’s issuer or authority.

Client authentication failed

The application reaches FerrisKey but token exchange fails.

Check:

• The client is enabled
• Client Authentication is enabled for confidential applications
• The application uses the current client secret
• There are no extra spaces around the copied secret

Missing email or profile data

The login succeeds but the application cannot create or match the account.

Check that openid, profile, and email are assigned as default client scopes. Also check that the FerrisKey user has an email address.

The application asks for password grant

Prefer authorization code flow when the application supports it. Only enable Direct Access Grants if the application explicitly requires grant_type=password and you trust it to handle user passwords directly.