자습서: 함수 및 Microsoft Graph를 사용하여 사용자 지정 역할 할당(미리 보기)

아티클
12/13/2024

이 문서에서는 함수를 사용하여 Microsoft Graph를 쿼리하고 Entra ID 그룹 멤버 자격에 따라 사용자 지정 역할을 사용자에게 할당하는 방법을 보여 줍니다.

이 자습서에서는 다음을 알아봅니다.

정적 웹앱을 배포합니다.
Microsoft Entra 앱 등록을 만듭니다.
Microsoft Entra ID를 사용하여 사용자 지정 인증을 설정합니다.
사용자의 Entra ID 그룹 멤버 자격을 쿼리하고 사용자 지정 역할 목록을 반환하는 서버리스 함수를 구성합니다.

참고 항목

이 자습서에서는 함수를 사용하여 역할을 할당해야 합니다. 함수 기반 역할 관리는 현재 미리 보기에 있습니다. 이 자습서를 완료하는 데 필요한 권한 수준은 "User.Read.All"입니다.

앱의 API에는 GetRoles 함수가 있습니다. 이 함수는 사용자의 액세스 토큰을 사용하여 Microsoft Graph의 Entra ID를 쿼리합니다. 사용자가 앱에 정의된 그룹의 구성원인 경우 해당 사용자 지정 역할이 사용자에 매핑됩니다.

필수 조건

요구 사항	설명
활성 Azure 계정	계정이 없는 경우 체험 계정을 만들 수 있습니다.
Microsoft Entra 권한	Microsoft Entra 애플리케이션을 만드는 데 충분한 권한이 있어야 합니다.

GitHub 리포지토리 만들기

역할 함수 템플릿을 기반으로 리포지토리를 생성합니다. 다음 위치로 이동하여 새 리포지토리를 만듭니다.

https://github.com/staticwebdev/roles-function/generate
리포지토리 이름을 my-custom-roles-app으로 지정합니다.
템플릿에서 리포지토리 만들기를 선택합니다.

Azure에 정적 웹앱 배포

새 브라우저 창에서 Azure Portal을 엽니다.
왼쪽 위 모서리에 있는 리소스 만들기를 선택합니다.
검색 상자에 정적 웹앱을 입력합니다.
Static Web Apps를 선택합니다.
만들기를 실행합니다.

다음 정보를 사용하여 정적 웹앱을 구성합니다.

설정	값	주의
구독	Azure 구독을 선택합니다.
Resource group	my-custom-roles-app-group이라는 새 그룹을 만듭니다.
이름	my-custom-roles-app
플랜 유형	Standard	함수를 사용하여 인증을 사용자 지정하고 역할을 할당하려면 표준 플랜이 필요합니다.
API 지역	가장 가까운 지역을 선택합니다.

배포 세부 정보 섹션에서 다음을 수행합니다.

설정	값
원본	GitHub를 선택합니다.
조직	리포지토리를 생성한 조직을 선택합니다.
리포지토리	my-custom-roles-app을 선택합니다.
Branch	기본을 선택합니다.

빌드 세부 정보 섹션에서 이 앱의 구성 세부 정보를 추가합니다.

설정	값	주의
빌드 사전 설정	사용자 지정을 선택합니다.
앱 위치	/frontend를 입력합니다.	이 폴더에는 프런트 엔드 애플리케이션이 포함되어 있습니다.
API 위치	/api	API 함수가 포함된 리포지토리의 폴더입니다.
출력 위치	비워 둡니다.	이 앱에는 빌드 출력이 없습니다.

검토 + 만들기를 선택합니다.
만들기를 선택하여 첫 번째 배포를 시작합니다.
프로세스가 완료되면 리소스로 이동을 선택하여 새 정적 웹앱을 엽니다.
개요 섹션에서 애플리케이션의 URL을 찾습니다. 이 값을 텍스트 편집기에 복사하여 이후 단계에서 Entra 인증을 설정하는 데 사용합니다.

Microsoft Entra 애플리케이션 만들기

Azure Portal에서 Microsoft Entra ID를 검색하여 이동합니다.
관리 메뉴에서 앱 등록을 선택합니다.

새 등록을 선택하여 애플리케이션 등록 창을 엽니다. 다음 값을 입력합니다.

