Skip to content

Commit e8a6289

Browse files
hotlonghotlong
committed
Update files
1 parent ac86b93 commit e8a6289

33 files changed

Lines changed: 1614 additions & 382 deletions

‎content/docs/architecture/index.mdx‎

Lines changed: 0 additions & 62 deletions
This file was deleted.

‎content/docs/configure/authentication.mdx‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
title: Authentication
3+
description: Configure sign-in, sessions, OAuth, OIDC/SSO, and device flow.
4+
---
5+
6+
# Authentication
7+
8+
ObjectOS uses the ObjectStack authentication plugin, powered by
9+
Better Auth. Authentication is project-local: each project has its own
10+
identity tables and session scope.
11+
12+
## What is supported
13+
14+
Depending on the packaged application and enabled settings, ObjectOS can
15+
support:
16+
17+
- email/password sign-in;
18+
- session management;
19+
- password reset and email verification;
20+
- social OAuth providers such as Google, GitHub, Microsoft, and Apple;
21+
- enterprise OIDC/SSO such as Okta, Entra ID, Keycloak, and Ping;
22+
- two-factor authentication;
23+
- passkeys/WebAuthn;
24+
- magic links;
25+
- CLI/browser device flow.
26+
27+
## Required secret
28+
29+
Set:
30+
31+
```bash
32+
OS_AUTH_SECRET=replace-with-a-strong-random-secret
33+
```
34+
35+
ObjectOS derives a stable per-project secret from this value and the
36+
project environment id. This means:
37+
38+
- sessions survive container restarts;
39+
- tokens from one project cannot be reused on another project;
40+
- rotating `OS_AUTH_SECRET` invalidates sessions.
41+
42+
## Session isolation
43+
44+
In multi-project deployments, cookies are scoped to the project hostname.
45+
ObjectOS intentionally avoids broad root-domain cookies for project
46+
sessions. This prevents a session from leaking across customer projects.
47+
48+
## Social login
49+
50+
Configure provider credentials through environment variables or system
51+
settings, depending on how the application package exposes auth
52+
configuration.
53+
54+
Provider callback URLs use the ObjectOS auth route:
55+
56+
```text
57+
https://<project-domain>/api/v1/auth/callback/<provider>
58+
```
59+
60+
Examples:
61+
62+
```text
63+
https://crm.example.com/api/v1/auth/callback/google
64+
https://crm.example.com/api/v1/auth/callback/microsoft
65+
```
66+
67+
## Enterprise OIDC/SSO
68+
69+
OIDC providers typically require:
70+
71+
| Field | Description |
72+
|---|---|
73+
| Provider id | Stable id such as `okta` or `azure-ad` |
74+
| Display name | Button label shown to users |
75+
| Discovery URL | `.well-known/openid-configuration` endpoint |
76+
| Client id | Application client id from the identity provider |
77+
| Client secret | Secret stored in environment or encrypted settings |
78+
| Scopes | Usually `openid email profile` |
79+
80+
For customer deployments, prefer OIDC discovery URLs over manually
81+
configured authorization/token/userinfo endpoints.
82+
83+
## Platform SSO
84+
85+
In cloud-connected deployments, ObjectOS can use the control-plane login
86+
as a platform SSO provider. A builder who is already signed in to the
87+
control plane can be provisioned into a project runtime without creating
88+
a separate project-local account.
89+
90+
This requires the control plane and ObjectOS to share the same
91+
`OS_AUTH_SECRET` base secret. Disable platform SSO only when the customer
92+
wants every project to own a completely separate login boundary.
93+
94+
## Operational checks
95+
96+
Before production:
97+
98+
- confirm expired tokens return `401`;
99+
- confirm logout revokes the active session;
100+
- confirm password reset revokes other sessions if required by policy;
101+
- confirm callback URLs match the public project domain;
102+
- confirm trusted origins include only approved domains;
103+
- confirm `OS_AUTH_SECRET` is stored in a secret manager, not in source.

