ObjectOS
설정
이 페이지는 아직 번역되지 않았습니다. 영어 원문을 표시합니다.

Authentication

Configure sign-in, sessions, OAuth, OIDC/SSO, SSO providers registered in Setup (OIDC and SAML 2.0), and device flow.

사용 가능 에디션

ObjectOS uses the ObjectStack authentication plugin, powered by Better Auth. Authentication is project-local: each project has its own identity tables and session scope.

What is supported

Depending on the packaged application and enabled settings, ObjectOS can support:

  • email/password sign-in;
  • session management;
  • password reset and email verification;
  • social OAuth providers such as Google, GitHub, Microsoft, and Apple;
  • enterprise single sign-on through your identity provider (Okta, Entra ID, Keycloak, Ping, …), over OIDC or SAML 2.0, registered by an administrator in Setup → SSO Providers;
  • two-factor authentication;
  • passkeys/WebAuthn;
  • magic links;
  • phone number sign-in with SMS OTP (opt-in);
  • CLI/browser device flow.

Who may sign up (ObjectStack 17.3+)

Self-registration is closed by default. Who may create their own account is one setting, Setup → Authentication → Audience:

AudienceWho may sign up
invite_only (default)Only an address holding a pending invitation
email_domainAddresses on the domains you allow — exact match, case-insensitive; subdomains need their own entry
openAnyone

The audience judges every self-serve path: email/password sign-up, a first sign-in through a social provider, magic link, OTP and phone. A refused sign-up answers 403 SELF_REGISTRATION_CLOSED (or 403 EMAIL_DOMAIN_NOT_ALLOWED under email_domain). Two rules come with opening it:

  • email_domain and open both need a self-registration permission set — the set each self-registrant receives (member_default is fine; admin_full_access is refused).
  • Both turn email verification on: email_domain always, open unless the deployment's own configuration turns it off.

The Allow self-service registration toggle under Email and password does not override the audience: with the audience at invite_only, sign-up stays closed even while that toggle is on.

Creating people yourself is never gated by the audience — invitations, Create User, bulk import and enterprise SSO work under every setting (see Users). The very first account on a fresh install is exempt too.

Upgrading from 17.2 or earlier: an undeclared audience used to mean open email/password sign-up. It now means invite_only, and nothing fails at upgrade — a deployment that relied on open sign-up simply stops accepting it. Choose open (with a self-registration permission set) to keep it.

The audience is a different decision from the membership policy (Setup → Authentication → Membership, or OS_AUTH_MEMBERSHIP_POLICY — see Environment Variables). The audience decides whether someone may become a user at all; the membership policy decides which organization a new user joins.

Phone sign-in & SMS (ObjectStack 14.3+)

Enable phone-number authentication via the auth.plugins.phoneNumber setting. Once on:

  • POST /sign-in/phone-number accepts phone + password;
  • SMS OTP covers sign-in verification and self-service password reset, with per-number cooldowns, rolling-hour caps, and per-IP rate limits;
  • sys_user gains unique phone_number and phone_number_verified columns; phone-only accounts get a placeholder email.

SMS delivery is provided by @objectstack/plugin-sms with Aliyun SMS, Twilio, or a dev log fallback, configured through the sms settings namespace. Message bodies containing OTP codes are never persisted or logged. Notifications can also target the sms channel via notify(channels: ['sms']).

Admin user management (ObjectStack 14.3+)

Platform admins can provision accounts without the email invite flow:

  • POST /api/v1/auth/admin/create-user creates a user directly, with an optional one-time password (returned once, never persisted). The must_change_password flag forces rotation at first sign-in (403 PASSWORD_EXPIRED until changed).
  • POST /api/v1/auth/admin/import-users bulk-imports rows / CSV / XLSX (max 500 rows per request) with dry-run and upsert-by-email-or-phone modes; existing users never get their passwords reset. Since 16.0 the default passwordPolicy is 'auto': rows with a deliverable channel (real email + wired email service, or phone + SMS invite path) are invited, and only unreachable rows get a temporary password (returned once, must_change_password). Callers that relied on the old identity-only default must now pass passwordPolicy: 'none' explicitly; per-row outcomes are on rows[].delivery with a summary.delivery breakdown.

Required secret

Set:

OS_AUTH_SECRET=replace-with-a-strong-random-secret

ObjectOS derives a stable per-project secret from this value and the project environment id. This means:

  • sessions survive container restarts;
  • tokens from one project cannot be reused on another project;
  • rotating OS_AUTH_SECRET invalidates sessions.

See Environment variables for the full list of auth-related settings, including the legacy AUTH_SECRET alias.

Session isolation

In multi-project deployments, cookies are scoped to the project hostname. ObjectOS intentionally avoids broad root-domain cookies for project sessions. This prevents a session from leaking across customer projects.

Social login

