API 센터에서 API에 대한 액세스 권한 부여

API 센터에서 API에 대한 액세스 권한을 부여하도록 설정을 구성할 수 있습니다. 다음 설정은 다음과 같습니다.

• API 키 또는 OAuth 2.0 권한 부여를 사용하여 API 인증 사용
• 인벤토리의 특정 API 버전과 특정 인증 방법 연결
• 액세스 정책을 통해 지정된 사용자 또는 그룹의 API 버전에 대한 인증 관리
• 권한 있는 사용자가 API 센터 포털에서 직접 API를 테스트할 수 있도록 설정

비고

이 기능은 현재 미리 보기로 제공됩니다.

필수 조건

• Azure 구독의 API 센터입니다. 아직 API 센터를 만들지 않았다면 빠른 시작: API 센터 만들기를 참조하세요.

• API 센터에 하나 이상의 API를 등록합니다. 자세한 내용은 자습서: API 인벤토리에 API 등록을 참조하세요.

• API에 대한 환경 및 배포를 구성합니다. 자세한 내용은 자습서: API에 대한 환경 및 배포 추가를 참조하세요.

• API 센터 포털을 설정합니다. 자세한 내용은 API 센터 포털 설정을 참조하세요.

• API 키 또는 OAuth 2.0 클라이언트 비밀을 저장할 Azure 키 자격 증명 보관소입니다. 키 자격 증명 모음을 만드는 단계는 키 자격 증명 모음 만들기를 참조하십시오. 키 자격 증명 모음은 Azure의 역할 기반 액세스 제어(RBAC) 권한 모델을 사용해야 합니다.

• (Microsoft Entra ID를 사용한 OAuth 2.0 권한 부여의 경우) Azure 구독과 연결된 Microsoft Entra 테넌트에서 앱 등록을 만들 수 있는 권한입니다.

옵션 1: API 키 인증에 대한 설정 구성

API 키 인증을 지원하는 API의 경우 다음 단계에 따라 API 센터에서 설정을 구성합니다.

1. Azure Key Vault에 API 키 저장

API 키를 안전하게 관리하려면 Azure Key Vault에 저장하고 API 센터의 관리 ID를 사용하여 키 자격 증명 모음에 액세스합니다.

키 자격 증명 모음에 API 키를 비밀로 저장하려면 Key Vault에서 비밀 설정 및 검색을 참조하세요.

API 센터에서 관리 ID 사용

이 시나리오의 경우 API 센터는 관리 ID 를 사용하여 키 자격 증명 모음에 액세스합니다. 필요에 따라 시스템 할당 또는 하나 이상의 사용자 할당 관리 ID를 사용하도록 설정합니다.

다음 예제에서는 Azure Portal을 사용하여 시스템 할당 관리 ID를 사용하도록 설정하는 방법을 보여 줍니다. 높은 수준에서 구성 단계는 사용자 할당 관리 ID와 유사합니다.

1. 포털에서 API 센터로 이동합니다.
2. 왼쪽 메뉴의 보안 아래에서 관리 ID를 선택합니다.
3. 시스템 할당을 선택하고 상태를 켬으로 설정합니다.
4. 저장을 선택합니다.

관리 ID에 Key Vault 비밀 사용자 역할 할당

API 센터의 관리된 ID에 키 자격 모음에서 키 저장소 비밀 사용자 역할을 할당합니다. 다음 단계는 Azure Portal을 사용합니다.

1. 포털에서 키 자격 증명 모음으로 이동합니다.
2. 왼쪽 메뉴에서 액세스 제어(IAM)를 선택합니다.
3. + 역할 할당 추가를 선택합니다.
4. 역할 할당 추가 페이지에서 다음과 같이 값을 설정합니다.
   1. 역할 탭에서 Key Vault 비밀 사용자를 선택합니다.
   2. 구성원 탭의 액세스 권한 할당에서 관리 ID>+ 구성원 선택을 선택합니다.
   3. 관리 ID 선택 페이지에서 이전 섹션에서 추가한 API 센터의 시스템 할당 관리 ID를 선택합니다. 선택을 클릭합니다.
   4. 검토 + 할당을 다시 선택합니다.

2. API 센터에서 API 키 구성 추가

1. 포털에서 API 센터로 이동합니다.

2. 왼쪽 메뉴의 거버넌스 아래에서 권한 부여(미리 보기)>+ 구성 추가를 선택합니다.

