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

API 센터에서 API에 대한 액세스 권한을 부여하도록 설정을 구성합니다. 이러한 설정:

  • API 키, OAuth 2.0 권한 부여 또는 다른 HTTP 보안 체계를 사용하여 API 인증 및 권한 부여 사용
  • 인벤토리의 API 버전과 인증 구성 연결
  • 액세스 정책을 통해 지정된 사용자 또는 그룹의 API 버전에 대한 액세스 관리
  • 권한 있는 사용자가 API 센터 포털에서 API를 테스트할 수 있도록 설정

비고

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

필수 조건

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

  • API 센터에 등록된 API가 하나 이상 있습니다. 자습서: API 인벤토리에 API 등록을 참조하세요.

  • API에 대해 구성된 환경 및 배포입니다. 자습서: API에 대한 환경 및 배포 추가를 참조하세요.

  • API 센터 포털이 설정되었습니다. API 센터 포털 설정을 참조하세요.

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

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

옵션 1: API 키 인증 구성

API 키 인증을 지원하는 API의 경우 다음 단계를 완료합니다.

1. Azure Key Vault에 API 키 저장

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

API 센터의 관리 ID를 사용하여 키 자격 증명 모음에 액세스합니다.

API Center에서 관리 ID 사용하도록 설정

이 시나리오의 경우 API 센터는 관리 ID를 사용하여 Azure 리소스에 액세스합니다. 사용자의 요구 사항에 따라 시스템에서 할당한 관리 ID나 사용자가 할당한 하나 이상의 관리 ID를 사용하도록 설정합니다.

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

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

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

자산 가져오기를 허용하려면 API 센터의 관리 ID에 Azure Key Vault의 Key Vault 비밀 사용자 역할을 할당합니다. 포털 또는 Azure CLI를 사용할 수 있습니다.

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

2. API 키 구성 추가

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

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

  3. 구성 추가 페이지에서 다음 값을 설정합니다. 포털에서 API 키를 구성하는 스크린샷.

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

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

이 구성을 완료한 후 API 버전에 인증 구성 추가 섹션으로 이동하여 API 키 구성을 API 버전과 연결합니다.

옵션 2: OAuth 2.0 권한 부여 구성

OAuth 2.0 권한 부여를 지원하는 API의 경우 다음 단계를 완료합니다. 다음 흐름 중 하나 또는 둘 다를 구성할 수 있습니다.

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

1. OAuth 2.0 앱 만들기

구독과 연결된 Microsoft Entra 테넌트 같은 ID 공급자에서 앱 등록을 만듭니다. 단계는 ID 공급자에 따라 달라집니다.

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

  1. 테넌트에서 충분한 권한으로 Azure Portal 에 로그인합니다.
  2. Microsoft Entra ID>+ 새 등록으로 이동합니다.
  3. 애플리케이션 등록 페이지에서 다음을 수행합니다.
    1. 이름에 의미 있는 이름을 입력합니다.
    2. 지원되는 계정 유형에서 적절한 옵션(예: 이 조직 디렉터리의 계정만)을 선택합니다(단일 테넌트).
    3. (권한 부여 코드 흐름의 경우) 리디렉션 URI에서 SPA(단일 페이지 애플리케이션) 를 선택하고 API 센터 포털 https://<service-name>.portal.<location>.azure-api-center.ms의 URI를 입력합니다. <service-name>와 <location>를 API 센터 이름 및 배포 위치로 교체하세요. 예: 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)
    • OAuth 2.0 토큰 엔드포인트(v2)( 토큰 새로 고침 엔드포인트로도 사용됨)
  • 구성한 모든 API 범위입니다.

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

키 자격 증명 모음에 클라이언트 비밀을 저장하려면 Key Vault에서 비밀 설정 및 검색을 참조하세요.

API 센터의 관리 ID를 사용하여 키 자격 증명 모음에 액세스합니다.

API Center에서 관리 ID 사용하도록 설정

이 시나리오의 경우 API 센터는 관리 ID를 사용하여 Azure 리소스에 액세스합니다. 사용자의 요구 사항에 따라 시스템에서 할당한 관리 ID나 사용자가 할당한 하나 이상의 관리 ID를 사용하도록 설정합니다.

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

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

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

자산 가져오기를 허용하려면 API 센터의 관리 ID에 Azure Key Vault의 Key Vault 비밀 사용자 역할을 할당합니다. 포털 또는 Azure CLI를 사용할 수 있습니다.

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

3. OAuth 2.0 구성 추가

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

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

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

    포털에서 OAuth 2.0을 구성하는 스크린샷

    비고

    이전에 만든 앱 등록의 값을 사용합니다. 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 버전에 인증 구성 추가 섹션으로 이동하여 OAuth 2.0 구성을 API 버전과 연결합니다.

