REST API를 사용하여 PAT(개인용 액세스 토큰) 관리

아티클
10/24/2024

Azure DevOps Services

소유한 많은 PAT(개인용 액세스 토큰) 집합을 처리하는 경우 UI만 사용하여 이러한 토큰의 유지 관리를 관리하는 것이 복잡해질 수 있습니다.

PAT 수명 주기 관리 API를 사용하면 자동화된 프로세스를 사용하여 조직과 연결된 PAT를 쉽게 관리할 수 있습니다. 이 풍부한 API 집합을 사용하면 새 PAT를 만들고 기존 PAT를 갱신하거나 만료할 수 있도록 PAT를 관리할 수 있습니다.

이 문서에서는 Microsoft Entra 토큰으로 인증하고 PAT 수명 주기 API를 사용하여 호출하는 애플리케이션을 구성하는 방법을 보여 줍니다. 사용 가능한 엔드포인트의 전체 목록을 보려면 여기에서 API 참조를 확인합니다.

필수 조건

사용 권한: 테넌트의 보안 정책에 따라 애플리케이션에 조직의 리소스에 액세스할 수 있는 권한이 필요할 수 있습니다. 현재 이 테넌트에서 이 앱을 계속 사용할 수 있는 유일한 방법은 관리자에게 앱에 대한 사용 권한을 부여하도록 요청하는 것입니다.

인증:
- API를 사용하려면 Microsoft Entra ID OAuth를 통해 Microsoft Entra 토큰으로 인증합니다. 자세한 내용은 인증 섹션을 참조하세요.
- 활성 Azure 구독이 있는 Microsoft Entra 테넌트를 만듭니다.

참고 항목

서비스 주체 또는 관리 ID를 사용하여 PAT를 만들거나 해지할 수 없습니다.

Microsoft Entra 토큰으로 인증

다른 Azure DevOps Services API와 달리 사용자는 PAT 대신 이 API를 사용하기 위해 Microsoft Entra 액세스 토큰을 제공해야 합니다. Microsoft Entra 토큰은 PAT를 사용하는 것보다 더 안전한 인증 메커니즘입니다. 이 API의 PAT 생성 및 해지 기능을 고려할 때 허용되는 사용자에게만 이러한 강력한 기능이 제공되도록 하고 싶습니다.

Microsoft Entra 액세스 토큰을 획득하고 새로 고치려면 다음 작업을 수행합니다.

Important

"On-behalf-of application" 솔루션(예: "클라이언트 자격 증명" 흐름) 및 Microsoft Entra 액세스 토큰을 발급하지 않는 인증 흐름은 이 API에서 사용할 수 없습니다. Microsoft Entra 테넌트에서 다단계 인증을 사용하는 경우 반드시 "권한 부여 코드" 흐름을 사용해야 합니다.

Microsoft Entra 토큰을 처리하기 위한 인증 흐름이 작동하는 애플리케이션이 있으면 이러한 토큰을 사용하여 PAT 수명 주기 관리 API를 호출할 수 있습니다.

API를 직접 호출하려면 요청 헤더에 Authorization Microsoft Entra 액세스 토큰을 Bearer 토큰으로 제공합니다. 자세한 내용과 사용 가능한 요청의 전체 목록은 PAT API 참조를 참조하세요.

다음 섹션에서는 Microsoft Entra 액세스 토큰으로 사용자를 인증하는 앱을 만드는 방법을 보여 줍니다. 앱은 MSAL(Microsoft 인증 라이브러리) 라이브러리를 사용하고 PAT 수명 주기 관리 API를 호출합니다.

MSAL에는 Microsoft Entra 토큰을 획득하고 새로 고치는 데 앱 내에서 사용할 수 있는 여러 호환 인증 흐름이 포함되어 있습니다. MSAL 흐름의 전체 목록은 Microsoft 인증 라이브러리 인증 흐름 설명서에서 찾을 수 있습니다. 애플리케이션에 적합한 인증 방법을 선택하는 가이드는 Azure DevOps에 적합한 인증 방법 선택에서 찾을 수 있습니다.

시작하려면 다음 예제 중 하나를 참조하세요.

샘플 Python Flask 앱을 복제하고 테넌트 및 ADO 조직으로 구성
선택한 언어에 대한 샘플 애플리케이션을 Azure Portal 에서 생성하고 PAT 수명 주기 관리 API에 맞게 구성합니다.

Python Flask 웹앱 복제