3. 구성 추가 페이지에서 다음과 같이 값을 설정합니다.

   설정	설명
   타이틀	권한 부여의 이름을 입력합니다.
   설명	필요에 따라 권한 부여에 대한 설명을 입력합니다.
   보안 체계	API 키를 선택합니다.
   API 키 위치	키가 API 요청에 표시되는 방법을 선택합니다. 사용 가능한 값은 헤더 (요청 헤더) 및 쿼리 (쿼리 매개 변수)입니다.
   API 키 매개 변수 이름	API 키를 포함하는 HTTP 헤더 또는 쿼리 매개 변수의 이름을 입력합니다. 예: x-api-key
   API 키 키 볼트 비밀 참조	선택을 클릭하고 저장한 구독, 키 자격 증명 모음 및 비밀을 선택합니다. 예: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>

4. 선택하고생성합니다.

옵션 2: OAuth 2.0 권한 부여에 대한 설정 구성

OAuth 2.0 권한 부여를 지원하는 API의 경우 다음 단계에 따라 API 센터에서 인증 설정을 구성합니다. 다음 OAuth 2.0 권한 부여 흐름 중 하나 또는 둘 다에 대한 설정을 구성할 수 있습니다.

• PKCE를 사용한 권한 부여 코드 흐름(코드 교환용 증명 키) - 이 흐름은 API 센터 포털과 같이 브라우저에서 사용자를 인증하는 데 권장됩니다.
• 클라이언트 자격 증명 흐름 - 이 흐름은 데이터에 액세스하기 위해 특정 사용자의 권한이 필요하지 않은 애플리케이션에 권장됩니다.

1. OAuth 2.0 앱 만들기

OAuth 2.0 권한 부여의 경우 Azure 구독과 연결된 Microsoft Entra 테넌트 같은 ID 공급자에 앱 등록을 만듭니다. 정확한 생성 단계는 사용하는 ID 공급자에 따라 달라집니다.

다음 예제에서는 Microsoft Entra ID에서 앱 등록을 만드는 방법을 보여줍니다.

1. 테넌트에 충분한 권한이 있는 계정으로 Azure Portal 에 로그인합니다.
2. Microsoft Entra ID>+ 새 등록으로 이동합니다.
3. 애플리케이션 등록 페이지에서 애플리케이션 등록 설정을 입력합니다.
   1. 이름에 앱의 의미 있는 이름을 입력합니다.
   2. 지원되는 계정 유형에서 시나리오에 적합한 옵션(예: 이 조직 디렉터리의 계정만 해당)을 선택합니다(단일 테넌트).
   3. (권한 부여 코드 흐름의 경우) 리디렉션 URI에서 SPA(단일 페이지 애플리케이션) 를 선택하고 URI를 설정합니다. API 센터 포털 배포의 URI를 다음 형식으로 입력하세요: https://<service-name>.portal.<location>.azure-api-center.ms.<service name>을 API 센터의 이름으로, <location>을 배포된 위치로 바꾸세요. 예: https://myapicenter.portal.eastus.azure-api-center.ms
   4. 등록을 선택합니다.
4. 왼쪽 메뉴의 관리 아래에서 인증서 및 비밀을 선택한 다음 + 새 클라이언트 비밀을 선택합니다.
   1. 설명입력합니다.
   2. 만료 옵션을 선택합니다.
   3. 추가를 선택합니다.
   4. 페이지를 떠나기 전에 클라이언트 암호의 값을 복사합니다. 다음 섹션에서 필요합니다.
5. 필요에 따라 앱 등록에 API 범위를 추가합니다. 자세한 내용은 웹 API를 노출하도록 애플리케이션 구성을 참조하세요.

API 센터에서 OAuth 2.0 권한 부여를 구성하는 경우 앱 등록에서 다음 값이 필요합니다.

• 앱 등록 개요 페이지의 애플리케이션(클라이언트) ID 및 이전에 복사한 클라이언트 암호입니다.
• 앱 등록 개요> 엔드포인트 페이지의 다음엔드포인트 URL:
  • OAuth2.0 권한 부여 엔드포인트(v2) - Microsoft Entra ID에 대한 권한 부여 엔드포인트
  • OAuth 2.0 토큰 엔드포인트(v2) - Microsoft Entra ID의 토큰 엔드포인트 및 토큰 갱신 엔드포인트
