BizRouter 비즈라우터

Microsoft Entra ID SAML 연동

조직 관리자는 콘솔 로그인을 OIDC 대신 SAML 2.0 으로 설정할 수 있습니다. 이 문서는 Microsoft Entra ID (엔터프라이즈 애플리케이션의 SAML 기반 로그온)를 기준으로 설정 순서와 BizRouter 가 응답에서 확인하는 항목을 정리합니다. 화면 이름은 Entra 버전에 따라 조금 다를 수 있습니다. 로그인 뒤의 통제는 OIDC 와 같습니다 SAML 로그인도 IP 허용 목록, 2차 인증, 세션 정책, SSO 전용, 구성원 자동 등록, 계정 연결 증명, 관리 이력과 로그인 이력을 OIDC 와 같은 코드로 지납니다. 로그인 방식만 다릅니다. 이 기능은 조직이 설정하기 전에는 꺼져 있고, 기존 OIDC·비밀번호·Google 로그인은 바뀌지 않습니다.

지원 범위

지원하지 않는 항목은 조용히 넘기지 않고 거부합니다 항목 상태 내용

설정 순서

BizRouter 콘솔에서 값을 확인하고, Entra ID 에 등록한 뒤, 다시 BizRouter 에 저장합니다

설정 순서 · BizRouter 에서 SAML 을 고르고 등록할 값을 확인합니다

설정 → 보안 의 SSO 에서 로그인 방식을 「SAML 2.0」으로 고르면 「IdP 앱 등록에 넣을 값」이 나옵니다. 식별자(Entity ID), 회신 URL(ACS), SP 메타데이터 URL 이며 복사 버튼이 있습니다. 설정을 저장하기 전에도 같은 값이 표시됩니다.

설정 순서 · Entra ID 에서 애플리케이션을 만듭니다

엔터프라이즈 애플리케이션에서 새 애플리케이션 → 자체 애플리케이션 만들기를 누르고 「갤러리에 없는 다른 애플리케이션 통합」을 고릅니다. 만든 앱의 Single Sign-On 에서 SAML 을 고르고 기본 SAML 구성에 아래 값을 넣습니다. SP 메타데이터 URL 의 파일을 업로드해도 같은 값이 채워집니다. Entra ID 항목 값 식별자(엔터티 ID) https://bizrouter.ai/saml/<조직 ID> (콘솔에 표시된 값을 그대로 사용합니다) 회신 URL(Assertion Consumer Service URL) https://bizrouter.ai/api/web/auth/sso/saml/acs 로그온 URL · 릴레이 상태 · 로그아웃 URL 비워 둡니다. IdP 에서 시작하는 로그인과 단일 로그아웃을 지원하지 않기 때문입니다. 식별자는 조직마다 서버가 정하며 바꿀 수 없습니다. 이 값이 계정 연결의 기준(IdP 와 식별자의 조합)이므로, 값이 달라지면 기존 연결이 모두 무효가 됩니다.

설정 순서 · 사용자 식별자 속성을 지정합니다 (필수)

