Federate your identity provider

What federation gives you

By default an org’s operators authenticate through the daevix identity backend. Federation points an org at your own upstream identity provider instead, so:

• your people sign in with their existing corporate accounts (SSO), and
• the group memberships your IdP already manages flow into daevix as the urn:dvx:groups claim, where you bind them to roles with group-scoped grants.

Membership stays authoritative upstream — daevix never copies your directory. It only translates “which groups does this token claim” into the group principals your grants are keyed on. Add or remove someone from a group in your IdP and the change takes effect on their next token, with nothing to sync on the daevix side.

Before you start

• You need idp:manage in the org (the admin role includes it). Federation is a distinct capability precisely because it introduces a new trust dependency — your org is trusting an external IdP for authorization-relevant group claims.
• Register an OAuth/OIDC client (or a SAML application) with your IdP, pointed at the daevix identity backend’s callback. Note the issuer URL, client id, and client secret (OIDC), or the metadata URL (SAML).
• Decide which upstream attribute carries group membership (for example groups).

Configure it

Federation is configured through the operator API, scoped to your org:

curl -X PUT https://<controlplane>/api/v1/orgs/<org>/idp \
  -H "Authorization: Bearer $DVX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "oidc",
        "name": "Corp SSO",
        "issuer": "https://accounts.example.com",
        "client_id": "daevix-web",
        "client_secret": "<your-client-secret>",
        "groups_attribute": "groups",
        "scopes": ["openid", "profile", "email", "groups"]
      }'

For a SAML IdP, send "type": "saml" with "metadata_url" instead of the OIDC fields.

daevix drives the identity backend to create the org-scoped connection, enable just-in-time account provisioning, and install the mapping that projects your groups_attribute into urn:dvx:groups. The response echoes back only a reference — type, name, group attribute, and status:

{ "org_id": "acme", "type": "oidc", "name": "Corp SSO",
  "groups_attribute": "groups", "status": "configured" }

Read it back any time with GET /api/v1/orgs/<org>/idp, and remove federation with DELETE /api/v1/orgs/<org>/idp.

Your client secret is never stored by daevix

Secret custody is pass-through. The client secret you send flows straight to the identity backend, which custodies it. daevix persists only the reference above — there is no secret column in its database, so there is nothing to leak. The secret never appears in any API response.

Bind groups to roles

Once federation is live, an upstream group arrives as a urn:dvx:groups entry. Grant a role or capability to that group with a group-scoped grant:

curl -X POST https://<controlplane>/api/v1/orgs/<org>/grants \
  -H "Authorization: Bearer $DVX_TOKEN" -H "Content-Type: application/json" \
  -d '{"principal":"group:<org>:<group>","role":"admin"}'

Everyone your IdP places in that group then holds the role in your org, with no per-user administration on the daevix side.

Cross-org isolation

An org’s federation can only ever mint that org’s group principals. Group claims are namespaced by the caller’s own org, so however your IdP names a group, it becomes group:<your-org>:<name> — never another tenant’s. One org’s federation can never grant authority in, or leak groups into, a sibling org.