BizRouter 비즈라우터

Microsoft Entra ID SCIM 연동

SCIM 2.0 으로 Microsoft Entra ID 가 BizRouter 구성원을 만들고, 이름을 맞추고, 퇴사·전배 때 비활성화합니다. Entra 에서 사용자를 끄면 BizRouter 계정, API 키, 로그인 세션이 같은 요청 안에서 막히므로 미사용 계정을 따로 찾아 잠글 필요가 없습니다.

시작하기 전에

SCIM 은 SSO 로 로그인하는 조직에서만 쓸 수 있습니다 조직 관리자(owner)여야 합니다. 설정 › 보안의 SSO 에 Microsoft Entra ID 를 등록하고, 허용 도메인의 소유를 DNS TXT 레코드로 인증한 뒤 「SSO 사용」을 켜야 합니다. 인증한 도메인이 하나도 없거나 SSO 가 꺼져 있으면 토큰을 만들 수 없고, 이미 만든 토큰도 403(「조직의 SSO 가 꺼져 있습니다」 등)으로 멈춥니다. SSO 를 다시 켜면 같은 토큰이 다시 동작합니다. 웍스AI 와 연동되어 웍스AI 로그인으로 구성원을 관리하는 조직에서는 SCIM 을 쓸 수 없습니다. Entra 쪽에는 이 용도로 쓸 엔터프라이즈 애플리케이션(갤러리에 없는 직접 만든 앱, Create your own application)이 필요합니다.

연동 순서

BizRouter 에서 토큰을 만들고 Entra 에 입력합니다

연동 순서 · SCIM 토큰 만들기

설정 › 보안의 「SCIM 자동 프로비저닝」에서 이름과 만료 기간(만료 없음 또는 90·180·365일)을 정해 토큰을 만듭니다. 토큰은 만들 때 한 번만 보이고 다시 확인할 수 없으며, BizRouter 에는 해시만 저장합니다. 토큰은 최대 5개까지 함께 쓸 수 있습니다.

연동 순서 · Entra 에서 프로비저닝 연결하기

Entra 관리 센터에서 엔터프라이즈 애플리케이션 › 프로비저닝으로 가서 프로비저닝 모드를 「자동」으로 두고, 관리자 자격 증명에 다음 값을 입력한 뒤 「연결 테스트」를 누릅니다. 웹 콘솔 주소(bizrouter.ai)를 쓰지 마십시오 Microsoft 문서는 SCIM 엔드포인트가 받아야 하는 프로토콜로 TLS 1.2 를 규정합니다. BizRouter 웹 콘솔 주소 bizrouter.ai 는 TLS 1.3 만 받으므로 같은 경로라도 Entra 의 연결 테스트가 핸드셰이크 단계에서 실패할 수 있습니다. TLS 1.2(ECDHE 와 AES-GCM·CHACHA20 암호군)를 허용하는 호스트는 api.bizrouter.ai 입니다.

연동 순서 · 속성 매핑 맞추기

「Provision Microsoft Entra ID Users」의 매핑에서 아래 표처럼 연결하고, 「Provision Microsoft Entra ID Groups」는 끕니다. Groups 는 지원하지 않으며, 쓰기 요청에는 501 로 답합니다.

연동 순서 · 프로비저닝 켜기

프로비저닝 상태를 「켜기」로 바꿉니다. 할당한 사용자는 Entra 의 프로비저닝 주기에 따라 전달되며, Entra 의 「요청 시 프로비저닝(Provision on demand)」으로 한 사용자만 바로 시험할 수 있습니다. 처음 로그인할 때 SCIM 으로 만든 구성원은 비밀번호가 없습니다. 처음 SSO 로 로그인하면 계정 주소로 인증번호가 메일로 가고, 그 번호를 한 번 입력하면 SSO 계정이 그 구성원에게 연결됩니다. SCIM 이 SSO 연결을 대신 만들어 주지는 않으므로, 이메일만 같은 다른 사람이 계정을 가져갈 수 없습니다. 이미 비밀번호나 Google 연결, 다른 SSO 연결이 있는 기존 계정은 이 경로를 쓰지 않고 기존처럼 본인 확인 로그인을 거쳐 연결합니다.

