FerriskeyAbyss: Identity Provider Federation
Abyss connects FerrisKey to external identity providers. Users can authenticate through Google, GitHub, Discord, or any custom OAuth2/OIDC provider, and FerrisKey handles the token exchange, user provisioning, account linking, and attribute mapping.
Why federation?
Federation meets users where they already have an identity. Rather than making them create yet another account, let them sign in with the Google or corporate credentials they already carry. FerrisKey sits in the middle as the broker, normalizing each provider’s format into one internal model.
Supported provider types
| Type | Status | Examples |
|---|---|---|
| OAuth2 | Supported | Google, GitHub, Discord, any OAuth2 provider |
| OIDC | Supported | Any OpenID Connect compliant provider |
| SAML | Planned | Enterprise IdPs such as Okta or Entra ID |
| LDAP | Planned | Active Directory, OpenLDAP |
SAML in the other direction already works
Signing in through an external SAML provider is what is planned here. FerrisKey acting as a SAML identity provider, so other applications can trust it, is shipped: see the SAML module.
Provider configuration
Providers are registered per realm, each with its full OAuth2 or OIDC configuration:
| Field | Description |
|---|---|
name | Display name shown on the login page |
provider_type | oauth2 or oidc |
client_id | OAuth2 client ID from the external provider |
client_secret | OAuth2 client secret (encrypted in storage) |
authorization_url | Provider’s authorization endpoint |
token_url | Provider’s token endpoint |
userinfo_url | Provider’s UserInfo endpoint (optional) |
scopes | OAuth2 scopes to request (e.g., openid, email, profile) |
enabled | Toggle the provider on/off without deleting it |
configuration | Provider-specific JSON config (e.g., tenant ID for Azure AD) |
Secret encryption
Client secrets are encrypted before storage. They are never exposed through the admin API in plaintext.
Provider mappings
Mappings say how the provider’s attributes land on FerrisKey user fields:
| External Field | Internal Field | Required |
|---|---|---|
email | email | Yes |
sub | . (used for linking) | Yes |
preferred_username | username | No |
given_name | firstname | No |
family_name | lastname | No |
A mapping can be marked required. When a required one is absent from the provider’s response, the federation flow fails rather than creating a half-filled user.
Common setups
Sign in with Google for a SaaS product
Configure a Google OAuth2 provider with scopes openid email profile. Users click “Sign in with Google”, authenticate at Google, and are redirected back to your app with FerrisKey tokens. New users are automatically provisioned.
Corporate SSO with Entra ID
Configure an OIDC provider pointing at your tenant’s endpoints. Employees authenticate with their corporate identity and receive FerrisKey tokens scoped to the right realm.
Several providers at once
Configure Google, GitHub, and Discord as providers on the same realm. Users choose their preferred provider on the login page. All three paths converge into the same FerrisKey user model with unified roles and permissions.
Account linking
A user who first signed in with Google can link a GitHub account later. Both external identities point at the same FerrisKey user, each tracked by its own federated credential.