BizRouter 는 구성원을 바뀌지 않는 식별자로 알아봅니다. Entra ID 의 NameID 는 기본이 사용자 이름(UPN)이고 이메일 형태입니다. UPN 은 퇴사자의 이름을 다른 사람이 받는 것처럼 다시 쓰일 수 있고, 그러면 새로 같은 이름을 받은 사람이 연결 확인 없이 이전 구성원의 계정을 이어받게 됩니다. 그래서 BizRouter 는 식별자가 이메일 형태이면 로그인을 거부하고, 이메일·UPN·사용자 이름류 속성(mail, email, emailaddress, upn, userprincipalname, name 등)을 「사용자 식별자 속성」으로 저장하는 것도 거부합니다. SAML 응답에 담긴 속성을 지정하십시오. Entra ID 는 기본 설정에서 이 속성을 응답에 담아 보냅니다. 응답에 없으면 특성 및 클레임에서 추가합니다. Okta 등 다른 IdP 에서는 바뀌지 않는 사용자 ID 속성(예: Okta 의 user.id )을 SAML 속성으로 내보내도록 설정하고 그 속성 이름을 지정합니다. 사용자 식별자 속성을 나중에 바꾸면 모든 구성원이 SSO 계정을 다시 연결해야 하므로 처음에 정확히 정하십시오. BizRouter 설정 권장 값 비워 두면 사용자 식별자 속성 NameID 를 씁니다. 이메일 형태 NameID 와 매번 바뀌는 NameID(transient)는 거부하므로 Entra ID 에서는 비워 둘 수 없습니다. 이메일 속성 이 속성, mail, email, 이메일 형식의 NameID 순으로 찾습니다. 이름 속성 http://schemas.microsoft.com/identity/claims/displayname displayname, displayName, name 순으로 찾습니다. 한 속성에 값이 여러 개인 응답(식별자·이메일)은 거부합니다. 이메일은 연결할 계정의 후보일 뿐이며 이메일만으로는 로그인되지 않습니다.

설정 순서 · 서명 인증서와 로그인 URL 을 BizRouter 로 가져옵니다

Entra ID 앱의 SAML 인증서에서 「앱 페더레이션 메타데이터 URL」을 복사해 BizRouter 의 「IdP 메타데이터 가져오기」에 붙여 넣고 「가져오기」를 누릅니다. 엔터티 ID(Issuer), 로그인 URL, 서명 인증서가 채워집니다. 현재 인증서와 예정 인증서가 함께 있으면 모두 등록됩니다. 메타데이터 XML 을 직접 붙여 넣거나 인증서를 직접 붙여 넣어도 됩니다. 가져오기만으로는 아무것도 저장되지 않으며, 내용을 확인한 뒤 저장해야 합니다. 메타데이터 서명은 확인하지 않습니다 메타데이터는 공개 https 주소(사설·내부 주소는 거부, 512KB 이하)에서 가져오거나 붙여 넣은 것을 그대로 믿습니다. IdP 가 알려 준 주소와 파일만 사용하십시오. 발급자(Issuer)는 메타데이터의 entityID 이며 Entra ID 는 끝에 슬래시가 붙은 https://sts.windows.net/<테넌트 ID>/ 형식입니다. 비교는 문자 하나까지 같아야 하므로 슬래시를 지우지 않습니다.

설정 순서 · 허용 이메일 도메인을 인증하고, 앱을 구성원에게 할당합니다

허용 이메일 도메인은 OIDC 와 같이 DNS TXT 레코드로 소유를 증명한 도메인만 SSO 로그인에 쓰입니다. Entra ID 의 사용자 및 그룹에서 로그인할 구성원에게 앱을 할당합니다.

설정 순서 · 저장하고 다른 브라우저에서 로그인을 확인합니다

「SSO 사용」을 켜고 저장합니다. 저장할 때 로그인 URL 이 공개 https 주소인지, 만료되지 않은 인증서가 있는지 확인합니다. 로그인 화면에 회사 이메일을 입력하고 「회사 SSO로 로그인」을 누르면 Entra ID 로 이동합니다. 처음 로그인하는 기존 구성원은 비밀번호 또는 Google 로 본인 확인 로그인을 한 번 거친 뒤 계정을 연결합니다. 모든 구성원이 연결되고 SSO 로그인에 한 번 성공한 뒤에 「SSO 전용」을 켤 수 있습니다.

BizRouter 가 응답에서 확인하는 것

