> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eigenpal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and access

> Connect SSO and grant access independently in each environment.

EigenPal supports password login and SSO for single-tenant installations. Keep authentication enabled. Use the administrator configured during [installation](https://docs.eigenpal.com/self-hosting/kubernetes.md) to set up access.

## Connect OIDC

Supply these variables to the app, with the client secret in a Kubernetes Secret:

```dotenv theme={null}
SSO_ENABLED=true
SSO_PROTOCOL=oidc
SSO_PROVIDER_ID=company
SSO_PROVIDER_LABEL=Company SSO
SSO_DISCOVERY_URL=https://identity.example.com/.well-known/openid-configuration
SSO_CLIENT_ID=eigenpal
SSO_CLIENT_SECRET=<from-secret-manager>
SSO_ALLOWED_EMAIL_DOMAINS=example.com
EIGENPAL_AUTH_METHODS=password,sso
```

Register `https://<your-host>/api/auth/callback/company` at your identity provider. Keep the provider ID stable.

By default, OIDC admits unmatched users as members. Set an explicit mapping and `deny` fallback to limit admission:

```dotenv theme={null}
SSO_ROLE_MAP={"eigenpal-admins":"admin","finance":"member"}
SSO_GROUPS_CLAIM=groups
SSO_DEFAULT_ROLE=deny
```

Test an allowed user and an unmapped user before switching to SSO-only login.

## Grant resource access

SSO manages identity and directory membership. In Studio, grant groups access to top-level workflow folders or standalone workflows. A person's organization role caps those grants.

Local EigenPal groups also work with SSO. Administrators manage their memberships; directory memberships refresh from the identity provider. Groups with the same name remain distinct.

Set roles and grants separately in each environment, for example editing in development and viewing in production. Promotion preserves local policy. New imported top-level resources start private.

Use [service accounts](https://docs.eigenpal.com/guides/service-accounts.md) and per-environment API keys for integrations.

## Additional settings

> [accordion] Password login and installation identity
>
> `EIGENPAL_AUTH_METHODS` accepts `password` and `sso`, comma-separated. Password is enabled by default. Leave `EIGENPAL_ALLOW_OPEN_SIGNUP=false` for invitation-only signup.
>
> If you pin `tenant.id`, use `tenant_[a-z0-9_]{1,56}` and preserve it after initialization. Keep `BETTER_AUTH_SECRET` stable and at least 32 characters long.

> [accordion] SSO claims and role mapping
>
> `SSO_SCOPES` defaults to `openid,profile,email`. `SSO_GROUP_FILTER` limits mirrored groups. An explicit role map can assign `admin`, `member`, `reviewer` or `viewer`. The fallback allows `member`, `reviewer`, `viewer` or `deny`. SSO cannot assign owner.

> [accordion] User Auth protocol and directory refresh
>
> `SSO_PROTOCOL=user-auth` supports compatible redirect/token-exchange services using `SSO_LOGIN_URL`, `SSO_SERVICE_URL`, `SSO_APP_ID` and an application secret or mTLS credentials. Its default fallback role is `deny`.
>
> Mount certificates before setting `SSO_CLIENT_CERT_FILE`, `SSO_CLIENT_KEY_FILE` or `SSO_CA_BUNDLE_FILE`. User-info and lookup paths resolve against the service URL.
>
> A compatible user-lookup endpoint enables directory refresh. Set maximum staleness at least as high as the refresh interval. Arbitrary OIDC providers do not necessarily support this lookup protocol; see [SSO fields](https://docs.eigenpal.com/self-hosting/environment-variables.md#authentication).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.