GitHub에서 다운로드하고 Microsoft Entra 테넌트 및 Azure DevOps 조직에서 사용하도록 구성할 수 있는 이 API에 대한 샘플 Python Flask 웹 애플리케이션을 제공했습니다. 샘플 애플리케이션은 MSAL 인증 코드 흐름을 사용하여 Microsoft Entra 액세스 토큰을 획득합니다.

Important

GitHub에서 샘플 Python Flask 웹 애플리케이션을 시작하는 것이 좋지만 다른 언어 또는 애플리케이션 유형을 사용하려는 경우 빠른 시작 옵션을 사용하여 동등한 테스트 애플리케이션을 다시 만듭니다.

샘플 앱을 복제한 후 리포지토리의 추가 정보 지침에 따릅니다. README는 Microsoft Entra 테넌트에 애플리케이션을 등록하고, Microsoft Entra 테넌트를 사용하도록 샘플을 구성하고, 복제된 앱을 실행하는 방법을 설명합니다.

빠른 시작 Azure Portal 애플리케이션 생성

대신 Azure Portal의 애플리케이션 페이지에서 빠른 시작 옵션을 사용하여 생성된 MSAL 코드로 샘플 앱을 생성할 수 있습니다. 빠른 시작 테스트 애플리케이션은 권한 부여 코드 흐름을 따르지만 Microsoft Graph API 엔드포인트에서 수행합니다. 사용자는 PAT 수명 주기 관리 API의 엔드포인트를 가리키도록 애플리케이션의 구성을 업데이트해야 합니다.

이 방법을 따르려면 Microsoft Entra ID 개발 문서 홈페이지에서 선택한 애플리케이션 유형에 대한 빠른 시작 지침을 따릅니다. Python Flask 빠른 시작 앱을 사용하여 다음 예제를 안내합니다.

예: Python Flask 빠른 시작 애플리케이션 시작

활성 Azure 구독이 있는 Microsoft Entra 테넌트에 애플리케이션을 등록한 후 Azure Portal의 Microsoft Entra ID ->App Registrations에서 등록된 애플리케이션으로 이동합니다.
애플리케이션을 선택하고 API 권한으로 이동합니다.
권한 추가를 선택하고 Azure DevOps를> 선택합니다. user_impersonation 확인 -> 권한 추가를 선택합니다.
빠른 시작을 선택합니다.
애플리케이션 유형을 선택합니다. Python Flask의 경우 웹 애플리케이션을 선택합니다.
애플리케이션 플랫폼을 선택합니다. 이 자습서에서는 Python을 선택합니다.
필요한 필수 구성 요소를 충족하는지 확인한 다음, Azure Portal에서 애플리케이션을 구성하는 데 필요한 변경을 수행할 수 있도록 합니다. 회신 URL은 애플리케이션 생성 시 설정된 리디렉션 URL + "/getAToken"입니다.
빠른 시작 애플리케이션을 다운로드하고 파일을 추출합니다.
애플리케이션 요구 사항을 설치하고 애플리케이션을 실행하여 필요한 모든 종속성이 있는지 확인합니다. 애플리케이션은 처음에 Microsoft Graph API의 엔드포인트에 도달하도록 구성됩니다. 다음 섹션의 구성 지침에 따라 이 엔드포인트를 PAT 수명 주기 관리 API 기본 엔드포인트로 변경하는 방법을 알아봅니다.

빠른 시작 애플리케이션 구성

사용자가 빠른 시작 애플리케이션을 다운로드하고 설치하면 Microsoft Graph에서 테스트 API 엔드포인트를 사용하도록 구성됩니다. 생성된 구성 파일을 대신 PAT 수명 주기 관리 API를 호출하도록 수정합니다.

팁

이러한 문서에서는 컬렉션과 조직을 서로 교환하여 사용합니다. 구성 변수에 컬렉션 이름이 필요한 경우 조직 이름으로 바꾸세요.

다음 작업을 수행합니다.

PAT 수명 주기 관리 API에 https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview 대한 ENDPOINT 구성 변수 업데이트
SCOPE 구성 변수를 "499b84ac-1321-427f-aa17-267ca6975798/.default"로 업데이트하여 Azure DevOps 리소스 및 모든 범위를 참조합니다.

다음 예제에서는 이전 섹션의 Azure Portal을 통해 생성한 빠른 시작 Python Flask 애플리케이션에 대해 이 구성을 어떻게 수행했는지 보여 줍니다.

애플리케이션 구성 파일에 처음에 일반 텍스트로 삽입되는 클라이언트 암호를 보호하려면 지침을 따라야 합니다. 구성 파일에서 일반 텍스트 변수를 제거하고 환경 변수 또는 Azure KeyVault를 사용하여 애플리케이션의 비밀을 보호하는 것이 가장 좋습니다.