속성 매핑

BizRouter 가 쓰는 속성과 무시하는 속성 Entra 속성 SCIM 속성 BizRouter 처리 일치 기준(Matching attribute) 이미 BizRouter 에 있는 구성원을 Entra 가 알아보게 하려면 사용자 매핑의 일치 기준 1순위를 userName 으로 두십시오. BizRouter 는 SCIM 이 만들었거나 넘겨받은 구성원만 externalId 로 찾을 수 있습니다.

구성원의 생명주기

Entra 의 동작과 BizRouter 의 처리 Entra 에서 요청 BizRouter 처리 비활성화는 BizRouter 관리자가 콘솔에서 구성원을 삭제할 때와 같은 처리입니다. 같은 요청이 끝났을 때 계정 로그인, 콘솔 세션, CLI 세션, 모델 호출용 API 키, 사용량 조회용 API 키가 모두 막혀 있습니다.

SCIM 이 하지 않는 것

Entra 가 바꿀 수 없도록 막아 둔 것 관리자(owner) 계정 의 비활성화·삭제·이메일 변경은 거부합니다(mutability). 이름과 식별자는 바꿀 수 있습니다. 관리자 계정은 Entra 할당 범위에서 빼 두는 것을 권장합니다. 이미 로그인 수단이 있는 구성원의 이메일(userName) 은 바꾸지 못합니다(mutability). 비밀번호, Google 연결, SSO 연결 중 하나라도 있으면 그렇습니다. 이메일은 비밀번호 재설정 메일이 가는 곳이라, 바꿀 수 있으면 다른 사람의 메일함으로 계정을 옮길 수 있기 때문입니다. 아직 로그인 수단이 없는 SCIM 생성 계정은 바꿀 수 있고, 대소문자만 다른 변경은 변경으로 보지 않습니다. 권한 은 SCIM 으로 만들 수도 바꿀 수도 없습니다. 새 구성원은 항상 일반 구성원이고, 기존 구성원을 넘겨받아도 권한은 그대로입니다. BizRouter 관리자가 콘솔에서 끄거나 미접속 정책이 비활성화한 계정, 계정 차단된 계정은 SCIM 이 다시 켜지 않습니다(mutability). 콘솔에서 구성원을 다시 초대하십시오. SCIM 이 끈 계정이라도 그 뒤에 관리자가 다시 초대했다가 다시 끈 경우에는 관리자의 결정이 우선하므로 SCIM 이 켜지 않습니다. 인증된 도메인 밖 의 계정, 다른 조직 소속 계정, WRKS 연동 계정, 운영 계정은 SCIM 에서 없는 것과 같게 응답합니다. 만들려는 주소가 다른 조직에 있으면 어느 경우인지 알려 주지 않는 같은 오류(400 invalidValue)를 돌려줍니다. 조직 설정에 이메일 도메인 정책이 있으면 생성·이메일 변경·재활성화에도 그대로 적용합니다. 구성원 수 제한은 없습니다 BizRouter 의 초대 경로에는 구성원 수나 요금제에 따른 제한이 없어 SCIM 도 같은 기준으로 조직이 활성 상태인지와 이메일 도메인 정책만 확인합니다.

토큰 관리

교체와 폐기 토큰을 바꿀 때는 새 토큰을 만들어 Entra 에 넣고 연결 테스트를 마친 뒤 이전 토큰을 폐기합니다. 폐기한 토큰은 다음 요청부터 401 이 됩니다. SSO 설정을 삭제하거나 IdP 를 바꿔 저장하면(로그인 방식, 발급자, 클라이언트, Entra 테넌트, SAML 의 로그인 주소, 서명 인증서가 하나도 겹치지 않을 때) 그 조직의 SCIM 토큰은 모두 자동으로 폐기되고 「관리 이력」에 사유와 함께 남습니다. 새 IdP 에 이전 토큰이 이어지지 않으므로 새 토큰을 만들어 Entra 에 다시 넣어야 합니다. 같은 IdP 의 설정만 고치거나 인증서를 교체하는 저장, SSO 를 껐다 켜는 것은 토큰을 폐기하지 않습니다. 목록에는 이름, 앞부분, 만든 시각, 마지막 사용 시각, 만료가 보입니다. 토큰 값 자체는 어디에도 다시 나타나지 않습니다. 토큰을 만들고 폐기한 기록은 「관리 이력」에 남습니다.

