Azure Active Directory B2C에서 OAuth 2.0 클라이언트 자격 증명 흐름 설정

아티클
01/11/2024

시작하기 전에 이 페이지 위쪽의 정책 유형 선택 선택기를 사용하여 설정하려는 정책 유형을 선택합니다. Azure Active Directory B2C는 사용자가 애플리케이션과 상호 작용하는 방법을 정의하는 두 가지 방법, 즉 미리 정의된 사용자 흐름 또는 완전히 구성 가능한 사용자 지정 정책을 통해 제공합니다. 이 문서에서 필요한 단계는 각 방법마다 다릅니다.

OAuth 2.0 클라이언트 자격 증명 부여 흐름은 REST API와 같은 웹 리소스를 호출할 때 인증하기 위해 앱(기밀 클라이언트)에서 사용자를 가장하는 대신 자체 자격 증명을 사용하도록 허용합니다. 이 유형의 권한 부여는 일반적으로 사용자의 직접적인 상호 작용 없이 백그라운드에서 실행해야 하는 서버 간 상호 작용에 사용됩니다. 이러한 유형의 애플리케이션은 종종 디먼 또는 서비스 계정이라고 합니다.

클라이언트 자격 증명 흐름에서는 관리자가 애플리케이션 자체에 직접 사용 권한을 부여합니다. 앱에서 토큰을 리소스에 제공하는 경우 인증에 관련된 사용자가 없으므로 리소스에서 작업을 수행할 수 있는 권한을 앱 자체에 부여합니다. 이 문서에서는 API를 호출할 수 있는 권한을 애플리케이션에 부여하는 데 필요한 단계와 해당 API를 호출하는 데 필요한 토큰을 가져오는 방법에 대해 설명합니다.

참고 항목

이 기능은 공개 미리 보기 상태입니다.

앱 등록 개요

앱에서 클라이언트 자격 증명으로 로그인한 다음, 웹 API를 호출할 수 있도록 하려면 두 개의 애플리케이션을 Azure AD B2C 디렉터리에 등록합니다.

애플리케이션 등록을 사용하면 앱에서 Azure AD B2C를 통해 로그인할 수 있습니다. 앱 등록 프로세스는 앱을 고유하게 식별하는 애플리케이션 ID(클라이언트 ID라고도 함)를 생성합니다. 또한 앱에서 토큰을 안전하게 획득하는 데 사용하는 클라이언트 암호를 만듭니다.
웹 API 등록을 사용하면 앱에서 보안 웹 API를 호출할 수 있습니다. 등록에는 웹 API 범위가 포함됩니다. 범위는 웹 API와 같은 보호된 리소스에 대한 사용 권한을 관리하는 방법을 제공합니다. 그런 다음, 웹 애플리케이션 권한을 웹 API 범위에 부여합니다. 액세스 토큰이 요청되면 앱에서 요청의 .default 범위 매개 변수를 지정합니다. Azure AD B2C는 앱에 부여된 웹 API 범위를 반환합니다.

앱 아키텍처 및 등록은 다음 다이어그램에 설명되어 있습니다.

Diagram of a web app with web A P I call registrations and tokens.

1단계: 웹 API 앱 등록

이 단계에서는 해당 범위와 함께 웹 API(앱 2)를 등록합니다. 나중에 해당 범위에 대한 권한을 애플리케이션(앱 1)에 부여합니다. 이러한 앱 등록이 이미 있는 경우 이 단계를 건너뛰고 다음 단계, 1.1단계 웹 API 역할(범위) 정의로 이동합니다.

웹 API 앱 등록(앱 ID: 2)을 만들려면 다음 단계를 수행합니다.

Azure Portal에 로그인합니다.
Azure AD B2C 테넌트가 포함된 디렉터리를 사용하고 있는지 확인합니다. 포털 도구 모음에서 디렉터리 + 구독 아이콘을 선택합니다.
포털 설정 | 디렉터리 + 구독 페이지의 디렉터리 이름 목록에서 Azure AD B2C 디렉터리를 찾은 다음, 전환을 선택합니다.
Azure Portal에서 Azure AD B2C를 검색하고 선택합니다.
앱 등록을 선택한 다음, 새 등록을 선택합니다.
이름으로 애플리케이션의 이름(예: my-api1)을 입력합니다. 리디렉션 URI 및 지원되는 계정 유형의 기본값은 그대로 둡니다.
등록을 선택합니다.
앱 등록이 완료되면 개요를 선택합니다.
웹 애플리케이션을 구성할 때 나중에 사용할 수 있도록 애플리케이션(클라이언트) ID 값을 기록합니다.

