자습서: Node.js 디먼 애플리케이션에 권한을 부여하도록 외부 테넌트 준비
이 자습서 시리즈에서는 Node.js 디먼 클라이언트 앱을 빌드하고 Microsoft Entra 관리 센터에서 인증을 준비하는 방법을 보여 줍니다. OAuth(Open Authorization) 2.0 클라이언트 자격 증명 부여 흐름을 사용한 다음 웹 API를 호출하기 위한 액세스 토큰을 획득하도록 구성합니다.
이 자습서에서는 다음을 수행합니다.
- Microsoft Entra 관리 센터에서 웹 API를 등록하고 해당 식별자를 기록합니다.
- 웹 API에 대한 앱 역할 구성
- 클라이언트 디먼 애플리케이션 등록
- 디먼 앱에 권한 부여
- 디먼 앱에 대한 클라이언트 암호 만들기
Microsoft Entra 관리 센터에서 클라이언트 디먼 애플리케이션 및 웹 API를 이미 등록한 경우 이 자습서의 단계를 건너뛰고 API를 호출하기 위한 액세스 토큰 획득을 진행할 수 있습니다.
필수 조건
- 외부 테넌트입니다. 아직 없는 경우 평가판에 등록합니다.
웹 API 애플리케이션 등록
최소한 애플리케이션 개발자 자격으로 Microsoft Entra 관리 센터에 로그인합니다.
여러 테넌트에 액세스할 수 있는 경우 위쪽 메뉴의 설정 아이콘
을 사용하여 디렉터리 + 구독 메뉴에서 외부 테넌트로 전환합니다.ID>애플리케이션>앱 등록으로 이동합니다.
+ 새 등록을 선택합니다.
표시되는 애플리케이션 등록 페이지에서 애플리케이션의 등록 정보를 입력합니다.
이름 섹션에 앱 사용자에게 표시될 의미 있는 애플리케이션 이름을 입력합니다(예: ciam-ToDoList-api).
지원되는 계정 유형에서 이 조직 디렉터리의 계정만을 선택합니다.
등록을 선택하여 애플리케이션을 만듭니다.
등록이 완료되면 애플리케이션의 개요 창이 표시됩니다. 애플리케이션 소스 코드에 사용할 디렉터리(테넌트) ID와 애플리케이션(클라이언트) ID를 기록해 둡니다.
앱 역할 구성
클라이언트 앱이 자체적으로 액세스 토큰을 가져오려면 API는 애플리케이션에 대해 애플리케이션 권한이라고도 하는 앱 역할을 최소한 1개 이상 게시해야 합니다. 애플리케이션 권한은 클라이언트 애플리케이션이 자체적으로 성공적으로 인증하고 사용자가 로그인할 필요가 없도록 하려는 경우 API가 게시해야 하는 권한 형식입니다. 애플리케이션 권한을 게시하려면 다음 단계를 따릅니다.
앱 등록 페이지에서 만든 애플리케이션(예: ciam-ToDoList-api)을 선택하여 개요 페이지를 엽니다.
관리에서 앱 역할을 선택합니다.
앱 역할 만들기를 선택한 다음, 다음 값을 입력한 후 적용을 선택하여 변경 내용을 저장합니다.
속성 값 표시 이름 ToDoList.Read.All 허용된 멤버 유형 애플리케이션 값 ToDoList.Read.All 설명 앱이 'ToDoListApi'를 사용하여 모든 사용자의 ToDo 목록을 읽을 수 있도록 허용 다시 앱 역할 만들기를 선택한 다음, 두 번째 앱 역할에 대해 다음 값을 입력한 후 적용을 선택하여 변경 내용을 저장합니다.
속성 값 표시 이름 ToDoList.ReadWrite.All 허용된 멤버 유형 애플리케이션 값 ToDoList.ReadWrite.All 설명 앱이 'ToDoListApi'를 사용하여 모든 사용자의 ToDo 목록을 읽고 쓸 수 있도록 허용
idtyp 토큰 클레임 구성
Microsoft ID에서 반환된 토큰은 요청하는 클라이언트의 최적의 성능을 보장하기 위해 더 작게 유지됩니다. 따라서, 일부 클레임이 토큰에 더 이상 기본적으로 존재하지 않으며, 애플리케이션 기준으로 특수하게 요청되어야 합니다. 이 앱의 경우 웹 API에서 토큰이 앱 토큰인지 앱+사용자 토큰인지 확인하는 데 도움이 되는 idtyp 선택적 클레임을 포함합니다. 동일한 용도로 scp 및 역할 클레임의 조합을 사용할 수 있지만 idtyp 클레임을 사용하는 것이 앱 토큰과 앱+사용자 토큰을 구분하는 가장 쉬운 방법입니다. 예를 들어 토큰이 앱 전용 토큰인 경우 이 클레임의 값은 앱입니다.
다음 단계를 사용하여 idtyp 선택적 클레임을 구성합니다.
ciam-client-app과 같은 선택적 클레임을 구성하려는 앱 등록 페이지에서 개요 페이지를 엽니다.
관리에서 토큰 구성을 선택합니다.
선택적 클레임 추가를 선택합니다.
토큰 형식에서 액세스를 선택합니다.
선택적 클레임 idtyp를 선택합니다.
추가를 선택하여 변경 내용을 저장합니다.
디먼 앱 등록
애플리케이션에서 Microsoft Entra를 사용하여 사용자를 로그인할 수 있도록 하려면 Microsoft Entra 외부 ID 만든 애플리케이션을 인식해야 합니다. 앱 등록은 앱과 Microsoft Entra 간의 신뢰 관계를 설정합니다. 애플리케이션을 등록하면 외부 ID는 인증 요청을 만들 때 앱을 식별하는 데 사용되는 값인 애플리케이션(클라이언트) ID라는 고유 식별자를 만듭니다.
다음 단계에서는 Microsoft Entra 관리 센터에 앱을 등록하는 방법을 보여 줍니다.
최소한 애플리케이션 개발자 자격으로 Microsoft Entra 관리 센터에 로그인합니다.
여러 테넌트에 액세스할 수 있는 경우 위쪽 메뉴의 설정 아이콘
을 사용하여 디렉터리 + 구독 메뉴에서 외부 테넌트로 전환합니다.ID>애플리케이션>앱 등록으로 이동합니다.
+ 새 등록을 선택합니다.
애플리케이션 등록 페이지가 표시됩니다.
- 앱 사용자에게 표시될 의미 있는 애플리케이션 이름을 입력합니다(예: ciam-client-app).
- 지원되는 계정 유형에서 이 조직 디렉터리의 계정만을 선택합니다.
등록을 선택합니다.
성공적으로 등록되면 애플리케이션의 개요 창이 표시됩니다. 애플리케이션 소스 코드에 사용할 애플리케이션(클라이언트) ID를 기록해 둡니다.
클라이언트 암호 만들기
등록된 애플리케이션에 대한 클라이언트 암호를 만듭니다. 애플리케이션은 토큰을 요청할 때 클라이언트 암호를 사용하여 ID를 증명합니다.
- 앱 등록 페이지에서 만든 애플리케이션(예: ciam-client-app)을 선택하여 개요 페이지를 엽니다.
- 관리에서 인증서 및 비밀을 선택합니다.
- 새 클라이언트 비밀을 선택합니다.
- 설명 상자에 클라이언트 암호에 대한 설명을 입력합니다(예: ciam 앱 클라이언트 암호).
- 만료에서 조직의 보안 규칙에 따라 비밀이 유효한 기간을 선택한 다음 추가를 선택합니다.
- 비밀의 값을 기록합니다. 이후 단계에서 구성에 이 값을 사용합니다. 인증서 및 비밀에서 벗어나면 비밀 값이 다시 표시되지 않으며 어떤 수단으로도 검색할 수 없습니다. 기록해야 합니다.
디먼 앱에 API 권한 부여
앱 등록 페이지에서 만든 애플리케이션을 선택합니다(예: ciam-client-app).
관리 아래에서 API 권한을 선택합니다.
구성된 사용 권한 아래에서 권한 추가를 선택합니다.
내 조직에서 사용하는 API 탭을 선택합니다.
API 목록에서 ciam-ToDoList-api와 같은 API를 선택합니다.
애플리케이션 권한 옵션을 선택합니다. 사용자가 아닌 앱이 자체적으로 로그인하므로 이 옵션을 선택합니다.
권한 목록에서 TodoList.Read.All, ToDoList.ReadWrite.All을 선택합니다(필요한 경우 검색 상자 사용).
사용 권한 추가 단추를 선택합니다.
이제 권한이 올바르게 할당되었습니다. 그러나 디먼 앱은 사용자가 앱과 상호 작용하는 것을 허용하지 않기 때문에 사용자 자신은 이러한 권한에 동의할 수 없습니다. 이 문제를 해결하려면 관리자로서 테넌트의 모든 사용자를 대신하여 다음 권한에 동의해야 합니다.
- <테넌트 이름>에 대한 관리자 동의 부여를 선택한 다음 예를 선택합니다.
- 새로 고침을 선택한 다음 두 권한에 대해 <테넌트 이름>에 부여됨이 상태 아래에 표시되는지 확인합니다.
앱 등록 세부 정보 수집
다음 단계에서는 디먼 앱 애플리케이션을 준비합니다. 다음 세부 정보를 확인해야 합니다.
- 등록한 클라이언트 디먼 앱의 애플리케이션(클라이언트) ID.
- 디먼 앱을 등록한 디렉터리(테넌트) 하위 도메인입니다. 테넌트 이름이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
- 만든 디먼 앱의 애플리케이션 비밀 값입니다.
- 등록한 웹 API 앱의 애플리케이션(클라이언트) ID입니다.