옵션 3: 다른 HTTP 보안 체계에 대한 설정 구성

OAuth 2.0을 사용하지 않는 기본 인증 또는 전달자 토큰과 같은 다른 HTTP 보안 체계를 사용하는 API의 경우 다음 단계를 완료합니다. 레거시 API에 대해 이 옵션을 선택해야 할 수도 있습니다.

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

  1. 거버넌스에서 권한 부여(미리 보기)>+ 구성 추가를 선택합니다.

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

    설정 설명
    타이틀 권한 부여의 이름을 입력합니다.
    설명 필요에 따라 권한 부여에 대한 설명을 입력합니다.
    보안 체계 HTTP를 선택합니다.
    인증 체계 API에서 사용하는 인증 체계를 선택합니다. 다음 표의 체계를 예로 들어 있습니다.
    인증 체계 설명
    기본 username:password를 Base64로 인코딩된 문자열로 Authorization: Basic <credentials> 헤더에 보냅니다.
    베어러 헤더의 Authorization: Bearer <token>에서 OAuth 2.0 액세스 토큰 이외의 토큰을 보냅니다.
    요약 서버가 nonce를 보내는 챌린지-응답 메커니즘 클라이언트는 자격 증명 + nonce의 해시로 응답합니다.
    사용자 지정 공급업체별 스키마와 같은 다른 메커니즘 체계입니다.

이 구성을 완료한 후 다음 섹션으로 이동하여 구성을 API 버전과 연결합니다.

API 버전에 인증 구성 추가

인증 체계를 구성한 후 구성을 API 버전과 연결합니다.

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

  2. 인벤토리에서 자산을 선택합니다.

  3. 구성을 연결할 API를 선택합니다.

  4. 세부 정보에서 버전을 선택한 다음, 대상 API 버전을 선택합니다.

  5. API 버전의 상황에 맞는 메뉴에서 액세스 관리(미리 보기)를 선택합니다. 포털에서 API 버전과 인증 구성을 연결한 스크린샷

  6. 액세스 관리 페이지에서 + 인증 추가를 선택합니다.

  7. 사용 가능한 인증 구성을 선택합니다.

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

비고

API에서 지원하는 경우 API 버전(예: API 키 및 OAuth 2.0 모두)에 여러 인증 구성을 추가할 수 있습니다. 여러 API 버전에 동일한 구성을 추가할 수도 있습니다.

특정 사용자 또는 그룹에 대한 액세스 관리

API 버전의 특정 인증 구성으로 범위가 지정된 API 센터 자격 증명 액세스 읽기 권한자 역할을 사용자 또는 그룹에 할당하는 액세스 정책을 구성합니다. 이 역할을 사용하면 지정된 사용자만 API 센터 포털에서 API를 테스트할 수 있습니다.

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

  2. 인증 구성을 사용하여 API 버전으로 이동합니다.

  3. 액세스 관리(미리 보기)를 선택합니다.

  4. 관리하려는 인증 구성을 선택합니다.

  5. 드롭다운 메뉴에서 액세스 정책 편집을 선택합니다. 포털에서 액세스 정책을 추가하는 스크린샷

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

  7. 사용자 또는 그룹을 검색하고 선택합니다. 여러 항목을 선택할 수 있습니다.

  8. 선택하세요

팁 (조언)

사용자 또는 그룹을 제거하려면 액세스 관리 페이지의 상황에 맞는 메뉴에서 삭제를 선택합니다.

API 센터 포털에서 API 테스트

인증 및 사용자 액세스를 위해 구성한 API를 테스트합니다.

팁 (조언)

포털에서 로그인한 모든 사용자에 대해 표시되는 API를 제어하도록 표시 유형 설정을 구성할 수도 있습니다.

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

  2. API 센터 포털에서 포털 설정>보기 API 센터 포털을 선택합니다.

  3. API를 선택한 다음, 인증 방법이 구성된 버전을 선택합니다.

  4. 옵션에서 설명서 보기를 선택합니다. API 센터 포털의 API 세부 정보 스크린샷

  5. 작업을 선택한 다음, 이 API를 사용해보기를 선택합니다.

  6. 인증 설정을 검토합니다. 액세스 권한이 있는 경우 보내기를 선택합니다. API 센터 포털의 테스트 콘솔에서 API를 테스트하는 스크린샷

  7. 성공한 작업은 응답 코드 및 응답 본문을 반환 200 OK 합니다. 실패한 작업은 오류 메시지를 반환합니다.

관련 콘텐츠

  • Last updated on