하나라도 맞지 않으면 로그인시키지 않습니다 XML 은 DOCTYPE·엔티티·외부 참조 없이 512KB 이하여야 합니다. 서명은 등록한 인증서로만 검증합니다. 서명 안에 들어 있는 인증서는 믿지 않습니다. 검증된 서명이 실제로 덮은 요소에서만 값을 읽고, 문서 안의 어설션은 정확히 하나여야 합니다. 상태(Status)가 성공이고, 발급자, 목적지(Destination), 수신자(Recipient), 대상(Audience = 식별자)이 우리 값과 같아야 합니다. 응답과 어설션 모두 우리가 보낸 요청의 ID(InResponseTo)를 가리켜야 하며 요청 ID 는 한 번만 쓸 수 있습니다. 유효 시간(NotBefore·NotOnOrAfter)은 시계 오차 ±120초까지 허용합니다. 같은 어설션 ID 는 한 번만 받습니다. 사용자 식별자는 비어 있지 않고, 255자 이하이고, 값이 하나이고, @ 가 없어야 합니다. NameID 를 식별자로 쓸 때는 형식이 transient 나 emailAddress 가 아니어야 합니다. 계정 연결은 사용자 식별자 속성별로 따로 관리되어, 속성을 바꾸면 옛 연결은 새 속성의 값과 맞추지 않습니다. IdP 의 응답은 브라우저가 BizRouter 로 보냅니다. 서버는 응답을 검증한 뒤 1회용 티켓(2분)을 만들어 콘솔로 돌려보내고, 로그인을 시작한 브라우저의 쿠키가 있어야만 티켓을 사용할 수 있습니다. 다른 사람의 로그인 응답을 내 브라우저에 끼워 넣는 공격을 막기 위한 것입니다. 등록한 IdP 인증서가 모두 만료되면 로그인 시작 단계에서 멈춥니다. 만료 30일 전부터 설정 화면에 경고가 표시됩니다.

인증서 교체

로그인이 끊기지 않게 현재 인증서와 새 인증서를 함께 등록합니다 IdP 가 새 서명 인증서를 쓰기 전에 BizRouter 에 현재 인증서와 새 인증서를 함께 등록하십시오. 메타데이터를 다시 가져오면 현재와 예정 인증서가 모두 등록됩니다. 기존 인증서가 하나라도 남아 있으면 SSO 로그인 확인 기록은 유지되므로 SSO 전용을 끄지 않아도 됩니다. 기존 인증서와 겹치는 것이 하나도 없는 인증서 목록으로 바꾸면 다른 IdP 로 보고 로그인 확인 기록을 지웁니다. 서명 인증서는 RSA 2048비트 이상 또는 ECDSA(P-256 이상)여야 하고, 최대 5개까지 등록합니다. 설정 화면은 인증서의 지문(SHA-256), 주체, 유효 기간만 보여 주고 원문은 돌려주지 않으며, 관리 이력에는 지문만 기록합니다.

인증서 알림 메일

만료 전에 미리, 바뀔 때는 다른 관리자에게 SAML 이 켜진 조직은 매일 한 번 인증서를 확인합니다. 등록된 인증서 중 쓸 수 있는 것의 가장 늦은 만료일을 기준으로 만료 30일 전, 7일 전, 1일 전과 모두 만료된 뒤에 조직의 활성 관리자 모두에게 메일을 보냅니다. 같은 인증서 구성과 같은 시점에는 한 번만 보내며, 보낸 기록은 관리 이력에 「SSO 인증서 만료 예고 메일 발송」으로 남습니다. 메일에는 언제 끊기는지, 무엇을 해야 하는지, SSO 전용 조직은 비밀번호로도 들어올 수 없다는 점이 적혀 있습니다. 관리자 계정에도 SSO 전용이 적용된 조직은 관리자도 콘솔에 들어와 고칠 수 없게 되므로 만료 전에 처리하십시오. 인증서를 추가, 교체, 삭제하는 저장을 하면 저장한 관리자를 뺀 다른 활성 관리자 모두에게 알림 메일을 보냅니다. 메일에는 추가되거나 제거된 인증서 지문의 앞 12자와 바꾼 관리자, 시각이 적혀 있습니다(전체 지문은 관리 이력에 있습니다). 이 인증서로 서명된 응답은 구성원 누구의 이름으로든 콘솔에 들어올 수 있으므로, 다른 관리자가 직접 하지 않은 변경을 알아차릴 수 있게 한 것입니다. 관리자가 한 명뿐이면 보낼 사람이 없습니다.