관리 이력

SCIM 이 한 일은 모두 기록합니다 이력 항목 언제 구성원 자동 등록(SCIM) SCIM 이 계정을 만들었을 때 구성원 정보 변경(SCIM) 이름·이메일·식별자가 바뀌었거나 기존 구성원을 넘겨받았을 때 구성원 비활성화(SCIM) active=false 또는 삭제로 계정이 꺼졌을 때 구성원 재활성화(SCIM) SCIM 이 끈 계정이 다시 켜졌을 때 SCIM 토큰 발급, SCIM 토큰 폐기 관리자가 토큰을 만들거나 폐기했을 때 SCIM 이 만든 행에는 사람 대신 「처리한 SCIM 토큰」(토큰 이름과 앞부분)과 요청한 IP 주소가 남습니다. 토큰 값과 해시는 기록하지 않습니다. 로그인 이력에는 아무것도 쓰지 않습니다.

엔드포인트와 응답

Entra 가 아닌 클라이언트에서 직접 호출할 때의 참고 Base URL 요청은 Authorization: Bearer <SCIM 토큰> 으로 인증하고, 토큰이 조직을 정합니다. URL 이나 본문에 조직을 지정하는 방법은 없습니다. 응답은 모두 application/scim+json 입니다. Endpoint 설명 GET /ServiceProviderConfig, /ResourceTypes, /Schemas 지원 범위를 알리는 문서입니다. PATCH·filter 를 지원하고 Bulk·정렬·ETag·비밀번호 변경은 지원하지 않습니다. GET /Users filter 는 userName eq , externalId eq , id eq 만 받고, 그 밖의 filter 는 400 invalidFilter 입니다. startIndex(1부터, 최대 1,000,000 — 넘으면 400), count(기본 100, 최대 200)로 나눠 가져옵니다. POST /Users 사용자를 만듭니다. 201 과 Location 헤더를 돌려줍니다. GET, PUT, PATCH, DELETE /Users/{id} id 는 BizRouter 사용자 ID 입니다. PATCH 는 add·replace·remove 를 받으며 op 는 대소문자를 가리지 않고, path 가 없는 value 객체와 filter 가 든 path 도 받습니다. DELETE 는 204 입니다. GET /Groups 빈 목록을 돌려줍니다. Groups 에 쓰기 요청을 보내면 501 입니다.

오류 응답

SCIM 오류 스키마(urn:ietf:params:scim:api:messages:2.0:Error)로 답합니다 401 인증 실패 토큰이 없거나 틀렸거나, 폐기·만료되었습니다. 어느 경우인지는 알려 주지 않으며 응답에 WWW-Authenticate: Bearer 가 붙습니다. 403 사용할 수 없는 조직 조직이 활성 상태가 아니거나, SSO 가 꺼져 있거나, SSO 설정·인증된 도메인이 없습니다. 토큰 오류(401)와 달리 토큰은 유효하고 조직의 상태가 원인이며, 응답 문구가 이유를 알려 줍니다. 409 uniqueness 같은 userName 이나 externalId 가 이미 있습니다. Entra 는 이어서 userName 으로 조회해 PATCH 합니다. 400 invalidValue userName 이 이메일이 아니거나 인증된 도메인이 아니거나, 이름이 255자를 넘습니다. 값을 잘라서 저장하지 않고 거부합니다. 프로비저닝할 수 없는 주소는 이유를 구분하지 않는 같은 문구로 답합니다. 400 mutability 관리자 계정의 비활성화·삭제, 관리자가 끈 계정의 재활성화, 권한·비밀번호 설정처럼 SCIM 으로 할 수 없는 변경입니다. 400 invalidSyntax · invalidFilter · noTarget 본문이나 filter 형식이 맞지 않거나, remove 에 path 가 없습니다. 429 요청 한도 토큰 하나당 분당 1,200건을 넘으면 Retry-After 와 함께 429 를 돌려줍니다. 틀린 토큰으로 연달아 요청하는 주소도 5분에 30건까지만 401 로 답하고 그 뒤에는 429 로 답합니다.