• 앱 등록에 구성된 모든 API 범위입니다.

2. Azure Key Vault에 클라이언트 비밀 저장

비밀을 안전하게 관리하려면 Azure Key Vault에 저장하고 API 센터의 관리 ID를 사용하여 키 자격 증명 모음에 액세스합니다.

키 자격 증명 모음에 API 키를 비밀로 저장하려면 Key Vault에서 비밀 설정 및 검색을 참조하세요.

API 센터에서 관리 ID 사용

이 시나리오의 경우 API 센터는 관리 ID 를 사용하여 키 자격 증명 모음에 액세스합니다. 필요에 따라 시스템 할당 또는 하나 이상의 사용자 할당 관리 ID를 사용하도록 설정합니다.

다음 예제에서는 Azure Portal을 사용하여 시스템 할당 관리 ID를 사용하도록 설정하는 방법을 보여 줍니다. 높은 수준에서 구성 단계는 사용자 할당 관리 ID와 유사합니다.

1. 포털에서 API 센터로 이동합니다.
2. 왼쪽 메뉴의 보안 아래에서 관리 ID를 선택합니다.
3. 시스템 할당을 선택하고 상태를 켬으로 설정합니다.
4. 저장을 선택합니다.

관리 ID에 Key Vault 비밀 사용자 역할 할당

API 센터의 관리된 ID에 키 자격 모음에서 키 저장소 비밀 사용자 역할을 할당합니다. 다음 단계는 Azure Portal을 사용합니다.

1. 포털에서 키 자격 증명 모음으로 이동합니다.
2. 왼쪽 메뉴에서 액세스 제어(IAM)를 선택합니다.
3. + 역할 할당 추가를 선택합니다.
4. 역할 할당 추가 페이지에서 다음과 같이 값을 설정합니다.
   1. 역할 탭에서 Key Vault 비밀 사용자를 선택합니다.
   2. 구성원 탭의 액세스 권한 할당에서 관리 ID>+ 구성원 선택을 선택합니다.
   3. 관리 ID 선택 페이지에서 이전 섹션에서 추가한 API 센터의 시스템 할당 관리 ID를 선택합니다. 선택을 클릭합니다.
   4. 검토 + 할당을 다시 선택합니다.

3. API 센터에서 OAuth 2.0 권한 부여 추가

1. 포털에서 API 센터로 이동합니다.

2. 왼쪽 메뉴의 거버넌스 아래에서 권한 부여(미리 보기)>+ 구성 추가를 선택합니다.

3. 구성 추가 페이지에서 다음과 같이 값을 설정합니다.

   

   비고

   이전에 ID 공급자에서 만든 앱 등록에 따라 설정을 구성합니다. Microsoft Entra ID를 사용하는 경우 앱 등록 개요 페이지에서 클라이언트 ID를 찾고 개요>엔드포인트 페이지에서 URL 엔드포인트를 찾습니다.

   설정	설명
   타이틀	권한 부여의 이름을 입력합니다.
   설명	필요에 따라 권한 부여에 대한 설명을 입력합니다.
   보안 체계	OAuth2를 선택합니다.
   클라이언트 ID	ID 공급자에서 만든 앱의 클라이언트 ID(GUID)를 입력합니다.
   클라이언트 암호	선택을 클릭하고 저장한 구독, 키 자격 증명 모음 및 클라이언트 비밀을 선택합니다. 예: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>
   권한 부여 URL	ID 공급자에 대한 OAuth 2.0 권한 부여 엔드포인트를 입력합니다. Microsoft Entra ID의 예: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
   토큰 URL	ID 공급자에 대한 OAuth 2.0 토큰 엔드포인트를 입력합니다. Microsoft Entra ID의 예: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   URL 새로 고침	ID 공급자에 대한 OAuth 2.0 토큰 새로 고침 엔드포인트를 입력합니다. 대부분의 공급자의 경우 토큰 URL과 동일합니다. Microsoft Entra ID의 예: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   OAuth2 프로세스	사용하려는 OAuth 2.0 흐름 중 하나 또는 둘 다를 선택합니다. 사용 가능한 값은 PKCE(권한 부여 코드) 및 클라이언트 자격 증명입니다.
   범위	API에 대해 구성된 하나 이상의 API 범위를 공백으로 구분하여 입력합니다. 범위가 구성되지 않은 경우 .를 입력합니다 .default.