Configure provider credentials through environment variables or system settings, depending on how the application package exposes auth configuration.

Provider callback URLs depend on the provider type. ObjectStack exposes two distinct callback paths and they are not interchangeable:

Provider typeCallback path
Built-in social (Google, GitHub, Microsoft, Apple, …)/api/v1/auth/callback/<provider>
Generic OIDC / OAuth2 configured in code (Okta, Entra ID, Keycloak, Ping, …)/api/v1/auth/oauth2/callback/<provider>

An SSO provider registered in Setup → SSO Providers uses a third set of paths, listed in that section.

Examples:

https://crm.example.com/api/v1/auth/callback/google
https://crm.example.com/api/v1/auth/callback/microsoft
https://crm.example.com/api/v1/auth/oauth2/callback/okta
https://crm.example.com/api/v1/auth/oauth2/callback/entra

Configure the matching redirect URI in the identity provider's application registration before enabling the provider in ObjectOS.

Enterprise OIDC/SSO in configuration

This section is about OIDC providers that the application package or the deployment's configuration declares (the generic OAuth2 route, genericOAuth). They are registered as generic OAuth2 providers and use the /api/v1/auth/oauth2/callback/<provider> path. To let an administrator add an identity provider from the console instead, without a configuration change, use Setup → SSO Providers. A typical configuration requires:

FieldDescription
Provider idStable id such as okta or entra (used in the callback URL)
Display nameButton label shown to users
Discovery URL.well-known/openid-configuration endpoint
Client idApplication client id from the identity provider
Client secretSecret stored in environment or encrypted settings
ScopesUsually openid email profile

For customer deployments, prefer OIDC discovery URLs over manually configured authorization/token/userinfo endpoints.

Setup → SSO Providers

Setup → Access Control → SSO Providers is where a platform administrator connects the organization's own identity provider, over OIDC or SAML 2.0, without touching configuration. It is a different route from the configuration-time providers above: its providers live in the database, are added and changed in the console, and use their own callback paths. Use one route per identity provider, not both.

Configuration (genericOAuth, above)Setup → SSO Providers
Who adds a providerWhoever edits the package or deployment configurationA platform administrator, in the console
ProtocolsOIDC / OAuth2OIDC and SAML 2.0
OIDC callback/api/v1/auth/oauth2/callback/<provider>/api/v1/auth/sso/callback/<provider id>
SAML ACS URL—/api/v1/auth/sso/saml2/sp/acs/<provider id>
SAML SP entity ID—/api/v1/auth/sso/saml2/sp/metadata?providerId=<provider id>
How people reach the providerAs the application configures itSign in with SSO: people type their work email and are routed by its domain
Domain verification, just-in-time accounts, group → permission-set mapping—Per provider

The page appears once SSO is on: OS_SSO_ENABLED=true on a self-hosted deployment; on ObjectOS Cloud, a plan that includes single sign-on with your identity provider. From the list, a platform administrator:

  • registers a provider — Register SSO Provider (OIDC) or Register SAML Provider — naming its Provider ID (the last segment of the URLs above) and the email domain whose people it signs in;
  • proves the domain with Request Domain Verification and Verify Domain (a DNS TXT record). ObjectOS Enterprise and ObjectOS Cloud require this before the provider signs anyone in; on Enterprise OS_SSO_DOMAIN_VERIFICATION=false turns it off;
  • sets Edit Sign-In Options: Allow Just-in-Time Provisioning (create the account at a first sign-in, instead of requiring an invitation), Allow IdP-Initiated Sign-In, and for OIDC Read Claims From the ID Token Only;
  • adjusts the provider later with Edit OIDC Settings, Edit SAML Settings (for example a new signing certificate), Edit Attribute Mapping and Edit Groups Claim;
  • maps the identity provider's groups to permission sets in Setup → IdP Group Mappings → Map SSO Group.

Step-by-step guides, with the exact values to paste on each side:

Platform SSO

In cloud-connected deployments, ObjectOS can use the control-plane login as a platform SSO provider. A builder who is already signed in to the control plane can be provisioned into a project runtime without creating a separate project-local account.

This requires the control plane and ObjectOS to share the same OS_AUTH_SECRET base secret. Disable platform SSO only when the customer wants every project to own a completely separate login boundary.

Operational checks

Before production:

  • confirm expired tokens return 401;
  • confirm the sign-up audience matches who should be able to create an account;
  • confirm logout revokes the active session;
  • confirm password reset revokes other sessions if required by policy;
  • confirm callback URLs match the public project domain;
  • confirm trusted origins include only approved domains;
  • confirm OS_AUTH_SECRET is stored in a secret manager, not in source.

Next steps

Authentication establishes who a user is. To control what they can access once signed in, see Permissions. For non-browser clients and machine-to-machine access, see API access.

이 페이지의 내용