샘플 Node.js 웹 애플리케이션에서 사용자 로그인 및 웹 API 호출

아티클
06/27/2024

이 가이드에서는 코드 샘플을 사용하여 Node.js 웹 애플리케이션에서 인증 및 권한 부여를 추가하는 방법을 보여줍니다. 샘플 애플리케이션은 사용자를 Node.js 웹앱에 로그인한 다음, .NET API를 호출합니다. 외부 테넌트 세부 정보를 사용하여 인증 및 권한 부여를 사용하도록 설정합니다. 샘플 웹 애플리케이션은 Node용 MSAL(Microsoft 인증 라이브러리)을 사용하여 인증을 처리합니다.

이 문서에서는 다음 작업을 완료합니다.

Microsoft Entra 관리 센터에서 웹 API를 등록하고 구성합니다.
외부 테넌트 세부 정보를 사용하려면 샘플 노드 웹 애플리케이션과 ASP.NET 웹 API를 업데이트합니다.
샘플 웹 애플리케이션 및 API를 실행하고 테스트합니다.

필수 조건

사용자 로그인의 단계를 완료하고 샘플 Node.js 웹 애플리케이션 문서에서 API를 호출합니다. 이 문서에서는 샘플 Node.js 웹앱을 사용하여 사용자를 로그인하는 방법을 보여줍니다.
Visual Studio Code 또는 다른 코드 편집기
Node.js
.NET 7.0 이상.
외부 테넌트입니다. 아직 없는 경우 평가판에 등록합니다.

웹 API 등록

이 단계에서는 웹 및 웹 API 애플리케이션 등록을 만들고 웹 API의 범위를 지정합니다.

웹 API 애플리케이션 등록

최소한 애플리케이션 개발자 자격으로 Microsoft Entra 관리 센터에 로그인합니다.
여러 테넌트에 액세스할 수 있는 경우 상단 메뉴의 설정 아이콘을 사용하여 디렉터리 + 구독 메뉴에서 외부 테넌트로 전환합니다.
ID>애플리케이션>앱 등록으로 이동합니다.
+ 새 등록을 선택합니다.
표시되는 애플리케이션 등록 페이지에서 애플리케이션의 등록 정보를 입력합니다.
1. 이름 섹션에 앱 사용자에게 표시될 의미 있는 애플리케이션 이름을 입력합니다(예: ciam-ToDoList-api).
2. 지원되는 계정 유형에서 이 조직 디렉터리의 계정만을 선택합니다.
등록을 선택하여 애플리케이션을 만듭니다.
등록이 완료되면 애플리케이션의 개요 창이 표시됩니다. 애플리케이션 소스 코드에 사용할 디렉터리(테넌트) ID와 애플리케이션(클라이언트) ID를 기록해 둡니다.

API 범위 구성

이 API는 클라이언트가 API 호출을 위해 획득해야 하는 권한을 노출해야 합니다.

API는 클라이언트 앱이 사용자에 대한 액세스 토큰을 성공적으로 가져오려면 위임된 권한이라고도 하는 최소 하나의 범위를 게시해야 합니다. 범위를 게시하려면 다음 단계를 수행합니다.

앱 등록 페이지에서 만든 API 애플리케이션(ciam-ToDoList-api)을 선택하여 개요 페이지를 엽니다.
관리에서 API 표시를 선택합니다.
페이지 위쪽의 애플리케이션 ID URI 옆에 있는 추가 링크를 선택하여 이 앱에 고유한 URI를 생성합니다.
api://{clientId}와 같은 제안된 애플리케이션 ID URI를 수락하고 저장을 선택합니다. 웹 애플리케이션은 웹 API에 대한 액세스 토큰을 요청할 때 API에 대해 정의된 각 범위의 접두사로 이 URI를 추가합니다.
이 API에서 정의한 범위에서 범위 추가를 선택합니다.

다음 값을 입력하여 API에 대한 읽기 권한을 정의하는 다음 값을 입력한 다음, 범위 추가를 선택하여 변경 내용을 저장합니다.

속성	값
범위 이름	ToDoList.Read
동의할 수 있는 사람	관리자 전용
관리자 동의 표시 이름	'TodoListApi'를 사용하여 사용자 ToDo 목록 읽기
관리자 동의 설명	앱이 'ToDoListApi'를 사용하여 사용자의 ToDo 목록을 읽을 수 있도록 허용합니다.
시	Enabled

범위 추가를 다시 선택하고 API에 대한 읽기 및 쓰기 권한 범위를 정의하는 다음 값을 입력합니다. 범위 추가를 선택하여 변경 내용을 저장합니다.

