외부 ID 공급자를 신뢰하도록 앱 구성

이 문서에서는 Microsoft Entra ID의 애플리케이션에서 페더레이션 ID 자격 증명을 관리하는 방법을 설명합니다. 페더레이션 ID 자격 증명은 애플리케이션과 외부 IdP(ID 공급자) 간의 트러스트 관계를 만듭니다.

그런 다음 외부 소프트웨어 워크로드를 구성하여 외부 IdP의 토큰을 Microsoft ID 플랫폼의 액세스 토큰으로 교환할 수 있습니다. 외부 워크로드는 비밀을 관리할 필요 없이(지원되는 시나리오에서) Microsoft Entra 보호 리소스에 액세스할 수 있습니다. 토큰 교환 워크플로에 대한 자세한 내용은 워크로드 ID 페더레이션을 읽어보세요.

이 문서에서는 Microsoft Entra ID의 애플리케이션에서 페더레이션 ID 자격 증명을 만들고, 나열 및 삭제하는 방법을 알아봅니다.

중요 고려 사항 및 제한 사항

페더레이션 ID 자격 증명을 만들기, 업데이트 또는 삭제하려면 작업을 수행하는 계정에는 애플리케이션 관리자, 애플리케이션 개발자, 클라우드 애플리케이션 관리자 또는 애플리케이션 소유자 역할이 있어야 합니다. 페더레이션 ID 자격 증명을 업데이트하려면 microsoft.directory/applications/credentials/update 권한이 필요합니다.

최대 20개의 페더레이션 ID 자격 증명을 애플리케이션 또는 사용자가 할당한 관리 ID에 추가할 수 있습니다.

페더레이션 ID 자격 증명을 구성할 때는 몇 가지 중요한 정보를 제공해야 합니다.

• 발급자와 주체는 신뢰 관계를 설정하는 데 필요한 주요 정보입니다. issuer 및 subject의 조합은 앱에서 고유해야 합니다. 외부 소프트웨어 워크로드가 외부 토큰을 액세스 토큰으로 교환하도록 Microsoft ID 플랫폼에 요청하면 페더레이션 ID 자격 증명의 발급자 및 주체 값이 외부 토큰에 제공된 issuer 및 subject 클레임에 대해 검사됩니다. 유효성 검사를 통과하면 Microsoft ID 플랫폼에서는 외부 소프트웨어 워크로드에 액세스 토큰을 발급합니다.

• 발급자는 외부 ID 공급자의 URL이며 교환되는 외부 토큰의 issuer 클레임과 일치해야 합니다. 필수입니다. issuer 클레임 값에 선행 또는 후행 공백이 있으면 토큰 교환이 차단됩니다. 이 필드는 문자 수가 600자로 제한됩니다.

• 주체는 외부 소프트웨어 워크로드의 식별자이며 교환되는 외부 토큰의 sub(subject) 클레임과 일치해야 합니다. 주체는 고정된 형식이 없으며(각 IdP는 고유한 형식 사용), 경우에 따라 GUID, 콜론으로 구분된 식별자, 경우에 따라 임의의 문자열을 사용합니다. 이 필드는 문자 수가 600자로 제한됩니다.

  Important

  주체 설정 값은 GitHub 워크플로 구성의 구성과 정확히 일치해야 합니다. 그렇지 않으면 Microsoft ID 플랫폼에서 들어오는 외부 토큰을 보고 액세스 토큰에 대한 교환을 거부합니다. 오류가 발생하지 않고 교환이 오류 없이 실패합니다.

  Important

  주체 설정에 잘못된 외부 워크로드 정보를 실수로 추가하면 페더레이션 ID 자격 증명이 오류 없이 성공적으로 만들어집니다. 토큰 교환이 실패할 때까지 오류가 명확해지지 않습니다.

• 대상은 외부 토큰에 표시할 수 있는 대상을 나열합니다. 필수입니다. 600자로 제한되는 단일 대상 그룹 값을 추가해야 합니다. 권장 값은 "api://AzureADTokenExchange"입니다. 들어오는 토큰의 aud 클레임에서 수락해야 하는 Microsoft ID 플랫폼을 나타냅니다.

• 이름은 페더레이션 ID 자격 증명의 고유 식별자입니다. 필수입니다. 이 필드는 문자 수 3~120자로 제한되고 URL 친화적이어야 합니다. 영숫자, 대시 또는 밑줄 문자가 지원되며 첫 번째 문자는 영숫자만 사용해야 합니다.  만든 후에는 변경이 불가능합니다.

• 설명은 페더레이션 ID 자격 증명에 대한 사용자 제공 설명입니다. 선택 사항. 설명은 Microsoft Entra ID로 유효성 검사되거나 확인되지 않습니다. 이 필드는 600자로 제한됩니다.

와일드카드 문자는 페더레이션 ID 자격 증명 속성 값에서 지원되지 않습니다.