대신 클라이언트 암호 대신 인증서를 사용하도록 선택할 수 있습니다. 애플리케이션이 프로덕션에서 사용되는 경우 인증서를 사용하는 것이 좋습니다. 인증서 사용에 대한 지침은 빠른 시작 애플리케이션 설정의 마지막 단계에서 찾을 수 있습니다.

주의

일반 텍스트 클라이언트 비밀을 프로덕션 애플리케이션 코드에 두지 마세요.

예: PAT 수명 주기 관리 API에 대한 Python Flask 빠른 시작 애플리케이션 구성

빠른 시작 애플리케이션을 다운로드하고 해당 종속성을 설치하고 사용자 환경에서 실행되는지 테스트한 후 원하는 편집기에서 파일을 엽니다 app_config.py . 파일은 다음 코드 조각과 유사해야 합니다. 명확성을 위해 기본 Microsoft Graph API 구성을 참조하는 주석이 제거되었습니다.

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret,
# like Azure Key Vault. Or, use an environment variable as described in Flask's documentation:
# https://flask.palletsprojects.com/en/1.1.x/config/#configuring-from-environment-variables
# CLIENT_SECRET = os.getenv("CLIENT_SECRET")
# if not CLIENT_SECRET:
#     raise ValueError("Need to define CLIENT_SECRET environment variable")

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  

SCOPE = ["User.ReadBasic.All"]

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

앱 등록의 클라이언트 ID 및 클라이언트 암호를 사용하여 클라이언트 ID 또는 클라이언트 비밀을 애플리케이션으로 업데이트합니다. 프로덕션 환경에서 환경 변수, Azure KeyVault를 사용하거나 인증서로 전환하여 클라이언트 비밀을 보호해야 합니다.
```
CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret.
```

변수를 ENDPOINT Azure DevOps 컬렉션 URL 및 API 엔드포인트로 변경합니다. 예를 들어 "testCollection"이라는 컬렉션의 경우 값은 다음과 같습니다.

# Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here

ENDPOINT = 'https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview'

"testCollection"이라는 컬렉션의 경우 이 엔드포인트는 다음과 같습니다.

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview'

SCOPE Azure DevOps API 리소스를 참조하도록 변수를 변경합니다. 문자열은 Azure DevOps API의 리소스 ID이며 .default 범위는 해당 리소스 ID에 대한 모든 범위를 참조합니다.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
애플리케이션이 다중 테넌트 구성이 아닌 특정 테넌트에 대해 구성된 경우 변수에 대한 AUTHORITY 대체 값을 사용하여 "Enter_the_Tenant_Name_Here"에 특정 테넌트 이름을 추가합니다.
```
# For single-tenant app:
AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"

# For multi-tenant app:
AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"
```

최종 app_config.py 파일이 CLIENT_ID, 테넌트 ID 및 컬렉션 URL과 일치하는지 확인합니다. 보안상의 이유로 CLIENT_SECRET 환경 변수, Azure KeyVault로 이동되었거나 등록된 애플리케이션에 대한 인증서와 교환되었는지 확인합니다.

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

# Note that the CLIENT_SECRET has been removed and moved to an environment variable or Azure KeyVault

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set in the app's registration in the Azure portal.

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' 
# Used to configure user's collection URL and the desired API endpoint

SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
# Means "All scopes for the Azure DevOps API resource"

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

애플리케이션을 다시 실행하여 요청하는 사용자에 대한 모든 PAT 토큰을 가져올 수 있는지 테스트합니다. 확인되면 나머지 PAT 수명 주기 관리 API 엔드포인트에 대한 요청 전송을 지원하도록 디렉터리와 콘텐츠의 내용을 'app.py' 'ms-identity-python-webapp-master\templates' 수정할 수 있습니다. 모든 PAT 수명 주기 관리 API 엔드포인트 에 대한 요청을 지원하도록 수정된 Python Flask 빠른 시작 애플리케이션의 예제는 GitHub에서 이 샘플 리포지토리를 참조하세요.

Microsoft Entra 액세스 토큰 자동 새로 고침

애플리케이션이 올바르게 구성되고 사용자가 액세스 토큰을 획득하면 토큰을 최대 1시간 동안 사용할 수 있습니다. 이전 두 예제에 제공된 MSAL 코드는 만료되면 토큰을 자동으로 새로 고칩니다. 토큰을 새로 고침하면 사용자가 다시 로그인하고 새 권한 부여 코드를 획득할 필요가 없습니다. 그러나 사용자는 새로 고침 토큰이 만료된 후 90일 후에 다시 로그인해야 할 수 있습니다.