속성	값
범위 이름	ToDoList.ReadWrite
동의할 수 있는 사람	관리자 전용
관리자 동의 표시 이름	'TodoListApi'를 사용하여 사용자 ToDo 목록 읽기 및 쓰기
관리자 동의 설명	앱이 'ToDoListApi'를 사용하여 사용자의 ToDo 목록을 읽고 쓸 수 있도록 허용
시	Enabled

관리에서 매니페스트를 선택하여 API 매니페스트 편집기를 엽니다.
accessTokenAcceptedVersion 속성을 2로 설정합니다.
저장을 선택합니다.

웹 API에 대한 권한을 게시할 때 최소 권한 원칙에 대해 자세히 알아봅니다.

앱 역할 구성

클라이언트 앱이 자체적으로 액세스 토큰을 가져오려면 API는 애플리케이션에 대해 애플리케이션 권한이라고도 하는 앱 역할을 최소한 1개 이상 게시해야 합니다. 애플리케이션 권한은 클라이언트 애플리케이션이 자체적으로 성공적으로 인증하고 사용자가 로그인할 필요가 없도록 하려는 경우 API가 게시해야 하는 권한 형식입니다. 애플리케이션 권한을 게시하려면 다음 단계를 따릅니다.

앱 등록 페이지에서 만든 애플리케이션(예: ciam-ToDoList-api)을 선택하여 개요 페이지를 엽니다.
관리에서 앱 역할을 선택합니다.

앱 역할 만들기를 선택한 다음, 다음 값을 입력한 후 적용을 선택하여 변경 내용을 저장합니다.

속성	값
표시 이름	ToDoList.Read.All
허용된 멤버 유형	애플리케이션
값	ToDoList.Read.All
설명	앱이 'ToDoListApi'를 사용하여 모든 사용자의 ToDo 목록을 읽을 수 있도록 허용

다시 앱 역할 만들기를 선택한 다음, 두 번째 앱 역할에 대해 다음 값을 입력한 후 적용을 선택하여 변경 내용을 저장합니다.

속성	값
표시 이름	ToDoList.ReadWrite.All
허용된 멤버 유형	애플리케이션
값	ToDoList.ReadWrite.All
설명	앱이 'ToDoListApi'를 사용하여 모든 사용자의 할 일 목록을 읽고 쓸 수 있도록 허용

선택적 클레임 구성

웹 API에서 토큰이 앱 토큰인지 앱+사용자 토큰인지 확인하는 데 도움이 되도록 idtyp 선택적 클레임을 포함할 수 있습니다. scp와 roles 클레임의 조합을 동일한 용도로 사용할 수 있지만 idtyp 클레임을 사용하는 것이 앱 토큰과 앱+사용자 토큰을 구분하는 가장 쉬운 방법입니다. 예를 들어 토큰이 앱 전용 토큰인 경우 이 클레임의 값은 앱입니다.

선택적 클레임 구성 문서의 단계를 사용하여 액세스 토큰에 idtyp 클레임을 추가합니다.

토큰 형식으로 액세스를 선택합니다.
선택적 클레임 목록에서 idtyp를 선택합니다.

웹앱에 API 권한 부여

클라이언트 앱(ciam-client-app)에 API 권한을 부여하려면 다음 단계를 따르세요.

앱 등록 페이지에서 만든 애플리케이션(예: ciam-client-app)을 선택하여 개요 페이지를 엽니다.
관리 아래에서 API 권한을 선택합니다.
구성된 사용 권한 아래에서 권한 추가를 선택합니다.
내 조직에서 사용하는 API 탭을 선택합니다.
API 목록에서 ciam-ToDoList-api와 같은 API를 선택합니다.
위임된 권한 옵션을 선택합니다.
권한 목록에서 ToDoList.Read, ToDoList.ReadWrite을 선택합니다(필요한 경우 검색 상자 사용).
사용 권한 추가 단추를 선택합니다. 이제 권한이 올바르게 할당되었습니다. 그러나 테넌트는 고객의 테넌트이므로 소비자 사용자 자신은 이러한 권한에 동의할 수 없습니다. 이 문제를 해결하려면 관리자로서 테넌트의 모든 사용자를 대신하여 다음 권한에 동의해야 합니다.
1. <테넌트 이름>에 대한 관리자 동의 부여를 선택한 다음 예를 선택합니다.
2. 새로 고침을 선택한 다음 두 범위에 대해 <테넌트 이름>에 부여됨이 상태 아래에 표시되는지 확인합니다.
구성된 권한 목록에서 ToDoList.Read 및 ToDoList.ReadWrite 권한을 한 번에 하나씩 선택한 다음 나중에 사용할 수 있도록 권한의 전체 URI를 복사합니다. 전체 권한 URI는 api://{clientId}/{ToDoList.Read} 또는 api://{clientId}/{ToDoList.ReadWrite}와 유사합니다.