4. 만들기를 선택하여 구성을 저장합니다.

API 버전에 인증 구성 추가

API 키 또는 OAuth 2.0 흐름에 대한 설정을 구성한 후 API 센터의 API 버전에 API 키 또는 OAuth 2.0 구성을 추가합니다.

1. 포털에서 API 센터로 이동합니다.
2. 왼쪽 메뉴의 자산에서 API를 선택합니다.
3. 권한 부여 구성을 연결할 API를 선택합니다.
4. 왼쪽 메뉴의 세부 정보에서 버전을 선택합니다.
5. 인증 구성을 추가할 API 버전을 선택합니다.
6. 왼쪽 메뉴의 세부 정보에서 액세스 관리(미리 보기)>+ 인증 추가를 선택합니다.
7. 인증 추가 페이지에서 연결할 사용 가능한 인증 구성을 선택합니다.
8. 선택하고생성합니다.

비고

API 버전에 여러 인증 구성을 추가할 수 있습니다. 예를 들어 API에서 지원하는 경우 API 키와 OAuth 2.0 구성을 모두 동일한 API 버전에 추가할 수 있습니다. 마찬가지로 여러 API 버전에 동일한 구성을 추가할 수 있습니다.

특정 사용자 또는 그룹의 액세스 관리

조직의 특정 사용자 또는 그룹이 API 버전의 인증 구성에 대한 액세스를 관리할 수 있습니다. 이렇게 하려면 API 버전의 특정 인증 구성으로 범위가 지정된 API 센터 자격 증명 액세스 읽기 권한자 역할을 사용자 또는 그룹에 할당하는 액세스 정책을 구성합니다. 예를 들어 특정 사용자만 API 키 또는 OAuth 2.0 흐름을 사용하여 API 센터 포털에서 API를 테스트하도록 허용하려는 경우에 유용합니다.

1. 포털에서 API 센터로 이동합니다.

2. 인증 구성을 추가한 API 버전으로 이동합니다(이전 섹션 참조).

3. 왼쪽 메뉴의 세부 정보에서 액세스 관리(미리 보기)를 선택합니다.

4. 관리하려는 액세스 권한이 있는 인증 구성의 행 끝에 있는 액세스 정책 편집 드롭다운을 선택합니다.

5. 액세스 관리 페이지에서 + 사용자 추가 > 또는 그룹 추가>를 선택합니다.

6. 추가하려는 사용자(또는 그룹)를 검색하여 선택합니다. 여러 항목을 선택할 수 있습니다.

7. 선택을 클릭합니다.

팁 (조언)

액세스 정책에서 사용자 또는 그룹을 제거할 수도 있습니다. 액세스 관리 페이지에서 사용자 또는 그룹의 상황에 맞는(...) 메뉴에서 삭제를 선택합니다.

API 센터 포털에서 API 테스트

API 센터 포털을 사용하여 인증 및 사용자 액세스를 위해 구성한 API를 테스트할 수 있습니다.

팁 (조언)

API 센터 포털에서 특정 사용자가 특정 API를 테스트할 수 있도록 설정하는 것 외에도 API에 대한 표시 유형 설정을 구성할 수 있습니다. 포털의 표시 유형 설정은 로그인한 모든 사용자에게 표시되는 API를 제어합니다.

1. 포털에서 API 센터로 이동합니다.

2. 왼쪽 메뉴의 API 센터 포털에서 포털 설정을 선택합니다.

3. API 센터 포털 보기를 선택합니다.

4. API 센터 포털에서 테스트할 API를 선택합니다.

5. 인증 방법이 구성된 API 버전을 선택합니다.

6. 옵션에서 설명서 보기를 선택합니다.

7. API에서 연산을 선택하고 이 API를 사용해보세요.

8. 열리는 창에서 인증 설정을 검토합니다. API에 액세스할 수 있는 경우 보내기 를 선택하여 API를 시도합니다.

9. 작업이 성공하면 응답 코드와 응답 본문이 표시됩니다 200 OK . 작업이 실패하면 오류 메시지가 표시됩니다.

관련 콘텐츠

• API 센터 포털 설정
• Visual Studio Code에서 Azure API Center 포털 보기 사용
• Azure API Management의 API에 대한 인증 및 권한 부여