1.1단계 웹 API 역할(범위) 정의

이 단계에서는 웹 API 애플리케이션 ID URI를 구성한 다음, 앱 역할을 정의합니다. 앱 역할은 OAuth 2.0 범위에서 사용하고 API를 나타내는 애플리케이션 등록에 정의됩니다. 애플리케이션은 .default 범위의 애플리케이션 ID URI를 사용합니다. 앱 역할을 정의하려면 다음 단계를 수행합니다.

만든 웹 API(예: my-api1)를 선택합니다.
관리에서 API 표시를 선택합니다.
애플리케이션 ID URI 옆에 있는 설정 링크를 선택합니다. 기본값(GUID)을 고유한 이름(예: api)으로 바꾼 다음, 저장을 선택합니다.
애플리케이션 ID URI를 복사합니다. 다음 스크린샷에서는 애플리케이션 ID URI를 복사하는 방법을 보여 줍니다.
관리 아래에서 매니페스트를 선택하여 애플리케이션 매니페스트 편집기를 엽니다. 편집기에서 appRoles 설정을 찾고, applications를 대상으로 하는 앱 역할을 정의합니다. 각 앱 역할 정의에는 id 값에 대한 GUID(전역 고유 식별자)가 있어야 합니다. Microsoft PowerShell에서 new-guid 명령을 실행하거나 온라인 GUID 생성기를 실행하여 새 GUID를 생성합니다. 각 앱 역할 정의의 value 속성이 범위인 scp 클레임에 표시됩니다. value 속성은 공백을 포함할 수 없습니다. 다음 예제에서는 읽기 및 쓰기라는 두 가지 앱 역할을 보여 줍니다.
```
"appRoles": [
{
  "allowedMemberTypes": ["Application"],
  "displayName": "Read",
  "id": "d6a15e20-f83c-4264-8e61-5082688e14c8",
  "isEnabled": true,
  "description": "Readers have the ability to read tasks.",
  "value": "app.read"
},
{
  "allowedMemberTypes": ["Application"],
  "displayName": "Write",
  "id": "204dc4ab-51e1-439f-8c7f-31a1ebf3c7b9",
  "isEnabled": true,
  "description": "Writers have the ability to create tasks.",
  "value": "app.write"
}],
```
페이지 위쪽에서 저장을 선택하여 매니페스트 변경 내용을 저장합니다.

2단계: 애플리케이션 등록

앱이 클라이언트 자격 증명 흐름을 사용하여 Azure AD B2C로 로그인할 수 있도록 하려면 기존 애플리케이션을 사용하거나 새 애플리케이션(앱 1)을 등록할 수 있습니다.

기존 앱을 사용하는 경우 앱의 accessTokenAcceptedVersion이 2로 설정되어 있는지 확인합니다.

Azure Portal에서 Azure AD B2C를 검색하고 선택합니다.
앱 등록을 선택한 다음, 목록에서 기존 앱을 선택합니다.
왼쪽 메뉴의 관리 아래에서 매니페스트를 선택하여 매니페스트 편집기를 엽니다.
accessTokenAcceptedVersion 요소를 찾아 값을 2로 설정합니다.
페이지 위쪽에서 저장을 선택하여 변경 내용을 저장합니다.

새 웹앱 등록을 만들려면 다음 단계를 수행합니다.

Azure Portal에서 Azure AD B2C를 검색하고 선택합니다.
앱 등록을 선택한 다음, 새 등록을 선택합니다.
애플리케이션의 이름을 입력합니다. 예를 들어 ClientCredentials_app입니다.
다른 값은 그대로 둔 다음, 등록을 선택합니다.
이후 단계에서 사용할 수 있게 애플리케이션(클라이언트) ID를 기록합니다.

2.1단계 클라이언트 암호 만들기