‎content/docs/configure/index.mdx‎

Lines changed: 0 additions & 68 deletions
This file was deleted.

‎content/docs/configure/meta.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"title": "Configure",
3+
"pages": ["runtime", "authentication", "permissions", "system-settings"]
4+
}

‎content/docs/configure/permissions/field-security.mdx‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: Field Security
3+
description: Control field visibility and editability.
4+
---
5+
6+
# Field Security
7+
8+
Field security controls what a user can read or edit after the user has
9+
access to the object and record.
10+
11+
## What field security answers
12+
13+
```text
14+
Can this user see or update this specific field?
15+
```
16+
17+
Examples:
18+
19+
- sales reps can see account name but not annual revenue;
20+
- support agents can update case status but not SLA violation fields;
21+
- finance users can read invoice totals;
22+
- administrators can edit integration credentials.
23+
24+
## Read vs update
25+
26+
Treat read and update separately:
27+
28+
| Grant | Meaning |
29+
|---|---|
30+
| Read | Field appears in API responses and UI |
31+
| Update | Field can be changed by the user |
32+
33+
A field can be readable but not editable.
34+
35+
## Sensitive fields
36+
37+
Use field security for:
38+
39+
- financial values;
40+
- personal data;
41+
- integration credentials;
42+
- internal scoring fields;
43+
- approval or compliance flags.
44+
45+
For secrets, prefer encrypted system settings or external secret
46+
management. Field security is not a substitute for encryption.
47+
48+
## Troubleshooting fields
49+
50+
When a user can open a record but cannot see or edit a field, check:
51+
52+
1. Object permission.
53+
2. Record access.
54+
3. Field-level read/update permission.
55+
4. UI view layout rules.
56+
5. Validation rules or computed/formula fields that may block updates.

‎content/docs/configure/permissions/identity.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: Identity
3+
description: Users, organizations, members, departments, teams, and invitations.
4+
---
5+
6+
# Identity
7+
8+
Identity defines who can enter the system and where they belong.
9+
10+
## Core objects
11+
12+
| Object | Purpose |
13+
|---|---|
14+
| `sys_user` | User account |
15+
| `sys_session` | Active session |
16+
| `sys_account` | Linked OAuth/OIDC account |
17+
| `sys_organization` | Tenant or workspace |
18+
| `sys_member` | User membership in an organization |
19+
| `sys_department` | Organization structure |
20+
| `sys_team` | Collaboration group |
21+
| `sys_invitation` | Pending invitation |
22+
| `sys_api_key` | Programmatic access identity |
23+
24+
## Provisioning patterns
25+
26+
Common customer patterns:
27+
28+
| Pattern | Use when |
29+
|---|---|
30+
| Self-service signup | Small teams or demo environments |
31+
| Admin invitation | Controlled customer onboarding |
32+
| OIDC/SSO JIT provisioning | Enterprise identity provider owns user lifecycle |
33+
| API key provisioning | Server-to-server integration |
34+
35+
ObjectOS can auto-provision a personal organization for a new user when
36+
the security plugin is active. In cloud-connected mode, owner and
37+
organization seed data can be replayed into the project database so the
38+
project owner lands in the right workspace on first login.
39+
40+
## Organizations vs projects
41+
42+
Do not confuse these:
43+
44+
| Term | Meaning |
45+
|---|---|
46+
| Project/environment | Runtime deployment unit resolved by ObjectOS |
47+
| Organization | Business tenant/workspace inside that project |
48+
49+
A single ObjectOS host can serve multiple projects. Each project can
50+
contain its own organizations, users, and permissions.
51+
52+
## Operational guidance
53+
54+
- Use SSO for enterprise customers.
55+
- Use invitations for controlled onboarding.
56+
- Keep API keys separate from human users.
57+
- Review active sessions during security incidents.
58+
- Disable or remove memberships instead of deleting audit-relevant users.

0 commit comments

Comments
 (0)