설정	값	주의
이름	MyStaticWebApp을 입력합니다.
지원되는 계정 유형	이 조직 디렉터리의 계정만을 선택합니다.
리디렉션 URI	웹을 선택하고 정적 웹앱의 Microsoft Entra 인증 콜백 URL을 입력합니다. `<YOUR_SITE_URL>/.auth/login/aad/callback`의 `<YOUR_SITE_URL>`을 정적 웹앱의 URL로 바꿉니다.	이 URL은 이전 단계에서 텍스트 편집기에 복사한 URL입니다.

앱 등록 만들기

등록을 선택합니다.
앱 등록이 만들어지면 기본 정보 섹션의 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID를 텍스트 편집기에 복사합니다.

정적 웹앱에서 Entra ID 인증을 구성하려면 이러한 값이 필요합니다.

ID 토큰 사용

앱 등록 설정의 관리에서 인증을 선택합니다.
암시적 허용 및 하이브리드 흐름 섹션에서 ID 토큰(암시적 흐름과 하이브리드 흐름에 사용됨) 을 선택합니다.

Static Web Apps 런타임에서 사용자를 인증하려면 이 구성이 필요합니다.
저장을 선택합니다.

클라이언트 암호 만들기

앱 등록 설정의 관리에서 인증서 및 비밀을 선택합니다.
클라이언트 비밀 섹션에서 새 클라이언트 비밀을 선택합니다.
설명 필드에 MyStaticWebApp을 입력합니다.
만료 필드에는 기본값인 6개월을 그대로 둡니다.

참고 항목

새 비밀을 생성하고 앱을 해당 값으로 업데이트하여 만료 날짜 이전에 비밀을 회전해야 합니다.
추가를 선택합니다.
만든 클라이언트 암호의 값 텍스트 편집기에 복사합니다.

정적 웹앱에서 Entra ID 인증을 구성하려면 이 값이 필요합니다.

Entra ID 인증 구성

브라우저에서 배포한 정적 웹앱이 포함된 GitHub 리포지토리를 엽니다.

frontend/staticwebapp.config.json에서 앱의 구성 파일로 이동합니다. 이 파일에는 다음 섹션이 포함되어 있습니다.

"auth": {
  "rolesSource": "/api/GetRoles",
  "identityProviders": {
    "azureActiveDirectory": {
      "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
      "registration": {
        "openIdIssuer": "https://login.microsoftonline.com/<YOUR_ENTRA_TENANT_ID>",
        "clientIdSettingName": "ENTRA_CLIENT_ID",
        "clientSecretSettingName": "ENTRA_CLIENT_SECRET"
      },
      "login": {
        "loginParameters": [
          "resource=https://graph.microsoft.com"
        ]
      }
    }
  }
},

이 구성은 다음 설정으로 구성됩니다.

속성	설명
`rolesSource`	로그인 프로세스에서 사용 가능한 역할 목록을 가져오는 URL입니다. 샘플 애플리케이션의 경우 URL은 `/api/GetRoles`입니다.
`userDetailsClaim`	로그인 요청의 유효성을 검사하는 데 사용되는 스키마의 URL입니다.
`openIdIssuer`	테넌트 ID와 함께 추가된 Microsoft Entra 로그인 경로입니다.
`clientIdSettingName`	Microsoft Entra 클라이언트 ID입니다.
`clientSecretSettingName`	Microsoft Entra 클라이언트 암호 값입니다.
`loginParameters`	Microsoft Graph에 대한 액세스 토큰을 가져오려면 `loginParameters` 필드를 `resource=https://graph.microsoft.com`으로 구성해야 합니다.

편집을 선택하여 파일을 업데이트합니다.
<YOUR_ENTRA_TENANT_ID>를 Microsoft Entra ID의 디렉터리(테넌트) ID로 바꿔 https://login.microsoftonline.com/<YOUR_ENTRA_TENANT_ID>의 openIdIssuer 값을 업데이트합니다.
변경 내용 커밋...을 선택합니다.
커밋 메시지를 입력하고 변경 내용 커밋을 선택합니다.

이러한 변경 내용을 커밋하면 GitHub Actions가 실행되어 정적 웹앱이 업데이트됩니다.
Azure Portal에서 정적 웹앱 리소스로 이동합니다.
메뉴 모음에서 구성을 선택합니다.
애플리케이션 설정 섹션에서 다음 설정을 추가합니다.

속성 값

ENTRA_CLIENT_ID Entra ID 애플리케이션(클라이언트) ID입니다.

ENTRA_CLIENT_SECRET Entra 애플리케이션 클라이언트 비밀 값입니다.
저장을 선택합니다.

속성	값
`ENTRA_CLIENT_ID`	Entra ID 애플리케이션(클라이언트) ID입니다.
`ENTRA_CLIENT_SECRET`	Entra 애플리케이션 클라이언트 비밀 값입니다.

