Microsoft Entra ID와
연결(SSO·SCIM)

필요한 것

• Microsoft Entra admin center(https://entra.microsoft.com)에서 Application Administrator 이상의 역할.
• SSO(OpenID Connect)는 Entra ID의 무료 범위에서 쓸 수 있습니다.
• SCIM(자동 프로비저닝)은 갤러리에 없는 앱이므로 Entra ID P1 이상이 필요합니다(Microsoft 365 E3·E5, Business Premium 등에 포함).
• Aiyori 조직의 관리자가 강사 화면의 “설정” → “회사의 ID 관리 시스템과 연결” 화면을 열 수 있을 것.

하나의 앱에서 SSO와 SCIM을 모두 설정합니다. 엔터프라이즈 애플리케이션을 만들면 같은 이름의 앱 등록도 생깁니다. SSO는 앱 등록에서, SCIM은 엔터프라이즈 애플리케이션 쪽에서 설정합니다.

1. 앱 만들기

1. Entra admin center → Entra ID → Enterprise applications → + New application → + Create your own application.
2. 이름에 Aiyori를 입력하고, Integrate any other application you don’t find in the gallery (Non-gallery)를 골라 Create.
3. 만든 앱의 Properties에서 Assignment required? 항목을 Yes로 합니다(할당한 사람만 로그인할 수 있습니다). My Apps에 타일을 둘 때는 Home page URL에 https://app.aiyori.app/api/web/sso/start?code=(조직 코드)를 입력합니다. 마지막으로 Save.

2. SSO(OpenID Connect)

1. Entra ID → App registrations → All applications → 1에서 만든 Aiyori를 엽니다.
2. Overview의 Directory (tenant) ID와 Application (client) ID를 적어 둡니다.
3. Authentication → + Add a platform → Web → 리디렉션 URI에 https://app.aiyori.app/api/web/sso/callback을 입력하고 Configure. 암시적 허용(implicit grant)의 체크 2개는 넣지 않습니다(Aiyori는 인가 코드와 PKCE를 씁니다).
4. Certificates & secrets → Client secrets → + New client secret → 설명은 Aiyori, 만료는 12개월을 권장(최장 24개월) → Add → Value를 적어 둡니다(이 화면에서만 보입니다).
5. Token configuration → + Add optional claim → ID → email에 체크 → Add. Microsoft Graph의 email 권한을 켤지 물으면, 체크하고 추가합니다.
6. API permissions는 기본값인 User.Read 그대로 두어도 됩니다(Aiyori가 요청하는 것은 openid email profile뿐이며, 관리자 동의는 필요 없습니다).
7. Aiyori의 강사 화면 → “설정” → “회사의 ID 관리 시스템과 연결” → “SSO” 탭에 아래 표의 값을 입력하고 “저장” 버튼을 누릅니다.
8. Enterprise applications → Aiyori → Users and groups → + Add user/group에서 시험할 사람을 한 명 할당합니다.
9. 그 사람으로 Aiyori 로그인 화면 → “회사 계정으로 로그인” → 조직 코드 → Microsoft 로그인 → Aiyori로 돌아오면 연결된 것입니다. SCIM을 아직 연결하지 않았다면, 그 사람을 먼저 수강자로 등록해 두거나(회사 메일 주소를 입력), “아직 등록되지 않은 사람이 로그인하면 수강자로 등록하기” 항목을 켭니다.
10. 모두 들어올 수 있는 것을 확인한 뒤, 필요하면 “비밀번호 로그인을 끄고 회사 계정만 허용하기” 항목을 켭니다.

발급자 URL(Issuer)

https://login.microsoftonline.com/(테넌트 ID)/v2.0

클라이언트 ID

Application (client) ID

클라이언트 시크릿

4단계에서 적어 둔 Value(Secret ID가 아닙니다)

허용할 메일 주소 도메인

회사 메일 도메인(예: example.com). onmicrosoft.com 주소를 쓰는 사람도 들어오게 하려면 그것도 한 줄에 입력합니다. 토큰에 email이 없는 사람은 UPN의 도메인으로 확인하므로, UPN 도메인이 메일 도메인과 다르면 그것도 입력합니다.

시크릿이 만료되면 모두가 회사 계정으로 들어올 수 없게 됩니다. 만료 전에 새 시크릿을 만들어 Aiyori 화면에서 바꿔 넣어 주세요. IT 담당자의 일정에 넣어 두면 안심입니다.

발급자의 common·organizations·consumers와 끝에 /v2.0이 없는 형태는 저장할 때 이유와 함께 거절합니다(어느 테넌트의 사람이든 통과해 버리기 때문입니다). 테넌트 ID 대신 contoso.onmicrosoft.com 같은 테넌트 이름을 입력하면, 저장할 때 테넌트 ID 형태로 바꿉니다.

UPN과 메일 주소가 다른 회사라도 SCIM으로 넣은 사람은 UPN으로도 찾을 수 있으므로, 5단계의 email 추가가 없어도 동작합니다. SCIM을 쓰지 않고 명단 한꺼번에 등록이나 자동 등록으로 넣을 때는 5단계에서 email을 추가해 주세요(추가하지 않으면 UPN 주소로 다른 사람으로 등록됩니다).

3. SCIM(자동 프로비저닝)

1. Aiyori의 “회사의 ID 관리 시스템과 연결” → “SCIM” 탭에서 “키 이름” 칸에 Entra ID를 입력하고 “키 만들기” 버튼 → 나온 키를 적어 둡니다(이 화면에서만 보입니다).
2. Enterprise applications → Aiyori → Provisioning → + New configuration(예전 화면에서는 Get started → Provisioning Mode를 Automatic으로).
3. Admin Credentials에서 인증 방식은 Bearer authentication, Tenant URL에 https://app.aiyori.app/api/scim/v2, Secret Token에 1단계의 키를 입력합니다.
4. Test Connection → 성공하면 Create(또는 Save). Entra ID는 없는 사람을 한 명 찾아보고, 빈 목록이 돌아오는지 확인합니다.
5. Mappings는 기본값 그대로 두어도 됩니다(확인할 곳은 아래 표).
6. Settings에서 Scope는 Sync only assigned users and groups(기본값) 그대로 둡니다. 동기화가 멈췄을 때의 Notification Email에 IT 담당자의 주소를 입력하고, Prevent accidental deletion을 켭니다.
7. Users and groups에서 Aiyori에 넣을 그룹(부서·입사 연차 등)을 할당합니다.
8. Provision on demand로 한 사람만 보내, Aiyori의 수강자 목록에 나오는지 확인합니다.
9. Start provisioning. 첫 번째 동기화는 인원에 따라 시간이 걸리고, 그 뒤로는 약 40분마다 동기화합니다. 결과는 Provisioning logs에서 볼 수 있습니다.

4. 연결한 날 확인할 것

• 할당한 한 사람이 회사 계정으로 들어올 수 있습니다. 할당하지 않은 사람은 Microsoft 화면에서 막힙니다(할당이 필요하도록 해 두었기 때문입니다).
• Provision on demand로 보낸 사람이 Aiyori의 수강자로 나오고, 그룹에 들어 있습니다.
• 그 사람의 할당을 해제하고 다시 Provision on demand로 보내면, Aiyori에서 “회사 설정으로 정지 중” 상태가 되어 로그인할 수 없습니다. 되돌리면 들어올 수 있습니다.
• 시크릿의 만료일을 IT 담당자의 일정에 넣었습니다.

Entra ID 연동의 규칙

• 발급자는 테넌트마다 다릅니다. ID 토큰의 iss와 tid(테넌트 ID)가 둘 다 등록한 테넌트와 같아야 들어올 수 있습니다(다른 회사 테넌트의 사람은 통과하지 못합니다).
• Entra ID는 email_verified를 보내지 않습니다. Aiyori는 발급자·테넌트·허용할 도메인으로 좁힌 뒤, 받은 email(없으면 UPN)을 씁니다.
• SCIM PATCH의 "op": "Replace"(대문자로 시작. Add·Remove도), 문자열 "False", path가 없는 PATCH도 받아들입니다. 본문 형식은 application/scim+json입니다.
• 사람은 filter=userName eq(UPN. 대소문자를 구분하지 않습니다)로도, externalId로도 찾을 수 있습니다. 그룹 멤버의 추가·제거(members의 Add·Remove)도 받아들입니다.
• 동기화는 약 40분마다입니다. 급할 때는 Provision on demand로 보냅니다.
• SCIM 키에는 기한이 없습니다. 1년에 한 번 정도 새 키를 만들어 Entra ID에 다시 입력하고, Aiyori에서 옛 키의 “비활성화” 버튼을 누릅니다.
• Microsoft Entra SCIM Validator의 항목 중, 삭제한 사람을 GET하면 404가 되는 것 하나만은 맞추지 않았습니다. Aiyori는 삭제해도 기록을 지우지 않고 정지하기 때문입니다. 평소 동기화는 할당을 해제하면 active: false를 보내므로 지장이 없습니다.