OIDC 에서 바꾸기

방식을 바꾸면 기존 계정 연결은 새 방식에서 쓸 수 없습니다 같은 설정에서 로그인 방식만 바꿉니다. 방식이 바뀌면 이전 방식으로 만든 계정 연결은 새 방식에서 인정되지 않으므로 SSO 로그인 확인을 다시 해야 합니다. 구성원은 처음 로그인할 때 본인 확인 로그인을 거쳐 다시 연결합니다. 잠금을 막기 위해 방식을 바꾸는 저장에서는 「SSO 전용」을 켤 수 없고, SSO 전용이 켜져 있다면 같은 저장에서 끌 때만 방식을 바꿀 수 있습니다. 바꾸기 전과 후의 설정은 관리 이력에 남습니다. OIDC 로 되돌릴 때는 클라이언트 시크릿을 다시 입력해야 합니다. SAML 의 「사용자 식별자 속성」을 바꾸는 것도 같습니다. 옛 속성으로 만든 계정 연결은 새 속성의 값과 맞지 않으므로 모든 구성원이 다시 연결해야 하고, 로그인 확인 기록이 지워집니다. 그래서 속성을 바꾸는 저장에서는 「SSO 전용」과 「관리자 계정에도 적용」을 켠 채로 저장할 수 없습니다. 설정 화면은 저장 전에 한 번 더 확인합니다.

오류 확인

로그인에 실패하면 구성원에게는 간단한 안내만 보이고, 원인은 로그인 이력에 남습니다 설정 → 접속·관리 이력 → 로그인 이력 에서 SSO 로그인의 실패 사유를 볼 수 있습니다. 서명이 확인되기 전의 응답에 적힌 이메일은 기록하지 않습니다. 어느 조직이 시작한 로그인에 대한 응답인지 알 수 없는 응답(요청 ID 가 없거나 모르는 응답, 10분이 지난 응답, 읽을 수 없는 XML, IdP 앱 목록에서 시작한 로그인)은 이력에 남지 않습니다. 이 경우 구성원 화면에는 BizRouter 로그인 화면에서 다시 시작하라는 안내가 나옵니다. 실패 사유 의미 조치 IdP 의 MFA 를 믿는 설정 「IdP 의 MFA 를 신뢰」를 켜면 SSO 로그인은 콘솔 2차 인증을 건너뜁니다. SAML 응답의 인증 수단(AuthnContext)은 확인하지 않으므로, IdP 에서 MFA 를 강제하는 경우에만 켜십시오. 조직 또는 상위 조직이 2차 인증을 요구하면 이 설정과 관계없이 콘솔 2차 인증을 거칩니다. IP 허용 목록은 항상 적용됩니다.