등록된 애플리케이션에 대한 클라이언트 암호를 만듭니다. 앱은 토큰을 요청할 때 클라이언트 암호를 사용하여 ID를 증명합니다.

관리에서 인증서 및 비밀을 선택합니다.
새 클라이언트 비밀을 선택합니다.
설명 상자에 클라이언트 비밀에 대한 설명을 입력합니다(예: clientsecret1).
만료에서 암호가 유효한 기간을 선택한 다음 추가를 선택합니다.
비밀의 값을 기록합니다. 이후 단계에서 구성에 이 값을 사용합니다.

2.2단계 웹 API에 대한 앱 권한 부여

앱(앱 1) 권한을 부여하려면 다음 단계를 수행합니다.

앱 등록을 선택한 다음, 만든 앱(앱 1)을 선택합니다.
관리 아래에서 API 권한을 선택합니다.
구성된 사용 권한 아래에서 권한 추가를 선택합니다.
내 API 탭을 선택합니다.
웹 애플리케이션에 액세스 권한을 부여해야 하는 API(앱 2)를 선택합니다. 예를 들어 my-api1을 입력합니다.
애플리케이션 권한을 선택합니다.
권한 아래에서 앱을 펼친 다음, 앞에서 정의한 범위(예: app.read 및 app.write)를 선택합니다.
권한 추가를 선택합니다.
<테넌트 이름에 대한 관리자 동의 부여>를 선택합니다.
예를 선택합니다.
새로 고침을 선택한 다음, 두 범위 모두 상태에 ...에 대해 허용됨이 표시되는지 확인합니다.

3단계: 액세스 토큰 얻기

사용자 흐름 또는 사용자 지정 정책에 대한 클라이언트 자격 증명을 사용하도록 설정하기 위한 특정 작업은 없습니다. Azure AD B2C 사용자 흐름과 사용자 지정 정책은 모두 클라이언트 자격 증명 흐름을 지원합니다. 아직 없는 경우 사용자 흐름 또는 사용자 지정 정책을 만듭니다. 그런 다음, 즐겨찾는 API 개발 애플리케이션을 사용하여 권한 부여 요청을 생성합니다. 다음 정보를 POST 요청의 본문으로 사용하여 이 예제와 같은 호출을 생성합니다.

https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy>/oauth2/v2.0/token

<tenant-name>을 Azure AD B2C 테넌트의 이름으로 바꿉니다. 예: contoso.b2clogin.com.
<policy>를 사용자 흐름 또는 사용자 지정 정책의 전체 이름으로 바꿉니다. 모든 유형의 사용자 흐름 및 사용자 지정 정책은 클라이언트 자격 증명 흐름을 지원합니다. 가지고 있는 사용자 흐름 또는 사용자 지정 정책을 사용하거나 가입 또는 로그인과 같은 새 정책을 만들 수 있습니다.

키	값
grant_type	`client_credentials`
client_id	2단계 애플리케이션 등록의 클라이언트 ID입니다.
client_secret	2.1단계 클라이언트 암호 만들기의 클라이언트 암호 값입니다.
scope	1.1단계 웹 API 역할(범위) 정의 및 `.default`의 애플리케이션 ID URI입니다. 예를 들면 `https://contoso.onmicrosoft.com/api/.default` 또는 `https://contoso.onmicrosoft.com/12345678-0000-0000-0000-000000000000/.default`와 같은 인터페이스를 정의할 수 있습니다.

실제 POST 요청은 다음 예제와 같이 표시됩니다.

요청:

POST /<tenant-name>.onmicrosoft.com/B2C_1A_SUSI/oauth2/v2.0/token HTTP/1.1
Host: <tenant-name>.b2clogin.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=33333333-0000-0000-0000-000000000000
&client_secret=FyX7Q~DuPJ...
&scope=https%3A%2F%2Fcontoso.onmicrosoft.com%2Fapi%2F.default

응답:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5OZDlnUkNWWUc2dUs...",
    "token_type": "Bearer",
    "not_before": 1645172292,
    "expires_in": 3600,
    "expires_on": 1645175892,
    "resource": "33333333-0000-0000-0000-000000000000"
}

반환 액세스 토큰 클레임에 대해 알아봅니다. 다음 표에는 클라이언트 자격 증명 흐름과 관련된 클레임이 나와 있습니다.