지원되는 지역, 페더레이션 자격 증명 업데이트 전파 시간, 지원되는 발급자 등에 대해 자세히 알아보려면 페더레이션 ID 자격 증명에 대한 중요한 고려 사항 및 제한 사항을 참조하세요.

필수 조건

Microsoft Entra ID로 앱 등록을 만듭니다. 외부 소프트웨어 워크로드가 대상으로 하는 Azure 리소스에 대한 액세스 권한을 앱에 부여합니다.

다음 단계에서 필요한 앱의 개체 ID(애플리케이션(클라이언트) ID 아님)를 찾습니다. Microsoft Entra 관리 센터에서 앱의 개체 ID를 찾을 수 있습니다. 등록된 애플리케이션 목록에서 앱 등록을 선택합니다. 개요->기본 정보에서 개체 ID를 찾습니다.

다음 단계에서 필요한 외부 IdP 및 소프트웨어 워크로드에 대해 주체 및 발급자 정보를 가져옵니다.

앱에서 페더레이션 ID 자격 증명 구성

GitHub Actions

GitHub Actions에 대한 페더레이션 ID를 추가하려면 다음 단계를 수행합니다.

1. Microsoft Entra 관리 센터의 앱 등록 환경에서 앱 등록을 찾습니다. 왼쪽 탐색 창에서 인증서 및 비밀을 선택하고 페더레이션된 자격 증명 탭을 선택한 다음 자격 증명 추가를 선택합니다.

2. 페더레이션 자격 증명 시나리오 드롭다운 상자에서 Azure 리소스를 배포하는 GitHub 작업을 선택합니다.

3. GitHub Actions 워크플로에 대한 조직 및 리포지토리를 지정합니다.

4. 엔터티 형식의 경우 환경, 분기, 끌어오기 요청 또는 태그를 선택하고 값을 지정합니다. 값은 GitHub 워크플로의 구성과 정확히 일치해야 합니다. 분기 및 태그에는 패턴 일치가 지원되지 않습니다. 온-푸시 워크플로가 여러 분기 또는 태그에 대해 실행되는 경우 환경을 지정합니다. 자세한 내용은 예제를 참조하세요.

5. 페더레이션된 자격 증명의 이름을 추가합니다.

6. 발급자, 대상 그룹 및 주체 식별자 필드는 입력한 값에 따라 자동으로 입력됩니다.

7. 추가를 선택하여 페더레이션된 자격 증명을 구성합니다.

   

GitHub 워크플로에 대한 Microsoft Entra 애플리케이션 등록에서 다음 값을 사용합니다.

• AZURE_CLIENT_ID애플리케이션(클라이언트) ID

• AZURE_TENANT_ID디렉터리(테넌트) ID

  다음 스크린샷은 애플리케이션 ID 및 테넌트 ID를 복사하는 방법을 보여 줍니다.

  

• AZURE_SUBSCRIPTION_ID 구독 ID. 구독 ID를 가져오려면 Azure Portal에서 구독을 열고 구독을 찾습니다. 그런 다음, 구독 ID를 복사합니다.

엔터티 형식 예제

분기 예제

기본 분기의 푸시 또는 풀 요청 이벤트에 의해 트리거되는 워크플로의 경우:

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

분기의 엔터티 형식과 "기본"의 GitHub 분기 이름을 지정합니다.

환경 예제

"프로덕션"이라는 환경에 연결된 작업의 경우:

on:
  push:
    branches:
      - main

jobs:
  deployment:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: deploy
        # ...deployment-specific steps

환경의 엔터티 유형과 "프로덕션"의 GitHub 환경 이름을 지정합니다.

태그 예제

예를 들어 "v2"라는 태그에 푸시하여 트리거되는 워크플로의 경우:

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:
      - v2
      - v1.*

태그의 엔터티 형식과 "v2"의 GitHub 태그 이름을 지정합니다.

풀 요청 예제

풀 요청 이벤트로 트리거되는 워크플로의 경우 풀 요청의 엔터티 형식을 지정합니다.

Kubernetes

Microsoft Entra 관리 센터의 앱 등록 환경에서 앱 등록을 찾습니다. 왼쪽 탐색 창에서 인증서 및 비밀을 선택하고 페더레이션된 자격 증명 탭을 선택한 다음 자격 증명 추가를 선택합니다.

드롭다운 메뉴에서 Azure 리소스에 액세스하는 Kubernetes 시나리오를 선택합니다.

클러스터 발급자 URL, 네임스페이스, 서비스 계정 이름 및 이름 필드를 입력합니다.

• 클러스터 발급자 URL은 관리형 클러스터의 OIDC 발급자 URL 또는 자체 관리형 클러스터의 OIDC 발급자 URL입니다.
• 서비스 계정 이름은 Pod에서 실행되는 프로세스의 ID를 제공하는 Kubernetes 서비스 계정의 이름입니다.
• 네임스페이스는 서비스 계정 네임스페이스입니다.
• 이름은 나중에 변경할 수 없는 페더레이션 자격 증명의 이름입니다.

