Okta와 SAML SSO
이 가이드는 Okta를 예로 들어 IdP(Identity Provider)와 SAML Single Sign-On (SSO)을 설정하는 과정을 안내합니다. 고급 구성 세부 사항 및 전체 API 참조는 SSO 플러그인 문서를 확인하세요.
SAML이란?
SAML(Security Assertion Markup Language)은 IdP(Identity Provider)(예: Okta, Azure AD, OneLogin)와 SP(Service Provider)(이 경우 Better Auth) 간에 인증 및 권한 부여 데이터를 교환하기 위한 XML 기반 표준입니다.
이 설정에서:
- IdP(Okta): 사용자를 인증하고 신원에 대한 어설션을 보냅니다.
- SP(Better Auth): 어설션을 검증하고 사용자를 로그인시킵니다.
1단계: Okta에서 SAML 애플리케이션 생성
-
Okta 관리 콘솔에 로그인합니다
-
Applications > Applications로 이동합니다
-
"Create App Integration"을 클릭합니다
-
로그인 방법으로 "SAML 2.0"을 선택합니다
-
다음 설정을 구성합니다:
- Single Sign-on URL: Better Auth ACS 엔드포인트(예:
http://localhost:3000/api/auth/sso/saml2/sp/acs/sso). 여기서sso는 providerId입니다 - Audience URI (SP Entity ID): Better Auth 메타데이터 URL(예:
http://localhost:3000/api/auth/sso/saml2/sp/metadata) - Name ID format: Email Address 또는 원하는 형식.
- Single Sign-on URL: Better Auth ACS 엔드포인트(예:
-
IdP 메타데이터 XML 파일 및 인증서를 다운로드합니다
2단계: Better Auth 구성
다음은 개발 환경에서 Okta에 대한 예제 구성입니다:
const ssoConfig = {
defaultSSO: [{
domain: "localhost:3000", // 도메인
providerId: "sso",
samlConfig: {
// SP 구성
issuer: "http://localhost:3000/api/auth/sso/saml2/sp/metadata",
entryPoint: "https://trial-1076874.okta.com/app/trial-1076874_samltest_1/exktofb0a62hqLAUL697/sso/saml",
callbackUrl: "/dashboard", // 성공적인 인증 후 리디렉션
// IdP 구성
idpMetadata: {
entityID: "https://trial-1076874.okta.com/app/exktofb0a62hqLAUL697/sso/saml/metadata",
singleSignOnService: [{
Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
Location: "https://trial-1076874.okta.com/app/trial-1076874_samltest_1/exktofb0a62hqLAUL697/sso/saml"
}],
cert: `-----BEGIN CERTIFICATE-----
MIIDqjCCApKgAwIBAgIGAZhVGMeUMA0GCSqGSIb3DQEBCwUAMIGVMQswCQYDVQQGEwJVUzETMBEG
...
[Okta 인증서]
...
-----END CERTIFICATE-----`
},
// SP 메타데이터
spMetadata: {
metadata: `<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
entityID="http://localhost:3000/api/sso/saml2/sp/metadata">
...
[SP 메타데이터 XML]
...
</md:EntityDescriptor>`
}
}
}]
}3단계: 다중 기본 프로바이더 (선택 사항)
다양한 도메인에 대해 여러 SAML 프로바이더를 구성할 수 있습니다:
const ssoConfig = {
defaultSSO: [
{
domain: "company.com",
providerId: "company-okta",
samlConfig: {
// company.com용 Okta SAML 구성
}
},
{
domain: "partner.com",
providerId: "partner-adfs",
samlConfig: {
// partner.com용 ADFS SAML 구성
}
},
{
domain: "contractor.org",
providerId: "contractor-azure",
samlConfig: {
// contractor.org용 Azure AD SAML 구성
}
}
]
}명시적: 로그인 시 providerId를 직접 전달합니다.
도메인 폴백: 사용자의 이메일 도메인을 기반으로 일치합니다. 예: user@company.com → company-okta 프로바이더와 일치.
4단계: 로그인 시작
SSO 플로우를 시작하는 세 가지 방법이 있습니다:
1. providerId로 명시적으로 (권장):
// 사용할 프로바이더를 명시적으로 지정
await authClient.signIn.sso({
providerId: "company-okta",
callbackURL: "/dashboard"
});2. 이메일 도메인 일치로:
// 이메일 도메인을 기반으로 프로바이더를 자동으로 일치
await authClient.signIn.sso({
email: "user@company.com",
callbackURL: "/dashboard"
});3. 도메인 지정으로:
// 일치를 위해 도메인을 명시적으로 지정
await authClient.signIn.sso({
domain: "partner.com",
callbackURL: "/dashboard"
});중요 참고 사항:
- DummyIDP는 개발 및 테스트용으로만 사용해야 합니다
- 프로덕션에서는 이러한 인증서를 절대 사용하지 마세요
- 예제는
localhost:3000을 사용합니다 - 환경에 맞게 URL을 조정하세요 - 프로덕션의 경우 항상 Okta, Azure AD 또는 OneLogin과 같은 적절한 IdP 프로바이더를 사용하세요
5단계: SAML 프로바이더 동적 등록
동적 등록의 경우 API를 사용하여 SAML 프로바이더를 등록해야 합니다. 자세한 등록 지침은 SSO 플러그인 문서를 참조하세요.
등록 예제:
await authClient.sso.register({
providerId: "okta-prod",
issuer: "https://your-domain.com",
domain: "your-domain.com",
samlConfig: {
// 프로덕션 SAML 구성
}
});