클레임	설명	값
`aud`	토큰의 의도한 수신자를 식별합니다.	API의 클라이언트 ID입니다.
`sub`	서비스 주체는 요청을 시작한 애플리케이션과 연결됩니다.	권한 부여 요청의 `client_id`에 대한 서비스 주체입니다.
`azp`	권한 있는 당사자 - 액세스 토큰이 발급된 당사자입니다.	요청을 시작한 애플리케이션의 클라이언트 ID입니다. 권한 부여 요청의 `client_id`에 지정한 것과 동일한 값입니다.
`scp`	애플리케이션 API에서 공개하는 범위 세트(공백 구분 기호)입니다.	클라이언트 자격 증명 흐름에서 권한 부여 요청은 `.default` 범위를 요청하는 반면, 토큰에는 API에서 공개하고 앱 관리자가 동의한 범위 목록이 포함됩니다. 예: `app.read app.write`.

3.1단계 스크립트를 사용하여 액세스 토큰 얻기

다음 PowerShell 스크립트를 사용하여 구성을 테스트합니다.

$appId = "<client ID>"
$secret = "<client secret>"
$endpoint = "https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy>/oauth2/v2.0/token"
$scope = "<Your API id uri>/.default"
$body = "grant_type=client_credentials&scope=" + $scope + "&client_id=" + $appId + "&client_secret=" + $secret

$token = Invoke-RestMethod -Method Post -Uri $endpoint -Body $body

다음 cURL 스크립트를 사용하여 구성을 테스트합니다.

curl --location --request POST 'https://<your-tenant>.b2clogin.com/<your-tenant>.onmicrosoft.com/<policy>/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'grant_type="client_credentials"' \
--form 'client_id="<client ID>"' \
--form 'client_secret="<client secret>"' \
--form 'scope="<Your API id uri>/.default"'

4단계: 토큰 사용자 지정

이 기능은 사용자 지정 정책에만 사용할 수 있습니다. 설정 단계의 경우 이전 선택기의 사용자 지정 정책을 선택합니다.

사용자 지정 정책은 토큰 발급 프로세스를 확장하는 방법을 제공합니다. OAuth 2.0 클라이언트 자격 증명의 사용자 경험을 사용자 지정하려면 클라이언트 자격 증명 사용자 경험을 구성하는 방법에 대한 지침을 따릅니다. 그런 다음, JwtIssuer 기술 프로필에서 만든 사용자 경험에 대한 참조가 있는 ClientCredentialsUserJourneyId 메타데이터를 추가합니다.

다음 예제에서는 ClientCredentialsUserJourneyId를 토큰 발급자 기술 프로필에 추가하는 방법을 보여 줍니다.

<TechnicalProfile Id="JwtIssuer">
  <Metadata>
    <Item Key="ClientCredentialsUserJourneyId">ClientCredentialsJourney</Item>
  </Metadata>
</TechnicalProfile>

다음 예제에서는 클라이언트 자격 증명 사용자 경험을 보여 줍니다. 첫 번째 및 마지막 오케스트레이션 단계가 필요합니다.

<UserJourneys>
  <UserJourney Id="ClientCredentialsJourney">
    <OrchestrationSteps>
      <!-- [Required] Do the client credentials -->
      <OrchestrationStep Order="1" Type="ClaimsExchange">
        <ClaimsExchanges>
          <ClaimsExchange Id="ClientCredSetupExchange" TechnicalProfileReferenceId="ClientCredentials_Setup" />
        </ClaimsExchanges>
      </OrchestrationStep>

      <!-- [Optional] Call a REST API or claims transformation -->
      <OrchestrationStep Order="2" Type="ClaimsExchange">
        <ClaimsExchanges>
          <ClaimsExchange Id="TokenAugmentation" TechnicalProfileReferenceId="TokenAugmentation" />
        </ClaimsExchanges>
      </OrchestrationStep>

      <!-- [Required] Issue the access token -->
      <OrchestrationStep Order="3" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />
    </OrchestrationSteps>
  </UserJourney>
</UserJourneys>

다음 단계

Azure AD B2C에서 리소스 소유자 암호 자격 증명 흐름을 설정하는 방법을 알아봅니다.