cURL을 사용하여 ASP.NET Core 웹 API 호출

아티클
04/24/2024

이 문서에서는 cURL(클라이언트 URL)을 사용하여 보호된 ASP.NET Core 웹 API를 호출하는 방법을 보여 줍니다. cURL은 개발자가 서버와 데이터를 주고받는 데 사용하는 명령줄 도구입니다. 이 문서에서는 테넌트에 웹앱과 웹 API를 등록합니다. 웹앱은 Microsoft ID 플랫폼에서 생성된 액세스 토큰을 가져오는 데 사용됩니다. 다음으로, 토큰을 사용하여 cURL을 통해 웹 API에 대한 권한 부여된 호출을 수행합니다.

이 문서에서는 cURL(클라이언트 URL)을 사용하여 보호된 ASP.NET Core 웹 API를 호출하는 방법을 보여 줍니다. cURL은 개발자가 서버와 데이터를 주고받는 데 사용하는 명령줄 도구입니다. 보호된 API를 만든 자습서: API에 보호된 엔드포인트 구현에 이어 이제 액세스 토큰을 만들려면 Microsoft ID 플랫폼에 웹 애플리케이션을 등록해야 합니다. 다음으로, 토큰을 사용하여 cURL을 통해 API에 대한 권한 부여된 호출을 수행합니다.

필수 조건

활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
이 Azure 계정에는 애플리케이션을 관리할 수 있는 권한이 있어야 합니다. 다음 Microsoft Entra 역할에는 필수 권한이 포함되어 있습니다.
- 애플리케이션 관리자
- 애플리케이션 개발자
- 클라우드 애플리케이션 관리자
워크스테이션 컴퓨터에 cURL을 다운로드하고 설치합니다.
.NET 8.0 SDK의 최소 요구 사항입니다.

활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
이 Azure 계정에는 애플리케이션을 관리할 수 있는 권한이 있어야 합니다. 다음 Microsoft Entra 역할에는 필수 권한이 포함되어 있습니다.
- 애플리케이션 관리자
- 애플리케이션 개발자
- 클라우드 애플리케이션 관리자
자습서 시리즈 완료:
워크스테이션 컴퓨터에 cURL을 다운로드하고 설치합니다.

Microsoft ID 플랫폼에 애플리케이션 등록

Microsoft ID 플랫폼에서는 ID 및 액세스 관리 서비스를 제공하기 전에 애플리케이션을 등록해야 합니다. 애플리케이션 등록을 통해 애플리케이션의 이름과 형식, 로그인 대상 그룹을 지정할 수 있습니다. 로그인 대상 그룹은 지정된 애플리케이션에 로그인할 수 있는 사용자 계정 유형을 지정합니다.

웹 API 등록

팁

이 문서의 단계는 시작하는 포털에 따라 약간 다를 수 있습니다.

웹 API 등록을 만들려면 다음 단계를 따릅니다.

최소한 애플리케이션 개발자 자격으로 Microsoft Entra 관리 센터에 로그인합니다.
여러 테넌트에 액세스할 수 있는 경우 위쪽 메뉴의 설정 아이콘을 사용하여 디렉터리 + 구독 메뉴에서 애플리케이션을 등록하려는 테넌트로 전환합니다.
ID>애플리케이션>앱 등록으로 이동합니다.
새 등록을 선택합니다.
NewWebAPI1과 같은 애플리케이션의 이름을 입력합니다.
지원되는 계정 유형의 경우 이 조직 디렉터리 계정의 계정만을 선택합니다. 다양한 계정 유형에 대한 정보를 보려면 선택 도움말 옵션을 선택합니다.
등록을 선택합니다.
등록이 완료되면 애플리케이션의 개요 창이 표시됩니다. 애플리케이션 소스 코드에 사용할 디렉터리(테넌트) ID와 애플리케이션(클라이언트) ID를 기록해 둡니다.

참고 항목

지원되는 계정 유형은 애플리케이션에서 지원하는 계정 수정을 참조하여 변경할 수 있습니다.

API 표시

