EN

中文

EN

中文

Appearance

Go to Dashboard
中文

🧪 Beta — Available today; the interface contract may still change.

Integrate with your existing authentication ​

You do not need to replace your existing identity system.

That is the one question this page answers. The biggest concern in an enterprise identity purchase is never "does it have this feature" — it is "our last IAM rollout took two years, please do not ask us to start over". GenAuth's position is a layer on top of your existing Human IAM: users stay in your directory, sign-in stays in your flow, and the only thing that changes is where an agent gets its authority from.

By the end of this guide you will be able to:

  • Decide which path fits your situation
  • Know what you configure and what we handle for each path
  • Understand the security boundary and cost of each

Two paths — pick one first ​

Path A: OIDC federationPath B: server-side trust
In one lineThe user authenticates and consents on the sign-in page they already knowThe user is already signed in to your app, and your server starts the delegation in the organization's name
User experienceOne redirect (to your IdP sign-in → consent page)No redirect; nothing extra for the user to do
Who consentsThe end user, personallyThe organization (an administrator consented in advance)
You needAn OIDC-capable identity providerA trustworthy server-side sign-in system
FitsPersonal data and actions where the user must be informedBackground jobs, batch processing, first-party apps with a mature sign-in system
Main costAn interactive round trip; the user must be presentThe key is the authority; hardening requirements are high

When you cannot decide: would it be inappropriate for the user to learn about this authorization only afterwards? If yes, take path A. If not (nightly reconciliation, for example), take path B.

Path A: OIDC federation ​

What it solves ​

Authority over user identity stays with your IdP. GenAuth no longer keeps its own copy of users — at consent time it sends the user back to your sign-in page, so the user sees the interface they already know, and returns to the consent page to decide once authenticated.

Two things get wired at once:

  • Identity federation: who the user is (sub points at that person in your directory)
  • Permission read: what the user can do (this sets the upper bound of the delegation — the "the person's real permissions" term in the three-way intersection)

What you configure ​

  1. Register an OIDC client for GenAuth in your IdP (authorization code flow) and configure the callback address
  2. Decide the scope and claim mapping: GenAuth needs a stable unique user identifier
  3. Configure the provider connection on the GenAuth side (currently supported and planned providers: Integration principles)
  4. Verify: run one complete interactive delegation (see Quickstart) and confirm the user on the consent page is the one in your directory

Boundaries ​

  • Your IdP is the identity authority; GenAuth neither copies nor takes over your user directory
  • Once a user is disabled or offboarded in your IdP, subsequent consent naturally fails
  • The exact shape of permission read depends on provider capability (see Integration principles)

Path B: server-side trust ​

What it solves ​

Your application already knows who is using it — the user just signed in to your system. Sending them off to another consent page is redundant for the experience, and product stakeholders may simply veto it.

On this path, an administrator consents in advance in the organization's name: "agents of this class in this organization may execute these scopes for this organization's users". After that your server, holding the access key, starts delegations directly with no per-use confirmation from the user.

typescript
// Your server has already established the signed-in user; start the delegation directly
const { data: grant } = await anima.delegateToken({
  agent: "report-agent",
  scopes: [AnimaScopes.WEB_SEARCH_RUN],   // minimum set
  user: { id: currentUser.id },          // from your own session
  expiresIn: 900,                        // 15 minutes, sized to the task
});

What you must do (not optional) ​

This path is equivalent to authorizing in the organization's name

Whoever holds the access key can start delegations for users in the organization. A leaked access key is an organization-level risk. Before adopting it, put these in place:

  • The key exists only in a controlled server-side environment (a secret manager or environment variables) — never in a client, a log, or a front-end build artifact
  • The key's allowedScopes / allowedAgents are set to the minimum — this is the first gate on delegation
  • Lifetimes are sized to the task (minutes), not set to the maximum
  • A dedicated key per agent, so an incident means disabling one key
  • Alerting on key usage: unexpected hours, unexpected origins, abnormal frequency

Full hard-constraint checklist and threat analysis: Security considerations.

Boundaries ​

  • The user receives no per-use confirmation, so you have an obligation to tell them in-product which agents are acting on their behalf — we recommend a "my authorizations" page (see Audit and compliance reporting)
  • The authorization is still revocable and auditable; the artifact is the same delegate token as in path A
  • Not suitable for consumer-facing informed-consent scenarios

The two paths can coexist ​

A common mature combination: internal tools take path B (employees are already signed in, experience wins), customer-facing features take path A (the customer must be informed personally). Both share one agent inventory, one audit chain and one set of recall mechanisms — switching paths requires no change on the agent side, only different parameters when starting the delegation.

FAQ ​

Our sign-in system is homegrown, not standard OIDC. Can we integrate? Two options: add a standard OIDC layer to it (better long-term), or start with path B (an existing server-side session is all you need).

Can we avoid both replacing our IdP and getting administrator consent? No. Authorization must have someone accountable — either the user personally or the organization. This is not a product limitation; it is what delegation semantics require (see Consent and approval).

Can multiple Human Identity providers be connected at once? The architecture is designed around a provider abstraction; see Integration principles for current support.

Next steps ​