역할 만들기

Azure Portal에서 Entra ID 앱 등록을 엽니다.
관리에서 앱 역할을 선택합니다.
앱 역할 만들기를 선택하고 다음 값을 입력합니다.

설정 값

표시 이름 admin을 입력합니다.

허용된 멤버 유형 사용자/그룹을 선택합니다.

값 admin을 입력합니다.

설명 관리자를 입력합니다.
이 앱 역할을 사용하도록 설정하시겠습니까? 상자를 선택합니다.
적용을 선택합니다.
이제 reader 역할에 같은 프로세스를 반복합니다.
각 역할의 ID 값을 복사하고 텍스트 편집기에서 따로 설정합니다.

설정	값
표시 이름	admin을 입력합니다.
허용된 멤버 유형	사용자/그룹을 선택합니다.
값	admin을 입력합니다.
설명	관리자를 입력합니다.

사용자 지정 역할 확인

샘플 애플리케이션에는 사용자가 미리 정의된 그룹에 있는지 확인하기 위해 Microsoft Graph를 쿼리하는 API 함수(api/GetRoles/index.js)가 포함되어 있습니다.

함수는 사용자의 그룹 멤버 자격에 따라 사용자에게 사용자 지정 역할을 할당합니다. 애플리케이션은 이러한 사용자 지정 역할에 따라 특정 경로를 제한하도록 구성됩니다.

GitHub 리포지토리에서 api/GetRoles/index.js에 있는 GetRoles 함수로 이동합니다.

위쪽 근처에는 사용자 지정 사용자 역할을 Microsoft Entra 그룹에 매핑하는 roleGroupMappings 개체가 있습니다.
편집을 선택합니다.
개체를 Microsoft Entra 테넌트의 그룹 ID로 업데이트합니다.

예를 들어 ID가 6b0b2fff-53e9-4cff-914f-dd97a13bfbd6 및 b6059db5-9cef-4b27-9434-bb793aa31805인 그룹이 있는 경우 개체를 다음으로 업데이트합니다.
```
const roleGroupMappings = {
  'admin': '6b0b2fff-53e9-4cff-914f-dd97a13bfbd6',
  'reader': 'b6059db5-9cef-4b27-9434-bb793aa31805'
};
```
GetRoles 함수는 사용자가 Microsoft Entra ID를 통해 성공적으로 인증될 때마다 호출됩니다. 이 함수는 사용자의 액세스 토큰을 사용하여 Microsoft Graph에서 Entra 그룹 멤버 자격을 쿼리합니다. 사용자가 roleGroupMappings 개체에 정의된 그룹의 구성원이면 해당 사용자 지정 역할이 반환됩니다.

위의 예제에서 사용자가 ID b6059db5-9cef-4b27-9434-bb793aa31805가 있는 Entra ID 그룹의 멤버인 경우 해당 역할이 부여됩니다 reader .
변경 내용 커밋...을 선택합니다.
커밋 메시지를 추가하고 변경 내용 커밋을 선택합니다.

변경하면 빌드가 시작되어 정적 웹앱이 업데이트됩니다.
배포가 완료되면 앱의 URL로 이동하여 변경 내용을 확인할 수 있습니다.
Microsoft Entra ID를 사용하여 정적 웹앱에 로그인합니다.
로그인하면 샘플 앱은 ID의 Entra ID 그룹 멤버 자격에 따라 할당된 역할 목록을 표시합니다.

앱의 일부 경로에 대한 액세스는 이러한 역할에 따라 허용되거나 금지됩니다.

참고 항목

Microsoft Graph에 대한 일부 쿼리는 여러 페이지의 데이터를 반환합니다. 둘 이상의 쿼리 요청이 필요한 경우 Microsoft Graph는 결과의 다음 페이지에 대한 URL이 포함된 응답에 @odata.nextLink 속성을 반환합니다. 자세한 내용은 앱에서 Microsoft Graph 데이터 페이징을 참조하세요.

리소스 정리

리소스 그룹을 삭제하여 배포된 리소스를 정리합니다.

Azure Portal의 왼쪽 메뉴에서 리소스 그룹을 선택합니다.
이름으로 필터링 필드에서 리소스 그룹 이름을 입력합니다.
이 자습서에서 사용한 리소스 그룹 이름을 선택합니다.
위쪽 메뉴에서 리소스 그룹 삭제를 선택합니다.

다음 단계

인증 및 권한 부여

다음을 통해 공유