userPrincipalName 또는 mail userName 로그인 이메일입니다. 소문자로 저장하며, DNS 로 소유를 인증한 도메인의 주소여야 합니다. SSO 로그인 때 IdP 가 보내는 이메일(email)과 같은 값을 연결해야 같은 계정으로 이어집니다. displayName displayName 콘솔에 표시되는 이름입니다. 가장 먼저 쓰입니다. givenName, surname name.givenName, name.familyName displayName 도 name.formatted 도 없을 때 「givenName familyName」 순서로 이어 붙여 이름으로 씁니다. 한쪽만 바뀌는 변경도 나머지 한쪽을 기억해 올바르게 합칩니다. objectId 또는 mailNickname externalId Entra 쪽 식별자입니다. 조직 안에서 유일해야 하며, 이 값으로도 사용자를 찾을 수 있습니다. Switch([IsSoftDeleted], …) 또는 계정 사용 여부 active false 이면 구성원을 비활성화하고, 다시 true 가 되면 SCIM 이 비활성화한 계정에 한해 되살립니다. 불리언과 문자열 「True」「False」를 모두 받습니다. mail (이메일 속성) emails[type eq "work"].value 무시합니다. 계정의 주소는 userName 이며, 응답의 emails 는 userName 과 같은 값입니다. 그 밖의 속성(직함, 전화번호, 부서·관리자 같은 엔터프라이즈 확장 등) — 무시합니다. 오류로 처리하지 않으므로 매핑에 남아 있어도 프로비저닝이 멈추지 않습니다. 권한(roles), 비밀번호 roles, entitlements, password 값이 있으면 거부합니다(mutability). 무시하면 권한이 부여된 것처럼 보이기 때문입니다. 매핑에서 제외하십시오. 앱에 사용자를 할당합니다 POST /Users 구성원(member) 계정을 만듭니다. 이메일 인증은 완료 처리하고 비밀번호는 만들지 않으며, 로그인은 SSO 로 합니다. 이미 BizRouter 구성원인 이메일입니다 POST → 409 → GET filter → PATCH 409(uniqueness) 뒤 Entra 가 userName 으로 찾아 PATCH 하면 그 구성원을 SCIM 관리로 넘겨받습니다. 권한·로그인 방식·비밀번호는 바꾸지 않습니다. 이름이나 식별자가 바뀝니다 PATCH /Users/{id} 바뀐 속성만 반영하고 관리 이력에 이전 값과 새 값을 남깁니다. 한 요청 안의 작업 하나라도 잘못되면 전체를 거부하고 아무것도 바꾸지 않습니다. 사용자를 끄거나 앱 할당을 해제합니다 PATCH active=false 같은 요청 안에서 계정을 비활성화하고, 그 사용자의 API 키와 사용량 API 키를 끄고, 웹·CLI 로그인 세션을 모두 지웁니다. 계정과 사용 기록은 남습니다. Entra 에서 사용자를 삭제합니다 DELETE /Users/{id} 비활성화와 같은 효과이며 계정은 삭제하지 않습니다. 이후 SCIM 에서는 조회되지 않고, 같은 사용자를 Entra 가 다시 만들면 같은 계정이 되살아납니다. 꺼 둔 사용자를 다시 켭니다 PATCH active=true SCIM 이 비활성화한 계정만 켭니다. 이전 API 키와 세션은 돌아오지 않으므로 구성원이 다시 로그인해 새 키를 만듭니다.

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