기타 ID 공급자

Microsoft Entra 관리 센터의 앱 등록 환경에서 앱 등록을 찾습니다. 왼쪽 탐색 창에서 인증서 및 비밀을 선택하고 페더레이션된 자격 증명 탭을 선택한 다음 자격 증명 추가를 선택합니다.

드롭다운 메뉴에서 기타 발급자 시나리오를 선택합니다.

다음 필드를 지정합니다(예: Google Cloud에서 실행되는 소프트웨어 워크로드 사용).

• 이름은 나중에 변경할 수 없는 페더레이션 자격 증명의 이름입니다.
• 주체 식별자: 외부 ID 공급자에서 발급한 토큰의 sub 클레임과 일치해야 합니다. Google Cloud를 사용하는 이 예제에서 주체는 사용하려는 서비스 계정의 고유 ID입니다.
• 발급자: 외부 ID 공급자에서 발급한 토큰의 iss 클레임과 일치해야 합니다. OIDC 검색 사양을 준수하는 URL입니다. Microsoft Entra ID는 이 발급자 URL을 사용하여 토큰의 유효성을 검사하는 데 필요한 키를 가져옵니다. Google Cloud의 경우 발급자는 "https://accounts.google.com"입니다.

앱에 페더레이션 ID 자격 증명 나열

Microsoft Entra 관리 센터의 앱 등록 환경에서 앱 등록을 찾습니다. 왼쪽 탐색 창에서 인증서 및 비밀을 선택하고 페더레이션된 자격 증명 탭을 선택합니다. 앱에 구성된 페더레이션된 자격 증명이 나열됩니다.

앱에서 페더레이션 ID 자격 증명 삭제

Microsoft Entra 관리 센터의 앱 등록 환경에서 앱 등록을 찾습니다. 왼쪽 탐색 창에서 인증서 및 비밀을 선택하고 페더레이션된 자격 증명 탭을 선택합니다. 앱에 구성된 페더레이션된 자격 증명이 나열됩니다.

페더레이션 ID 자격 증명을 삭제하려면 자격 증명에 대한 삭제 아이콘을 선택합니다.

필수 조건

• 아직 Azure 계정이 없으면 계속하기 전에 체험 계정에 등록해야 합니다.

• Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.

  

• CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.

  • 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.

  • 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.

  • az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

• Microsoft Entra ID로 앱 등록을 만듭니다. 외부 소프트웨어 워크로드가 대상으로 하는 Azure 리소스에 대한 액세스 권한을 앱에 부여합니다.
• 다음 단계에 필요한 앱의 개체 ID, 앱(클라이언트) ID 또는 식별자 URI를 찾습니다. 이러한 값은 Microsoft Entra 관리 센터에서 찾을 수 있습니다. 등록된 애플리케이션 목록에서 앱 등록을 선택합니다. 개요->Essentials에서 다음 단계에 필요한 개체 ID, 애플리케이션(클라이언트) ID 또는 애플리케이션 ID URI 값을 가져옵니다.
• 다음 단계에서 필요한 외부 IdP 및 소프트웨어 워크로드에 대해 주체 및 발급자 정보를 가져옵니다.

앱에서 페더레이션 ID 자격 증명 구성

az ad app federated-credential create 명령을 실행하여 앱에서 새로운 페더레이션 ID 자격 증명을 만듭니다.

id 매개 변수는 애플리케이션의 식별자 URI, 애플리케이션 ID 또는 개체 ID를 지정합니다. parameters 매개 변수는 페더레이션 ID 자격 증명에 대해 JSON 형식으로 매개 변수를 지정합니다.

GitHub Actions 예

이름은 페더레이션 ID 자격 증명의 이름을 지정합니다.

발급자는 GitHub OIDC 공급자 https://token.actions.githubusercontent.com/에 대한 경로를 식별합니다. 이 발급자는 Azure 애플리케이션에서 신뢰할 수 있게 됩니다.

주체는 GitHub Actions 워크플로에 대한 GitHub 조직, 리포지토리 및 환경을 식별합니다. GitHub Actions 워크플로가 GitHub 토큰을 액세스 토큰으로 교환하도록 Microsoft ID 플랫폼에 요청하면 페더레이션 ID 자격 증명의 값이 제공된 GitHub 토큰에 대해 검사됩니다. Azure에서 액세스 토큰을 부여하기 전에 요청은 여기에 정의된 조건과 일치해야 합니다.

• 환경에 연결된 작업의 경우: repo:< Organization/Repository >:environment:< Name >
• 환경에 연결되지 않은 작업의 경우 워크플로를 트리거하는 데 사용되는 참조 경로를 기반으로 분기/태그에 대한 참조 경로(repo:< Organization/Repository >:ref:< ref path>)를 포함합니다. 예를 들어 repo:n-username/ node_express:ref:refs/heads/my-branch 또는 repo:n-username/ node_express:ref:refs/tags/my-tag입니다.
• 끌어오기 요청 이벤트에 의해 트리거된 워크플로의 경우: repo:< Organization/Repository >:pull-request

