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

아티클
12/27/2024

Azure DevOps Services

소유한 개인용 액세스 토큰(PAT) 대규모 집합을 처리하는 경우, UI를 사용해서만 이러한 토큰의 유지 관리를 수행하기가 복잡해질 수 있습니다.

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

이 문서에서는 Microsoft Entra 토큰 인증하고 PAT 수명 주기 API를 사용하여 호출하는 애플리케이션을 구성하는 방법을 보여 줍니다.

Important

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

필수 조건

다른 Azure DevOps Services API와 달리 사용자는 이 API를 사용하려면 Microsoft Entra 액세스 토큰 제공해야 합니다. 이 API의 PAT 생성 및 해지 기능을 고려할 때, 이러한 강력한 기능은 더 안전한 Microsoft Entra 토큰 에만 적용되도록 보장하고자 합니다.

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

활성 Azure 구독이 있는 Microsoft Entra 테넌트 사용
Microsoft Entra 테넌트에 애플리케이션 등록
애플리케이션에 Azure DevOps 권한 추가
테넌트 관리자의 동의 얻기: 테넌트의 보안 정책에 따라 애플리케이션에 조직의 리소스에 액세스할 수 있는 권한이 필요할 수 있습니다. 테넌트 관리자에게 테넌트 내에서 사용할 수 있는 권한을 앱에 부여하도록 요청합니다.

Important

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

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

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

다음 섹션에서는 Microsoft Entra 액세스 토큰으로 사용자를 인증하는 앱을 만드는 방법을 보여 줍니다. 앱은 Microsoft 인증 라이브러리(MSAL)을 사용하고 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 빠른 시작 앱을 사용하여 다음 예제를 안내합니다.

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

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

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

팁

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

다음 작업을 수행합니다.

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

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

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

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

주의

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

빠른 시작 애플리케이션을 다운로드하고 해당 종속성을 설치하고 사용자 환경에서 실행되는지 테스트한 후 원하는 편집기에서 파일을 엽니다 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일 후에 다시 로그인해야 할 수 있습니다.

FAQ(질문과 대답)

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

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

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

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

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

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

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

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

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

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

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

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

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

다음을 통해 공유

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

필수 조건

Python Flask 웹앱 복제

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

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

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

FAQ(질문과 대답)

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

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

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

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

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

피드백

추가 리소스