Azure Static Web Apps의 사용자 지정 인증
Azure Static Web Apps는 Azure에서 관리하는 공급자 등록을 사용하는 관리형 인증을 제공합니다. 등록에 대한 유연성을 높일 수 있도록 사용자 지정 등록을 사용하여 기본값을 재정의할 수 있습니다.
사용자 지정 인증을 사용하면 OpenID Connect를 지원하는 사용자 지정 공급자를 구성할 수도 있습니다. 이 구성을 사용하면 여러 외부 공급자를 등록할 수 있습니다.
사용자 지정 등록을 사용하면 미리 구성된 모든 공급자가 사용하지 않도록 설정됩니다.
참고 항목
사용자 지정 인증은 Azure Static Web Apps 표준 플랜에서만 사용할 수 있습니다.
사용자 지정 ID 공급자 구성
사용자 지정 ID 공급자는 구성 파일의 auth 섹션에서 구성됩니다.
소스 제어에 비밀을 포함시키지 않으려면 구성은 애플리케이션 설정에서 구성 파일의 일치하는 이름을 찾습니다. Azure Key Vault에 비밀을 저장하도록 선택할 수도 있습니다.
등록을 만들려면 먼저 다음 애플리케이션 설정을 만듭니다.
| 설정 이름 | 값 |
|---|---|
AZURE_CLIENT_ID |
Microsoft Entra 앱 등록을 위한 애플리케이션(클라이언트) ID입니다. |
| `AZURE_CLIENT_SECRET_APP_SETTING_NAME | Microsoft Entra 앱 등록에 대한 클라이언트 암호를 보유하는 애플리케이션 설정의 이름입니다. |
다음으로, 아래의 샘플을 사용하여 구성 파일에서 공급자를 구성합니다.
Microsoft Entra 공급자는 두 가지 버전으로 제공됩니다. 버전 1은 페이로드가 사용자 정보를 반환할 수 있도록 하는 userDetailsClaim을 명시적으로 정의합니다. 반대로 버전 2는 기본적으로 사용자 정보를 반환하고, openIdIssuer URL에서 v2.0으로 지정됩니다.
Microsoft Entra 버전 1
{
"auth": {
"identityProviders": {
"azureActiveDirectory": {
"userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
"registration": {
"openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
"clientIdSettingName": "AZURE_CLIENT_ID",
"clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
}
}
}
}
}
<TENANT_ID>를 Microsoft Entra 테넌트 ID로 바꿉니다.
Microsoft Entra 버전 2
{
"auth": {
"identityProviders": {
"azureActiveDirectory": {
"registration": {
"openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
"clientIdSettingName": "AZURE_CLIENT_ID",
"clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
}
}
}
}
}
<TENANT_ID>를 Microsoft Entra 테넌트 ID로 바꿉니다.
Microsoft Entra ID를 구성하는 방법에 대한 자세한 내용은 기존 등록 사용에 대한 App Service 인증/권한 부여 설명서를 참조하세요.
로그인할 수 있는 계정을 구성하려면 애플리케이션에서 지원하는 계정 수정 및 Microsoft Entra 앱을 Microsoft Entra 테넌트의 사용자 집합으로 제한을 참조하세요.
참고 항목
Microsoft Entra ID의 구성 섹션은 azureActiveDirectory이지만 플랫폼은 로그인, 로그아웃 및 사용자 정보 제거를 위해 URL에서 이를 aad로 별칭을 지정합니다. 자세한 내용은 인증 및 권한 부여 섹션을 참조하세요.
사용자 지정 인증서
Microsoft Entra ID 앱 등록에 사용자 지정 인증서를 추가하려면 다음 단계를 따릅니다.
아직 인증서가 없으면 Microsoft Key Vault에 인증서를 업로드합니다.
Static Web App에 관리 ID를 추가합니다.
사용자가 할당한 관리 ID의 경우 정적 사이트 개체의
keyVaultReferenceIdentity속성을 사용자가 할당한 관리 ID의resourceId로 설정합니다.관리 ID가 시스템에서 할당된 경우 이 단계를 건너뜁니다.
관리 ID에 다음 액세스 정책을 부여합니다.
- 비밀: Get/List
- 인증서: Get/List
다음 예에 표시된 대로
azureActiveDirectory구성 섹션의 인증 구성 섹션을clientSecretCertificateKeyVaultReference값으로 업데이트합니다.{ "auth": { "rolesSource": "/api/GetRoles", "identityProviders": { "azureActiveDirectory": { "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "registration": { "openIdIssuer": "https://login.microsoftonline.com/common/v2.0", "clientIdSettingName": "AZURE_CLIENT_ID", "clientSecretCertificateKeyVaultReference": "@Microsoft.KeyVault(SecretUri=https://<KEY_VAULT_NAME>.azure.net/certificates/<CERTIFICATE_NAME>/<CERTIFICATE_VERSION_ID>)", "clientSecretCertificateThumbprint": "*" } } } } }<>로 묶인 자리 표시자의 값을 바꿔야 합니다.비밀 URI에서 키 자격 증명 모음 이름과 인증서 이름을 지정합니다. 버전에 고정하려면 인증서 버전을 포함하고, 그렇지 않으면 런타임이 인증서의 최신 버전을 선택할 수 있도록 버전을 생략합니다.
항상 최신 버전의 인증서 지문을 끌어오려면
clientSecretCertificateThumbprint를*와 동일하게 설정합니다.
인증 콜백
ID 공급자가 로그인 또는 로그아웃 요청을 완료하려면 리디렉션 URL이 필요합니다. 대부분의 공급자는 콜백 URL을 허용 목록에 추가해야 합니다. 다음 엔드포인트는 리디렉션 대상으로 사용할 수 있습니다.
| Type | URL 패턴 |
|---|---|
| 로그인 | https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback |
| 로그아웃 | https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback |
Microsoft Entra ID를 사용하는 경우 <PROVIDER_NAME_IN_CONFIG> 자리 표시자의 값으로 aad를 사용합니다.
참고 항목
이러한 URL은 인증 공급자로부터 응답을 받기 위해 Azure Static Web Apps에서 제공하므로 이러한 경로에서 페이지를 만들 필요가 없습니다.
로그인, 로그아웃 및 사용자 세부 정보
사용자 지정 ID 공급자를 사용하려면 다음 URL 패턴을 사용합니다.
| 작업 | 패턴 |
|---|---|
| 로그인 | /.auth/login/<PROVIDER_NAME_IN_CONFIG> |
| 로그아웃 | /.auth/logout |
| 사용자 세부 정보 | /.auth/me |
| 사용자 세부 정보 제거 | /.auth/purge/<PROVIDER_NAME_IN_CONFIG> |
Microsoft Entra ID를 사용하는 경우 <PROVIDER_NAME_IN_CONFIG> 자리 표시자의 값으로 aad를 사용합니다.
역할 관리
정적 웹앱에 액세스하는 모든 사용자는 하나 이상의 역할에 속해 있습니다. 사용자가 속할 수 있는 두 가지 기본 제공 역할은 다음과 같습니다.
- 익명: 모든 사용자는 자동으로 익명 역할에 속합니다.
- 인증됨: 로그인된 모든 사용자는 인증됨 역할에 속합니다.
기본 제공 역할 외에 사용자 지정 역할을 사용자에게 할당하고, staticwebapp.config.json 파일에서 참조할 수 있습니다.
역할에 사용자 추가
사용자를 역할에 추가하려면 특정 역할에 사용자를 연결하는 데 사용할 수 있는 초대를 생성합니다. 역할은 staticwebapp.config.json 파일에서 정의되고 유지됩니다.
초대 만들기
초대는 개별 인증 공급자와 관련이 있으므로 지원할 공급자를 선택할 때 앱의 요구 사항을 고려해야 합니다. 일부 공급자는 사용자의 이메일 주소를 노출하지만 다른 공급자는 사이트의 사용자 이름만 제공합니다.
| 권한 부여 공급자 | 노출 |
|---|---|
| Microsoft Entra ID | 메일 주소 |
| GitHub | 사용자 이름 |
| X | 사용자 이름 |
다음 단계를 사용하여 초대를 만듭니다.
- Azure Portal에서 Static Web Apps 리소스로 이동합니다.
- 설정에서 역할 관리를 선택합니다.
- 초대를 선택합니다.
- 옵션 목록에서 권한 부여 공급자를 선택합니다.
- 초대 대상자 정보 상자에 받는 사람의 사용자 이름 또는 이메일 주소를 추가합니다.
- GitHub 및 X의 경우 사용자 이름을 입력합니다. 다른 모든 경우에는 받는 사람의 이메일 주소를 입력합니다.
- 도메인 드롭다운 메뉴에서 정적 사이트의 도메인을 선택합니다.
- 선택한 도메인은 초대에 표시되는 도메인입니다. 사이트와 연결된 사용자 지정 도메인이 있는 경우 사용자 지정 도메인을 선택합니다.
- 역할 상자에 쉼표로 구분된 역할 이름 목록을 추가합니다.
- 초대가 유효한 상태로 유지되도록 할 최대 시간을 입력합니다.
- 가능한 최대 제한은 168시간(7일)입니다.
- 생성을 선택합니다.
- 초대 링크 상자에서 링크를 복사합니다.
- 액세스를 허용하는 사용지에게 초대 링크를 메일로 보냅니다.
사용자가 초대의 링크를 클릭하면 해당 계정으로 로그인하라는 메시지가 표시됩니다. 성공적으로 로그인하면 사용자는 선택한 역할과 연결됩니다.
주의
경로 규칙이 선택한 인증 공급자와 충돌하지 않는지 확인합니다. 경로 규칙을 사용하여 공급자를 차단하면 사용자가 초대를 수락하지 못합니다.
역할 할당 업데이트
- Azure Portal에서 Static Web Apps 리소스로 이동합니다.
- 설정에서 역할 관리를 선택합니다.
- 목록에서 사용자를 선택합니다.
- 역할 상자에서 역할 목록을 편집합니다.
- 업데이트를 선택합니다.
사용자 삭제
- Azure Portal에서 Static Web Apps 리소스로 이동합니다.
- 설정에서 역할 관리를 선택합니다.
- 목록에서 사용자를 찾습니다.
- 사용자의 행에 대한 확인란을 선택합니다.
- 삭제를 선택합니다.
사용자를 제거하는 경우 다음 항목을 염두에 두어야 합니다.
- 사용자를 제거하면 해당 권한이 무효화됩니다.
- 전 세계적으로 전파하는 데 몇 분 정도 걸릴 수 있습니다.
- 사용자를 앱에 다시 추가하면
userId가 변경됩니다.