로그인, 세션, OAuth, OIDC/SSO 및 디바이스 플로우를 구성합니다.

인증

ObjectOS는 Better Auth로 구동되는 ObjectStack 인증 플러그인을 사용합니다. 인증은 프로젝트 로컬 방식입니다. 각 프로젝트는 자체 ID 테이블과 세션 범위를 가집니다.

지원 기능

패키징된 애플리케이션과 활성화된 설정에 따라 ObjectOS는 다음을 지원할 수 있습니다.

이메일/비밀번호 로그인;
세션 관리;
비밀번호 재설정 및 이메일 인증;
Google, GitHub, Microsoft, Apple과 같은 소셜 OAuth 제공자;
Okta, Entra ID, Keycloak, Ping과 같은 엔터프라이즈 OIDC/SSO;
2단계 인증;
패스키/WebAuthn;
매직 링크;
CLI/브라우저 디바이스 플로우.

필수 시크릿

다음을 설정하세요.

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

ObjectOS는 이 값과 프로젝트 환경 id로부터 안정적인 프로젝트별 시크릿을 파생합니다. 이는 다음을 의미합니다.

세션이 컨테이너 재시작 후에도 유지됩니다;
한 프로젝트의 토큰을 다른 프로젝트에서 재사용할 수 없습니다;
OS_AUTH_SECRET을 교체하면 세션이 무효화됩니다.

레거시 AUTH_SECRET 별칭을 포함한 인증 관련 설정의 전체 목록은 Environment variables를 참조하세요.

세션 격리

다중 프로젝트 배포에서 쿠키는 프로젝트 호스트명으로 범위가 지정됩니다. ObjectOS는 프로젝트 세션에 대해 광범위한 루트 도메인 쿠키를 의도적으로 피합니다. 이는 세션이 고객 프로젝트 간에 유출되는 것을 방지합니다.

소셜 로그인

애플리케이션 패키지가 인증 구성을 노출하는 방식에 따라 환경 변수 또는 시스템 설정을 통해 제공자 자격 증명을 구성하세요.

제공자 콜백 URL은 제공자 유형에 따라 다릅니다. ObjectStack은 두 가지 서로 다른 콜백 경로를 노출하며 이들은 서로 호환되지 않습니다.

제공자 유형	콜백 경로
내장 소셜 (Google, GitHub, Microsoft, Apple, …)	`/api/v1/auth/callback/<provider>`
일반 OIDC / OAuth2 (Okta, Entra ID, Keycloak, Ping, …)	`/api/v1/auth/oauth2/callback/<provider>`

예시:

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

ObjectOS에서 제공자를 활성화하기 전에 ID 제공자의 애플리케이션 등록에서 일치하는 리디렉션 URI를 구성하세요.

엔터프라이즈 OIDC/SSO

OIDC 제공자는 일반 OAuth2 제공자로 등록되며 /api/v1/auth/oauth2/callback/<provider> 경로를 사용합니다. 일반적인 구성에는 다음이 필요합니다.

필드	설명
Provider id	`okta` 또는 `entra`와 같은 안정적인 id (콜백 URL에 사용됨)
Display name	사용자에게 표시되는 버튼 레이블
Discovery URL	`.well-known/openid-configuration` 엔드포인트
Client id	ID 제공자의 애플리케이션 클라이언트 id
Client secret	환경 또는 암호화된 설정에 저장되는 시크릿
Scopes	일반적으로 `openid email profile`

고객 배포의 경우 수동으로 구성된 authorization/token/userinfo 엔드포인트보다 OIDC 디스커버리 URL을 선호하세요.

플랫폼 SSO

클라우드에 연결된 배포에서 ObjectOS는 컨트롤 플레인 로그인을 플랫폼 SSO 제공자로 사용할 수 있습니다. 이미 컨트롤 플레인에 로그인한 빌더는 별도의 프로젝트 로컬 계정을 생성하지 않고도 프로젝트 런타임에 프로비저닝될 수 있습니다.

이를 위해서는 컨트롤 플레인과 ObjectOS가 동일한 OS_AUTH_SECRET 기본 시크릿을 공유해야 합니다. 고객이 모든 프로젝트가 완전히 별도의 로그인 경계를 소유하기를 원하는 경우에만 플랫폼 SSO를 비활성화하세요.

운영 점검

프로덕션 전에:

만료된 토큰이 401을 반환하는지 확인하세요;
로그아웃이 활성 세션을 취소하는지 확인하세요;
정책에서 요구하는 경우 비밀번호 재설정이 다른 세션을 취소하는지 확인하세요;
콜백 URL이 공개 프로젝트 도메인과 일치하는지 확인하세요;
신뢰할 수 있는 출처에 승인된 도메인만 포함되는지 확인하세요;
OS_AUTH_SECRET이 소스가 아닌 시크릿 관리자에 저장되는지 확인하세요.

다음 단계

인증은 사용자가 누구인지를 확립합니다. 로그인 후 사용자가 무엇에 액세스할 수 있는지 제어하려면 Permissions를 참조하세요. 브라우저가 아닌 클라이언트 및 머신 간 액세스에 대해서는 API access를 참조하세요.

인증

On this page