PAT 수명 주기 관리 API 살펴보기

이전 GitHub 샘플 애플리케이션 및 빠른 시작 애플리케이션에서 애플리케이션은 사용자가 획득한 Microsoft Entra 토큰을 사용하여 요청하도록 미리 구성됩니다. 자세한 내용은 API 참조 문서를 참조하세요.

FAQ(질문과 대답)

Q: Microsoft Entra 토큰으로 인증해야 하는 이유는 무엇인가요? PAT가 충분하지 않은 이유는 무엇인가요?

A: 이 PAT 수명 주기 관리 API를 사용하여 새 PAT를 만들고 기존 PAT를 해지하는 기능을 열었습니다. 악의적인 행위자가 이 API를 사용하여 조직의 Azure DevOps 리소스에 여러 진입점을 만들 수 있습니다. Microsoft Entra 인증을 적용하여 이 권한 없는 사용에 대해 이 강력한 API를 보다 안전하게 보호할 수 있기를 바랍니다.

Q: 이 API를 사용하려면 활성 Azure 구독이 있는 Microsoft Entra 테넌트가 있어야 하나요?

A: 아쉽게도 이 API는 활성 Azure 구독을 사용하는 Microsoft Entra 테넌트에 속한 사용자만 사용할 수 있습니다.

Q: 다른 언어/프레임워크/애플리케이션 유형에 대한 이 샘플 애플리케이션의 예를 얻을 수 있나요?

A: 선택한 언어로 API를 사용하려고 합니다. 예제에 대한 요청이 있는 경우 개발자 커뮤니티로 이동하여 다른 사용자가 공유할 예제가 있는지 확인합니다. 더 큰 Azure DevOps 대상 그룹에 공유하려는 샘플 애플리케이션이 있는 경우 알려 주세요 . 이러한 문서에서 더 광범위하게 배포하는 방법을 살펴볼 수 있습니다.

Q: 이 토큰 API와 토큰 관리자 API의 차이점은 무엇인가요?

A: 이 토큰 API 및 토큰 관리자 API는 비슷하지만 다양한 사용 사례 및 대상 그룹을 제공합니다.

이 토큰 API는 주로 자동화된 파이프라인에서 소유한 PAT를 관리하려는 사용자를 위한 것입니다. 이 API는 허용합니다. 새 토큰을 만들고 기존 토큰을 업데이트할 수 있습니다.
토큰 관리자 API는 조직 관리자를 위한 것입니다. 관리자는 이 API를 사용하여 조직의 사용자에 대한 개인용 액세스 토큰(PAT) 및 자체 설명 세션 토큰을 포함하여 OAuth 권한 부여를 검색하고 해지할 수 있습니다.

Q: API를 통해 PAT를 다시 생성/회전하려면 어떻게 해야 하나요? UI에서 해당 옵션을 보았지만 API에 유사한 메서드가 표시되지 않습니다.

A: 좋은 질문! UI에서 사용할 수 있는 '다시 생성' 기능은 실제로 API를 통해 완전히 복제할 수 있는 몇 가지 작업을 수행합니다.

PAT를 회전하려면 다음 단계를 수행합니다.

GET 호출을 사용하여 PAT의 메타데이터를 이해합니다.
POST 호출을 사용하여 이전 PAT의 메타데이터를 사용하여 새 PAT를 만듭니다.
DELETE 호출을 사용하여 이전 PAT 해지

Q: 이 앱을 계속 사용하려고 할 때 "관리자 승인 필요" 팝업이 표시됩니다. 관리자 승인 없이 이 앱을 사용하려면 어떻게 해야 하나요?

A: 테넌트에는 조직의 리소스에 액세스할 수 있는 권한을 애플리케이션에 부여해야 하는 보안 정책이 있는 것 같습니다. 현재 이 테넌트에서 이 앱을 계속 사용할 수 있는 유일한 방법은 관리자에게 사용 권한을 부여하도록 요청하는 것입니다.

Q: 서비스 주체 또는 관리 ID를 사용하여 PAT 수명 주기 관리 API를 호출하려고 할 때 "서비스 주체가 이 작업을 수행할 수 없습니다"와 같은 오류가 표시되는 이유는 무엇인가요?

A: 서비스 주체 및 관리 ID는 허용되지 않습니다. 이 API의 PAT 생성 및 해지 기능을 고려할 때 허용되는 사용자에게만 이러한 강력한 기능이 제공되도록 하고 싶습니다.

다음 단계

PAT 수명 주기 관리 API 엔드포인트에 대해 알아보기

다음을 통해 공유