bg-gray-100 px-1 rounded font-mono break-all http://schemas.microsoft.com/identity/claims/objectidentifier http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress BizRouter 에서 시작하는 로그인(SP-initiated) 지원 로그인 화면에서 회사 이메일을 입력하면 IdP 로 이동합니다. 요청은 HTTP-Redirect, 응답은 HTTP-POST 방식입니다. IdP 앱 목록에서 시작하는 로그인(IdP-initiated) 거부 응답에 우리가 보낸 요청의 ID(InResponseTo)가 없으면 로그인시키지 않습니다. 구성원은 BizRouter 로그인 화면에서 시작해야 합니다. 응답 서명 필수 응답(Response) 또는 어설션(Assertion) 중 하나 이상이 서명되어야 합니다. 서명이 있으면 둘 다 검증합니다. RSA(SHA-256·384·512)와 ECDSA(SHA-256 이상)만 받고 SHA-1 은 거부합니다. 암호화된 어설션 미지원 암호화된 어설션이 오면 명시적으로 거부합니다. IdP 에서 어설션 암호화를 끄고 서명만 사용하십시오. 서명된 인증 요청 미지원 인증 요청(AuthnRequest)에는 서명하지 않습니다. 서명된 요청을 요구하는 IdP 는 쓸 수 없습니다. 단일 로그아웃(SLO) 미지원 IdP 에서 로그아웃해도 BizRouter 콘솔 세션은 유지됩니다. 세션은 조직의 세션 정책(최대 기간·유휴 만료)을 따릅니다. SAML: 서명 없음·검증 실패 응답에 서명이 없거나 등록한 인증서로 검증되지 않았습니다. 허용되지 않은 알고리즘(SHA-1 등)도 여기에 남습니다. IdP 가 서명하는 인증서와 BizRouter 에 등록한 인증서가 같은지, 서명 알고리즘이 SHA-256 이상인지 확인합니다. SAML: IdP 서명 인증서 만료 등록한 인증서가 모두 만료되었거나 아직 유효하지 않습니다. IdP 에서 새 인증서를 받아 메타데이터를 다시 가져옵니다. SAML: 대상 불일치 발급자, 수신자(Recipient), 대상(Audience), 목적지(Destination), 요청 ID 중 하나가 맞지 않습니다. IdP 앱의 식별자와 회신 URL 이 화면의 값과 정확히 같은지 확인합니다. 발급자는 문자 하나까지 같아야 하며 끝의 슬래시도 포함합니다. SAML: 유효 시간이 지났거나 아직 유효하지 않은 응답 어설션의 유효 시간이 지났거나 시작 전입니다. 서버와 IdP 의 시계가 2분 넘게 어긋나도 남습니다. 서버 시각과 IdP 시각을 확인하고, 로그인을 처음부터 다시 시도합니다. SAML: 이미 사용된 응답(재사용) 같은 어설션이 두 번 제출되었습니다. 뒤로 가기나 새로 고침으로 응답을 다시 보낸 경우가 대부분입니다. 반복되면 의심스러운 접근으로 봅니다. SAML: 이미 사용됐거나 설정 변경으로 무효가 된 로그인 요청 응답이 답하는 요청을 다른 응답이 이미 사용했거나, 로그인하는 도중 SSO 설정이 바뀌거나 꺼졌습니다. 구성원에게 BizRouter 로그인 화면에서 처음부터 다시 시작하도록 안내합니다. SAML: 사용자 식별자 오류 식별자가 없거나, 255자를 넘거나, 값이 여러 개이거나, 매번 바뀌는 NameID(transient)입니다. 「사용자 식별자 속성」에 바뀌지 않는 속성을 지정합니다. SAML: 사용자 식별자가 이메일 형태 IdP 가 사용자 식별자로 보낸 값에 @ 가 있거나 NameID 형식이 emailAddress 입니다. 이메일·UPN 은 다른 사람이 같은 값을 받을 수 있어 거부합니다. 「사용자 식별자 속성」에 바뀌지 않는 식별자(Entra 는 objectidentifier, Okta 는 user.id)를 지정합니다. SAML: 응답 형식 오류 XML 을 읽을 수 없거나, DOCTYPE 이 있거나, 어설션이 하나가 아니거나, 평가할 수 없는 조건이 있습니다. IdP 의 SAML 설정을 확인합니다. 암호화된 어설션이면 암호화를 끕니다. SAML: IdP 가 로그인을 거부함 IdP 가 성공이 아닌 상태를 돌려주었습니다. IdP 에서 해당 사용자에게 앱이 할당되어 있는지 확인합니다.

주식회사 AI3 | 서울 강남구 영동대로85길 34 | support@bizrouter.ai