az ad app federated-credential create --id f6475511-fd81-4965-a00e-41e7792b7b9c --parameters credential.json
("credential.json" contains the following content)
{
    "name": "Testing",
    "issuer": "https://token.actions.githubusercontent.com",
    "subject": "repo:octo-org/octo-repo:environment:Production",
    "description": "Testing",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

Kubernetes 예제

발급자는 서비스 계정 발급자 URL(관리형 클러스터의 OIDC 발급자 URL 또는 자체 관리형 클러스터의 OIDC 발급자 URL)입니다.

subject는 서비스 계정에 발급된 토큰의 주체 이름입니다. Kubernetes는 주체 이름에 system:serviceaccount:<SERVICE_ACCOUNT_NAMESPACE>:<SERVICE_ACCOUNT_NAME> 형식을 사용합니다.

이름은 나중에 변경할 수 없는 페더레이션 자격 증명의 이름입니다.

대상은 외부 토큰에 표시할 수 있는 대상을 나열합니다. 이 필드는 필수입니다. 권장 값은 "api://AzureADTokenExchange"입니다.

az ad app federated-credential create --id f6475511-fd81-4965-a00e-41e7792b7b9c --parameters credential.json
("credential.json" contains the following content)
{
    "name": "Kubernetes-federated-credential",
    "issuer": "https://aksoicwesteurope.blob.core.windows.net/9d80a3e1-2a87-46ea-ab16-e629589c541c/",
    "subject": "system:serviceaccount:erp8asle:pod-identity-sa",
    "description": "Kubernetes service account federated credential",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

기타 ID 공급자 예제

앱에서 페더레이션 ID 자격 증명을 구성하고 다른 외부 ID 공급자와 트러스트 관계를 만듭니다. 다음 예제에서는 예를 들어 Google Cloud에서 실행되는 소프트웨어 워크로드가 사용됩니다.

이름은 나중에 변경할 수 없는 페더레이션 자격 증명의 이름입니다.

ID: 앱의 개체 ID, 애플리케이션(클라이언트) ID 또는 식별자 URI입니다.

주체: 외부 ID 공급자에서 발급한 토큰의 sub 클레임과 일치해야 합니다. Google Cloud를 사용하는 이 예제에서 주체는 사용하려는 서비스 계정의 고유 ID입니다.

발급자: 외부 ID 공급자에서 발급한 토큰의 iss 클레임과 일치해야 합니다. OIDC 검색 사양을 준수하는 URL입니다. Microsoft Entra ID는 이 발급자 URL을 사용하여 토큰의 유효성을 검사하는 데 필요한 키를 가져옵니다. Google Cloud의 경우 발급자는 "https://accounts.google.com"입니다.

대상: 외부 토큰에 표시할 수 있는 대상을 나열합니다. 이 필드는 필수입니다. 권장 값은 "api://AzureADTokenExchange"입니다.

az ad app federated-credential create --id f6475511-fd81-4965-a00e-41e7792b7b9c --parameters credential.json
("credential.json" contains the following content)
{
    "name": "GcpFederation",
    "issuer": "https://accounts.google.com",
    "subject": "112633961854638529490",
    "description": "Test GCP federation",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

앱에 페더레이션 ID 자격 증명 나열

az ad app federated-credential list 명령을 실행하여 앱에서 페더레이션 ID 자격 증명을 나열합니다.

ID 매개 변수는 애플리케이션의 식별자 URI, 애플리케이션 ID 또는 개체 ID를 지정합니다.

az ad app federated-credential list --id f6475511-fd81-4965-a00e-41e7792b7b9c

앱에서 페더레이션 ID 자격 증명 가져오기

az ad app federated-credential show 명령을 실행하여 앱에서 페더레이션 ID 자격 증명을 가져옵니다.

ID 매개 변수는 애플리케이션의 식별자 URI, 애플리케이션 ID 또는 개체 ID를 지정합니다.

federated-credential-id는 페더레이션 ID 자격 증명의 ID 또는 이름을 지정합니다.

az ad app federated-credential show --id f6475511-fd81-4965-a00e-41e7792b7b9c --federated-credential-id c79f8feb-a9db-4090-85f9-90d820caa0eb

앱에서 페더레이션 ID 자격 증명 삭제

az ad app federated-credential delete 명령을 실행하여 앱에서 페더레이션 ID 자격 증명을 제거합니다.

ID 매개 변수는 애플리케이션의 식별자 URI, 애플리케이션 ID 또는 개체 ID를 지정합니다.

federated-credential-id는 페더레이션 ID 자격 증명의 ID 또는 이름을 지정합니다.

az ad app federated-credential delete --id f6475511-fd81-4965-a00e-41e7792b7b9c --federated-credential-id c79f8feb-a9db-4090-85f9-90d820caa0eb

필수 조건

• 예제 스크립트를 실행하려면 다음 두 가지 옵션을 사용합니다.
  • 코드 블록의 오른쪽 위 모서리에 있는 사용해 보기 단추를 사용하여 열 수 있는 Azure Cloud Shell을 사용합니다.
  • 다음 섹션에 설명된 대로 Azure PowerShell을 사용하여 로컬로 스크립트를 실행합니다.
• Microsoft Entra ID로 앱 등록을 만듭니다. 외부 소프트웨어 워크로드가 대상으로 하는 Azure 리소스에 대한 액세스 권한을 앱에 부여합니다.
• 다음 단계에서 필요한 앱의 개체 ID(애플리케이션(클라이언트) ID 아님)를 찾습니다. Microsoft Entra 관리 센터에서 앱의 개체 ID를 찾을 수 있습니다. 등록된 애플리케이션 목록에서 앱 등록을 선택합니다. 개요->기본 정보에서 개체 ID를 찾습니다.
• 다음 단계에서 필요한 외부 IdP 및 소프트웨어 워크로드에 대해 주체 및 발급자 정보를 가져옵니다.

로컬로 Azure PowerShell 구성

Cloud Shell을 사용하는 대신 이 문서에서 Azure PowerShell을 로컬로 사용하려면 다음을 수행합니다.

1. 아직 설치하지 않은 경우 Azure PowerShell 최신 버전을 설치합니다.

2. Azure에 로그인합니다.

   Connect-AzAccount
   

3. PowerShellGet 최신 버전을 설치합니다.

   Install-Module -Name PowerShellGet -AllowPrerelease
   

   다음 단계에서 이 명령을 실행한 후 현재 PowerShell 세션에서 Exit를 제거해야 합니다.

4. 이 문서에서 페더레이션 ID 자격 증명 작업을 수행하기 위해 Az.Resources 모듈의 시험판 버전을 설치합니다.

   Install-Module -Name Az.Resources -AllowPrerelease
   

앱에서 페더레이션 ID 자격 증명 구성

New-AzADAppFederatedCredential cmdlet을 실행하여 애플리케이션에 새로운 페더레이션 ID 자격 증명을 만듭니다.

GitHub Actions 예

• ApplicationObjectId: 이전에 Microsoft Entra ID에 등록한 앱의 개체 ID입니다(애플리케이션(클라이언트) ID가 아님).
• 발급자는 GitHub를 외부 토큰 발급자로 식별합니다.
• 주체는 GitHub Actions 워크플로에 대한 GitHub 조직, 리포지토리 및 환경을 식별합니다. GitHub Actions 워크플로가 GitHub 토큰을 액세스 토큰으로 교환하도록 Microsoft ID 플랫폼에 요청하면 페더레이션 ID 자격 증명의 값이 제공된 GitHub 토큰에 대해 검사됩니다.
  • 환경에 연결된 작업의 경우: repo:< Organization/Repository >:environment:< Name >
  • 환경에 연결되지 않은 작업의 경우 워크플로를 트리거하는 데 사용되는 참조 경로를 기반으로 분기/태그에 대한 참조 경로(repo:< Organization/Repository >:ref:< ref path>)를 포함합니다. 예를 들어 repo:n-username/ node_express:ref:refs/heads/my-branch 또는 repo:n-username/ node_express:ref:refs/tags/my-tag입니다.
  • 끌어오기 요청 이벤트에 의해 트리거된 워크플로의 경우: repo:< Organization/Repository >:pull-request
• 이름은 나중에 변경할 수 없는 페더레이션 자격 증명의 이름입니다.
• 대상은 외부 토큰에 표시할 수 있는 대상을 나열합니다. 이 필드는 필수입니다. 권장 값은 "api://AzureADTokenExchange"입니다.

New-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -Audience api://AzureADTokenExchange -Issuer 'https://token.actions.githubusercontent.com/' -Name 'GitHub-Actions-Test' -Subject 'repo:octo-org/octo-repo:environment:Production'

Kubernetes 예제

• ApplicationObjectId: 이전에 Microsoft Entra ID에 등록한 앱의 개체 ID입니다(애플리케이션(클라이언트) ID가 아님).
• 발급자는 서비스 계정 발급자 URL(관리형 클러스터의 OIDC 발급자 URL 또는 자체 관리형 클러스터의 OIDC 발급자 URL)입니다.
• 주체는 서비스 계정에 발급된 토큰의 주체 이름입니다. Kubernetes는 주체 이름에 system:serviceaccount:<SERVICE_ACCOUNT_NAMESPACE>:<SERVICE_ACCOUNT_NAME> 형식을 사용합니다.
• 이름은 나중에 변경할 수 없는 페더레이션 자격 증명의 이름입니다.
• 대상은 외부 토큰의 aud 클레임에 나타날 수 있는 대상을 나열합니다.

New-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -Audience api://AzureADTokenExchange -Issuer 'https://aksoicwesteurope.blob.core.windows.net/9d80a3e1-2a87-46ea-ab16-e629589c541c/' -Name 'Kubernetes-federated-credential' -Subject 'system:serviceaccount:erp8asle:pod-identity-sa'

기타 ID 공급자 예제

다음 매개 변수를 지정합니다(예: Google Cloud에서 실행되는 소프트웨어 워크로드 사용).

• ObjectID: 이전에 Microsoft Entra ID에 등록한 앱의 개체 ID입니다(애플리케이션(클라이언트) ID가 아님).
• 이름은 나중에 변경할 수 없는 페더레이션 자격 증명의 이름입니다.
• 주체: 외부 ID 공급자에서 발급한 토큰의 sub 클레임과 일치해야 합니다. Google Cloud를 사용하는 이 예제에서 주체는 사용하려는 서비스 계정의 고유 ID입니다.
• 발급자: 외부 ID 공급자에서 발급한 토큰의 iss 클레임과 일치해야 합니다. OIDC 검색 사양을 준수하는 URL입니다. Microsoft Entra ID는 이 발급자 URL을 사용하여 토큰의 유효성을 검사하는 데 필요한 키를 가져옵니다. Google Cloud의 경우 발급자는 "https://accounts.google.com"입니다.
• 대상: 외부 토큰의 aud 클레임과 일치해야 합니다. 보안상의 이유로 Microsoft Entra ID용 토큰에 고유한 값을 선택해야 합니다. 권장 값은 "api://AzureADTokenExchange"입니다.

New-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -Audience api://AzureADTokenExchange -Issuer 'https://accounts.google.com' -Name 'GcpFederation' -Subject '112633961854638529490'

앱에 페더레이션 ID 자격 증명 나열

Get-AzADAppFederatedCredential cmdlet을 실행하여 애플리케이션에 대한 페더레이션 ID 자격 증명을 나열합니다.

Get-AzADApplication -ObjectId $app | Get-AzADAppFederatedCredential

앱에서 페더레이션 ID 자격 증명 가져오기

Get-AzADAppFederatedCredential cmdlet을 실행하여 애플리케이션에서 ID에 따라 페더레이션 ID 자격 증명을 가져옵니다.

Get-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -FederatedCredentialId $credentialId

앱에서 페더레이션 ID 자격 증명 삭제

Remove-AzADAppFederatedCredential cmdlet을 실행하여 애플리케이션에서 페더레이션 ID 자격 증명을 삭제합니다.

Remove-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -FederatedCredentialId $credentialId

필수 조건

Microsoft Entra ID로 앱 등록을 만듭니다. 외부 소프트웨어 워크로드가 대상으로 하는 Azure 리소스에 대한 액세스 권한을 앱에 부여합니다.

다음 단계에서 필요한 앱의 개체 ID(애플리케이션(클라이언트) ID 아님)를 찾습니다. Microsoft Entra 관리 센터에서 앱의 개체 ID를 찾을 수 있습니다. 등록된 애플리케이션 목록에서 앱 등록을 선택합니다. 개요->기본 정보에서 개체 ID를 찾습니다.

다음 단계에서 필요한 외부 IdP 및 소프트웨어 워크로드에 대해 주체 및 발급자 정보를 가져옵니다.

Microsoft Graph 엔드포인트(https://graph.microsoft.com)는 애플리케이션에서 federatedIdentityCredentials를 만들고, 업데이트하고, 삭제하는 REST API를 노출합니다. AZ CLI에서 Microsoft Graph 명령을 실행하기 위해 Azure Cloud Shell을 시작하고 테넌트에 로그인합니다.

앱에서 페더레이션 ID 자격 증명 구성

GitHub Actions

다음 메서드를 실행하여 앱(앱의 개체 ID에 의해 지정됨)에 새 페더레이션 ID 자격 증명 만들기를 수행합니다. 발급자는 GitHub를 외부 토큰 발급자로 식별합니다. 주체는 GitHub Actions 워크플로에 대한 GitHub 조직, 리포지토리 및 환경을 식별합니다. GitHub Actions 워크플로가 GitHub 토큰을 액세스 토큰으로 교환하도록 Microsoft ID 플랫폼에 요청하면 페더레이션 ID 자격 증명의 값이 제공된 GitHub 토큰에 대해 검사됩니다.

az rest --method POST --uri 'https://graph.microsoft.com/applications/f6475511-fd81-4965-a00e-41e7792b7b9c/federatedIdentityCredentials' --body '{"name":"Testing","issuer":"https://token.actions.githubusercontent.com","subject":"repo:octo-org/octo-repo:environment:Production","description":"Testing","audiences":["api://AzureADTokenExchange"]}'

그리고 다음과 같은 응답을 받습니다.

{
  "@odata.context": "https://graph.microsoft.com/$metadata#applications('f6475511-fd81-4965-a00e-41e7792b7b9c')/federatedIdentityCredentials/$entity",
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "description": "Testing",
  "id": "1aa3e6a7-464c-4cd2-88d3-90db98132755",
  "issuer": "https://token.actions.githubusercontent.com",
  "name": "Testing",
  "subject": "repo:octo-org/octo-repo:environment:Production"
}

이름: Azure 애플리케이션의 이름입니다.

발급자: GitHub OIDC 공급자에 대한 경로입니다. https://token.actions.githubusercontent.com. 이 발급자는 Azure 애플리케이션에서 신뢰할 수 있게 됩니다.

주체: Azure에서 액세스 토큰을 부여하기 전에 요청은 여기에 정의된 조건과 일치해야 합니다.

• 환경에 연결된 작업의 경우: repo:< Organization/Repository >:environment:< Name >
• 환경에 연결되지 않은 작업의 경우 워크플로를 트리거하는 데 사용되는 참조 경로를 기반으로 분기/태그에 대한 참조 경로(repo:< Organization/Repository >:ref:< ref path>)를 포함합니다. 예를 들어 repo:n-username/ node_express:ref:refs/heads/my-branch 또는 repo:n-username/ node_express:ref:refs/tags/my-tag입니다.
• 끌어오기 요청 이벤트에 의해 트리거된 워크플로의 경우: repo:< Organization/Repository >:pull-request

대상은 외부 토큰에 표시할 수 있는 대상을 나열합니다. 이 필드는 필수입니다. 권장 값은 "api://AzureADTokenExchange"입니다.

Kubernetes 예제

다음 메서드를 실행하여 앱에서 페더레이션 ID 자격 증명을 구성하고 Kubernetes 서비스 계정과의 트러스트 관계를 만듭니다. 다음 매개 변수를 지정합니다.

• 발급자는 서비스 계정 발급자 URL(관리형 클러스터의 OIDC 발급자 URL 또는 자체 관리형 클러스터의 OIDC 발급자 URL)입니다.
• subject는 서비스 계정에 발급된 토큰의 주체 이름입니다. Kubernetes는 주체 이름에 system:serviceaccount:<SERVICE_ACCOUNT_NAMESPACE>:<SERVICE_ACCOUNT_NAME> 형식을 사용합니다.
• 이름은 나중에 변경할 수 없는 페더레이션 자격 증명의 이름입니다.
• 대상은 외부 토큰에 표시할 수 있는 대상을 나열합니다. 이 필드는 필수입니다. 권장 값은 "api://AzureADTokenExchange"입니다.

az rest --method POST --uri 'https://graph.microsoft.com/applications/f6475511-fd81-4965-a00e-41e7792b7b9c/federatedIdentityCredentials' --body '{"name":"Kubernetes-federated-credential","issuer":"https://aksoicwesteurope.blob.core.windows.net/9d80a3e1-2a87-46ea-ab16-e629589c541c/","subject":"system:serviceaccount:erp8asle:pod-identity-sa","description":"Kubernetes service account federated credential","audiences":["api://AzureADTokenExchange"]}'

그리고 다음과 같은 응답을 받습니다.

{
  "@odata.context": "https://graph.microsoft.com/$metadata#applications('f6475511-fd81-4965-a00e-41e7792b7b9c')/federatedIdentityCredentials/$entity",
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "description": "Kubernetes service account federated credential",
  "id": "51ecf9c3-35fc-4519-a28a-8c27c6178bca",
  "issuer": "https://aksoicwesteurope.blob.core.windows.net/9d80a3e1-2a87-46ea-ab16-e629589c541c/",
  "name": "Kubernetes-federated-credential",
  "subject": "system:serviceaccount:erp8asle:pod-identity-sa"
}

기타 ID 공급자 예제

다음 메서드를 실행하여 앱에서 페더레이션 ID 자격 증명을 구성하고 외부 ID 공급자와 트러스트 관계를 만듭니다. 다음 매개 변수를 지정합니다(예: Google Cloud에서 실행되는 소프트웨어 워크로드 사용).

• 이름은 나중에 변경할 수 없는 페더레이션 자격 증명의 이름입니다.
• ObjectID: 이전에 Microsoft Entra ID에 등록한 앱의 개체 ID입니다(애플리케이션(클라이언트) ID가 아님).
• 주체: 외부 ID 공급자에서 발급한 토큰의 sub 클레임과 일치해야 합니다. Google Cloud를 사용하는 이 예제에서 주체는 사용하려는 서비스 계정의 고유 ID입니다.
• 발급자: 외부 ID 공급자에서 발급한 토큰의 iss 클레임과 일치해야 합니다. OIDC 검색 사양을 준수하는 URL입니다. Microsoft Entra ID는 이 발급자 URL을 사용하여 토큰의 유효성을 검사하는 데 필요한 키를 가져옵니다. Google Cloud의 경우 발급자는 "https://accounts.google.com"입니다.
• 대상은 외부 토큰에 표시할 수 있는 대상을 나열합니다. 이 필드는 필수입니다. 권장 값은 "api://AzureADTokenExchange"입니다.

az rest --method POST --uri 'https://graph.microsoft.com/applications/<ObjectID>/federatedIdentityCredentials' --body '{"name":"GcpFederation","issuer":"https://accounts.google.com","subject":"112633961854638529490","description":"Testing","audiences":["api://AzureADTokenExchange"]}'

그리고 다음과 같은 응답을 받습니다.

{
  "@odata.context": "https://graph.microsoft.com/$metadata#applications('f6475511-fd81-4965-a00e-41e7792b7b9c')/federatedIdentityCredentials/$entity",
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "description": "Testing",
  "id": "51ecf9c3-35fc-4519-a28a-8c27c6178bca",
  "issuer": "https://accounts.google.com"",
  "name": "GcpFederation",
  "subject": "112633961854638529490"
}

앱에 페더레이션 ID 자격 증명 나열

다음 메서드를 실행하여 앱(앱의 개체 ID에 의해 지정됨)에 대한 페더레이션 ID 자격 증명 나열을 수행합니다.

az rest -m GET -u 'https://graph.microsoft.com/applications/f6475511-fd81-4965-a00e-41e7792b7b9c/federatedIdentityCredentials'

그리고 다음과 유사한 응답을 받습니다.

{
  "@odata.context": "https://graph.microsoft.com/$metadata#applications('f6475511-fd81-4965-a00e-41e7792b7b9c')/federatedIdentityCredentials",
  "value": [
    {
      "audiences": [
        "api://AzureADTokenExchange"
      ],
      "description": "Testing",
      "id": "1aa3e6a7-464c-4cd2-88d3-90db98132755",
      "issuer": "https://token.actions.githubusercontent.com/",
      "name": "Testing",
      "subject": "repo:octo-org/octo-repo:environment:Production"
    }
  ]
}

앱에서 페더레이션 ID 자격 증명 가져오기

다음 메서드를 실행하여 앱(앱의 개체 ID에 의해 지정됨)에 대한 페더레이션 ID 자격 증명 가져오기를 수행합니다.

az rest -m GET -u 'https://graph.microsoft.com/applications/f6475511-fd81-4965-a00e-41e7792b7b9c//federatedIdentityCredentials/1aa3e6a7-464c-4cd2-88d3-90db98132755'

그리고 다음과 유사한 응답을 받습니다.

{
  "@odata.context": "https://graph.microsoft.com/$metadata#applications('f6475511-fd81-4965-a00e-41e7792b7b9c')/federatedIdentityCredentials",
  "value": {
      "@odata.context": "https://graph.microsoft.com/$metadata#applications('f6475511-fd81-4965-a00e-41e7792b7b9c')/federatedIdentityCredentials/$entity",
      "@odata.id": "https://graph.microsoft.com/v2/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/directoryObjects/$/Microsoft.DirectoryServices.Application('f6475511-fd81-4965-a00e-41e7792b7b9c')/federatedIdentityCredentials('f6475511-fd81-4965-a00e-41e7792b7b9c')/f6475511-fd81-4965-a00e-41e7792b7b9c",
    "audiences": [
        "api://AzureADTokenExchange"
      ],
      "description": "Testing",
      "id": "1aa3e6a7-464c-4cd2-88d3-90db98132755",
      "issuer": "https://token.actions.githubusercontent.com/",
      "name": "Testing",
      "subject": "repo:octo-org/octo-repo:environment:Production"
    }
}

앱에서 페더레이션 ID 자격 증명 삭제

다음 메서드를 실행하여 앱(앱의 개체 ID에 의해 지정됨)에서 페더레이션 ID 자격 증명 삭제를 수행합니다.

az rest -m DELETE  -u 'https://graph.microsoft.com/applications/f6475511-fd81-4965-a00e-41e7792b7b9c/federatedIdentityCredentials/1aa3e6a7-464c-4cd2-88d3-90db98132755'

다음 단계

• Kubernetes에 워크로드 ID 페더레이션을 사용하는 방법을 알아보려면 Kubernetes용 Microsoft Entra 워크로드 ID 오픈 소스 프로젝트를 참조하세요.
• GitHub Actions에 워크로드 ID 페더레이션을 사용하는 방법을 알아보려면 액세스 토큰을 가져오도록 GitHub Actions 워크플로 구성을 참조하세요.
• Microsoft ID 공급자에서 액세스 토큰을 얻고 Azure 리소스에 액세스하도록 GitHub Actions 워크플로를 구성하는 방법에 대한 자세한 내용은 GitHub Actions 설명서를 참조하세요.
• 자세한 내용은 Microsoft Entra ID에서 OAuth 2.0 클라이언트 자격 증명 부여 및 다른 IdP에서 발급한 클라이언트 어설션을 사용하여 토큰을 가져오는 방법을 읽어보세요.
• 외부 ID 공급자에서 만든 JWT의 필수 형식에 대한 정보는 어설션 형식을 참조하세요.