샘플 웹 애플리케이션 및 웹 API 복제 또는 다운로드

샘플 애플리케이션을 가져오려면 GitHub에서 복제하거나 .zip 파일로 다운로드할 수 있습니다.

샘플을 복제하려면 명령 프롬프트를 열고 프로젝트를 만들려는 위치로 이동한 후 다음 명령을 입력합니다.
```
git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
```
.zip 파일을 다운로드합니다. 이름 길이가 260자 미만인 파일 경로에 추출합니다.

프로젝트 종속성 설치

콘솔 창을 열고, Node.js/Express 샘플 앱이 있는 디렉터리로 변경합니다.
```
cd 2-Authorization\4-call-api-express\App
```
다음 명령을 실행하여 웹앱 종속성을 설치합니다.
```
npm install && npm update
```

샘플 웹앱 및 API 구성

클라이언트 웹앱 샘플에서 앱 등록을 사용하려면 다음 안내를 따릅니다.

코드 편집기에서 App\authConfig.js 파일을 엽니다.
자리 표시자 찾기:
- Enter_the_Application_Id_Here를 이전에 등록한 앱의 애플리케이션(클라이언트) ID로 바꿉니다.
- Enter_the_Tenant_Subdomain_Here를 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 이름이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
- Enter_the_Client_Secret_Here를 이전에 복사한 앱 비밀 값으로 바꿉니다.
- Enter_the_Web_Api_Application_Id_Here를 이전에 복사한 웹 API의 애플리케이션(클라이언트) ID로 바꿉니다.

웹 API 샘플에서 앱 등록을 사용하려면.

코드 편집기에서 API\ToDoListAPI\appsettings.json 파일을 엽니다.
자리 표시자를 찾습니다.
- Enter_the_Application_Id_Here를 복사한 웹 API의 애플리케이션(클라이언트) ID로 바꿉니다.
- Enter_the_Tenant_Id_Here를 이전에 복사한 디렉터리(테넌트) ID로 바꿉니다.
- Enter_the_Tenant_Subdomain_Here를 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 이름이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.

샘플 웹앱과 API 실행 및 테스트

콘솔 창을 열고 다음 명령을 사용하여 웹 API를 실행합니다.
```
cd 2-Authorization\4-call-api-express\API\ToDoListAPI
dotnet run
```
다음 명령을 사용하여 웹앱 클라이언트를 실행합니다.
```
cd 2-Authorization\4-call-api-express\App
npm start
```
브라우저를 연 다음 http://localhost:3000.으로 이동합니다.
로그인 단추를 선택합니다. 로그인하라는 메시지가 나타납니다.
로그인 페이지에서 이메일 주소를 입력하고, 다음을 선택하고, 암호를 입력한 다음, 로그인을 선택합니다. 계정이 없는 경우 등록 흐름을 시작하는 계정이 없으신가요? 만들기 링크를 선택합니다.
등록 옵션을 선택한 경우 이메일, 일회용 암호, 새 암호 및 기타 계정 세부 정보를 입력한 후 전체 등록 흐름을 완료합니다. 다음 스크린샷과 비슷한 페이지가 표시됩니다. 로그인 옵션을 선택하면 비슷한 페이지가 표시됩니다.

API 호출

API를 호출하려면 todolist 보기 링크를 선택합니다. 다음 스크린샷과 비슷한 페이지가 표시됩니다.
항목을 만들고 제거하여 to-do 목록을 조작합니다.

작동 방식

작업을 보거나 추가하거나 제거할 때마다 API 호출을 트리거합니다. API 호출을 트리거할 때마다 클라이언트 웹앱은 API 엔드포인트를 호출하는 데 필요한 권한(범위)을 사용하여 액세스 토큰을 획득합니다. 예를 들어 작업을 읽으려면 클라이언트 웹앱이 ToDoList.Read 권한/범위가 있는 액세스 토큰을 획득해야 합니다.

웹 API 엔드포인트는 클라이언트 앱에서 제공한 액세스 토큰의 권한이나 범위가 유효한지 확인해야 합니다. 액세스 토큰이 유효한 경우 엔드포인트는 HTTP 요청에 응답하고, 그렇지 않으면 401 Unauthorized HTTP 오류로 응답합니다.

다음을 통해 공유

필수 조건