API가 등록되면 API가 클라이언트 애플리케이션에 노출하는 범위를 정의하여 해당 권한을 구성할 수 있습니다. 클라이언트 애플리케이션은 요청과 함께 액세스 토큰을 보호된 웹 API에 전달하여 작업을 수행할 수 있는 권한을 요청합니다. 그런 다음 웹 API는 수신한 액세스 토큰이 유효한 경우에만 요청된 작업을 수행합니다.

관리에서 API 노출 > 범위 추가를 선택합니다. 저장 후 계속을 선택하여 제안된 애플리케이션 ID URI(api://{clientId})를 수락합니다. {clientId}는 개요 페이지에서 기록된 값입니다. 그런 다음, 다음 정보를 입력합니다.
1. 범위 이름으로 Forecast.Read를 입력합니다.
2. 동의할 수 있는 사람에 대해 관리자 및 사용자 옵션을 선택했는지 확인합니다.
3. 관리자 동의 표시 이름 상자에 Read forecast data를 입력합니다.
4. 관리자 동의 설명 상자에 Allows the application to read weather forecast data를 입력합니다.
5. 사용자 동의 표시 이름 상자에 Read forecast data를 입력합니다.
6. 사용자 동의 설명 상자에 Allows the application to read weather forecast data를 입력합니다.
7. 상태가 사용으로 설정되어 있는지 확인합니다.
범위 추가를 선택합니다. 범위가 올바르게 입력되면 API 노출 창에 나열됩니다.

웹앱 등록

그러나 웹 API를 갖는 것만으로는 충분하지 않습니다. 만든 웹 API에 액세스하려면 액세스 토큰을 가져오려면 웹앱도 필요하기 때문입니다.

웹앱 등록을 만들려면 다음 단계를 수행합니다.

홈페이지로 돌아가려면 홈을 선택합니다. ID>애플리케이션>앱 등록으로 이동합니다.
새 등록을 선택합니다.
애플리케이션의 이름(예: web-app-calls-web-api)을 입력합니다.
지원되는 계정 유형의 경우 이 조직 디렉터리 계정의 계정만을 선택합니다. 다양한 계정 유형에 대한 정보를 보려면 선택 도움말 옵션을 선택합니다.
리디렉션 URI(선택 사항)에서 웹을 선택한 다음 URL 텍스트 상자에 http://localhost를 입력합니다.
등록을 선택합니다.

최소한 애플리케이션 개발자 자격으로 Microsoft Entra 관리 센터에 로그인합니다.
여러 테넌트에 액세스할 수 있는 경우 위쪽 메뉴의 설정 아이콘을 사용하여 디렉터리 + 구독 메뉴에서 애플리케이션을 등록하려는 테넌트로 전환합니다.
ID>애플리케이션>앱 등록으로 이동합니다.
새 등록을 선택합니다.
web-app-calls-web-api와 같은 애플리케이션 이름을 입력합니다.
지원되는 계정 유형의 경우 이 조직 디렉터리 계정의 계정만을 선택합니다. 다양한 계정 유형에 대한 정보를 보려면 선택 도움말 옵션을 선택합니다.
리디렉션 URI(선택 사항)에서 웹을 선택한 다음 URL 텍스트 상자에 http://localhost를 입력합니다.
등록을 선택합니다.

등록이 완료되면 개요 창에 앱 등록이 표시됩니다. 이후 단계에서 사용할 디렉터리(테넌트) ID와 애플리케이션(클라이언트) ID를 기록해 둡니다.

클라이언트 암호 추가

클라이언트 암호는 앱이 자신을 식별하는 데 사용할 수 있는 문자열 값이며 때로는 애플리케이션 비밀이라고도 합니다. 웹앱은 토큰을 요청할 때 클라이언트 암호를 사용하여 ID를 증명합니다.

클라이언트 암호를 구성하려면 다음 단계를 따릅니다.

개요 창의 관리에서 인증서 및 비밀>클라이언트 암호>새로 만들기를 선택합니다.
클라이언트 암호에 대한 설명을 추가합니다(예: 내 클라이언트 암호).
암호에 대해 만료를 선택하거나 사용자 지정 수명을 지정합니다.
- 클라이언트 암호의 수명은 2년(24개월) 이하로 제한됩니다. 사용자 지정 수명은 24개월 이상으로 지정할 수 없습니다.
- 12개월 미만의 만료 값을 설정하는 것이 좋습니다.
추가를 선택합니다.
클라이언트 암호의 값을 기록해 두세요. 이 비밀 값은 이 페이지에서 나가면 다시 표시되지 않습니다.

웹 API에 대한 액세스를 허용하는 애플리케이션 권한을 추가합니다.

웹앱 등록에서 웹 API 범위를 지정하면 웹앱은 Microsoft ID 플랫폼에서 제공하는 범위가 포함된 액세스 토큰을 가져올 수 있습니다. 그런 다음, 해당 코드 내에서 웹 API는 액세스 토큰에 있는 범위를 기준으로 리소스에 대한 권한 기반 액세스를 제공할 수 있습니다.

웹 API에 대한 웹앱 권한을 구성하려면 다음 단계를 따릅니다.

웹 애플리케이션(web-app-that-calls-web-api)의 개요 창에서 관리 아래에 있습니다. API 권한>권한 추가>조직에서 사용하는 API를 선택합니다.
NewWebAPI1 또는 권한을 추가하려는 API를 선택합니다.
권한 선택에서 Forecast.Read 옆의 확인란을 선택합니다. 권한 목록을 확장해야 할 수도 있습니다. 그러면 로그인한 사용자를 대신하여 클라이언트 앱이 가져야 하는 권한이 선택됩니다.
권한 추가를 선택하여 프로세스를 완료합니다.

권한이 API에 추가되면 구성된 권한 아래에 선택한 권한이 표시됩니다.

Microsoft Graph API에 대한 User.Read 권한도 확인할 수 있습니다. 이 권한은 앱 등록 시 자동으로 추가됩니다.

웹 API 테스트

ms-identity-docs-code-dotnet 리포지토리를 복제합니다.

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

ms-identity-docs-code-dotnet/web-api 폴더로 이동하여 ./appsettings.json 파일을 열고 {APPLICATION_CLIENT_ID} 및 {DIRECTORY_TENANT_ID}를 다음으로 바꿉니다.
- {APPLICATION_CLIENT_ID}는 앱의 개요 창 앱 등록에 있는 웹 API 애플리케이션(클라이언트) ID입니다.
- {DIRECTORY_TENANT_ID}는 앱의 개요 창 앱 등록에 있는 웹 API 디렉터리(테넌트) ID입니다.
다음 명령을 실행하여 앱을 시작합니다.
- .NET 6.0
- .NET 7.0
```
dotnet run
```
```
dotnet run --launch-profile https
```
다음과 유사한 출력이 표시됩니다. https://localhost:{port} URL에 포트 번호를 기록해 두세요.
```
... 
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

웹 API 테스트

자습서: ASP.NET Core 프로젝트 만들기 및 API 구성(예: NewWebAPILocal)에서 만들어진 웹 API로 이동하여 폴더를 엽니다.
새 터미널 창을 열고 웹 API 프로젝트가 있는 폴더로 이동합니다.

.NET 6.0
.NET 7.0

다음 명령을 실행하여 앱을 시작합니다.
```
dotnet run
```

다음과 유사한 출력이 표시됩니다. https://localhost:{port} URL에 포트 번호를 기록해 두세요.
```
... 
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

인증 코드 요청

인증 코드 흐름은 클라이언트가 사용자를 /authorize 엔드포인트로 보내는 것으로 시작됩니다. 이 요청에서 클라이언트는 사용자에게 Forecast.Read 권한을 요청합니다.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

URL을 복사하고 다음 매개 변수를 바꾼 후 브라우저에 붙여넣습니다.
- {tenant_id}는 웹앱 디렉터리(테넌트) ID입니다.
- {web-app-calls-web-api_application_client_id}는 웹앱(web-app-calls-web-api) 개요 창에 있는 애플리케이션(클라이언트) ID입니다.
- {web_API_application_client_id}는 웹 API(NewWebAPI1) 개요 창에 있는 애플리케이션(클라이언트) ID입니다.
앱이 등록된 Microsoft Entra 테넌트에 사용자로 로그인합니다. 필요한 경우 액세스 요청에 동의합니다.
사용자의 브라우저는 http://localhost/로 리디렉션됩니다. 브라우저의 탐색 모음을 참조하고 {authorization_code}를 복사하여 다음 단계에서 사용합니다. URL은 다음 코드 조각 형식을 따릅니다.
```
http://localhost/?code={authorization_code}
```

인증 코드와 cURL을 사용하여 액세스 토큰을 가져옵니다.

이제 cURL을 사용하여 Microsoft ID 플랫폼에서 액세스 토큰을 요청할 수 있습니다.

다음 코드 조각에서 cURL 명령을 복사합니다. 괄호 안의 값을 터미널에 대한 다음 매개 변수로 바꿉니다. 괄호를 제거해야 합니다.
- Bash
- Windows 명령 프롬프트
```
curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
-d 'client_id={web-app-calls-web-api_application_client_id}' \
-d 'api://{web_API_application_client_id}/Forecast.Read' \
-d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
-d 'redirect_uri=http://localhost' \
-d 'grant_type=authorization_code' \
-d 'client_secret={client_secret}'
```
```
curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token ^
 -d "client_id={web-app-calls-web-api_application_client_id}" ^
 -d "api://{web_API_application_client_id}/Forecast.Read" ^
 -d "code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}" ^
 -d "redirect_uri=http://localhost" ^
 -d "grant_type=authorization_code" ^
 -d "client_secret={client_secret}"
```
- {tenant_id}는 웹앱 디렉터리(테넌트) ID입니다.
- client_id={web-app-calls-web-api_application_client_id} 및 session_state={web-app-calls-web-api_application_client_id}는 웹 애플리케이션의(web-app-calls-web-api) 개요 창에 있는 애플리케이션(클라이언트) ID입니다.
- api://{web_API_application_client_id}/Forecast.Read는 웹 API(NewWebAPI1) 개요 창에 있는 애플리케이션(클라이언트) ID입니다.
- code={authorization_code}는 인증 코드 요청에서 받은 인증 코드입니다. 이를 통해 cURL 도구가 액세스 토큰을 요청할 수 있습니다.
- client_secret={client_secret}은 클라이언트 암호 추가에 기록된 클라이언트 암호 값입니다.

cURL 명령을 실행하고 올바르게 입력한 경우 다음 출력과 유사한 JSON 응답을 받아야 합니다.

{
   "token_type": "Bearer",
   "scope": "api://{web_API_application_client_id}/Forecast.Read",
   "expires_in": 3600,
   "ext_expires_in": 3600,
   "access_token": "{access_token}"
}

액세스 토큰으로 웹 API 호출

이전 cURL 명령을 실행하여 Microsoft ID 플랫폼이 액세스 토큰을 제공했습니다. 이제 획득한 토큰을 웹 API 호출을 위한 HTTP 요청의 전달자로 사용할 수 있습니다.

웹 API를 호출하려면 다음 cURL 명령을 복사하고 괄호 안의 다음 값을 바꾸고 터미널에 붙여넣습니다.
```
curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
```
- {access_token} 이전 섹션의 JSON 출력에서 기록된 액세스 토큰 값입니다.
- {port} 터미널에서 API를 실행할 때 기록된 웹 API의 포트 번호입니다. https 포트 번호인지 확인합니다.

요청에 유효한 액세스 토큰이 포함된 경우 예상되는 응답은 다음 출력과 유사한 출력과 함께 HTTP/2 200입니다.

HTTP/2 200
content-type: application/json; charset=utf-8
date: Day, DD Month YYYY HH:MM:SS
server: Kestrel
[{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]

다음 단계

OAuth 2.0 인증 코드 흐름 및 애플리케이션 형식에 대한 자세한 내용은 다음을 참조하세요.

다음을 통해 공유

cURL을 사용하여 ASP.NET Core 웹 API 호출

필수 조건

Microsoft ID 플랫폼에 애플리케이션 등록

웹 API 등록

API 표시

웹앱 등록

클라이언트 암호 추가

웹 API에 대한 액세스를 허용하는 애플리케이션 권한을 추가합니다.

웹 API 테스트

웹 API 테스트

인증 코드 요청

인증 코드와 cURL을 사용하여 액세스 토큰을 가져옵니다.

액세스 토큰으로 웹 API 호출

다음 단계

피드백

추가 리소스