Microsoft Entra ID OAuth 인증 구성

Microsoft Entra ID OAuth 인증 구성 (Configure Microsoft Entra ID OAuth authentication)

Microsoft Entra ID(이전 Azure Active Directory) 인증을 사용하면 Entra ID 테넌트를 Grafana의 ID 공급자로 쓸 수 있어요. Entra ID 애플리케이션 역할(application roles)로 Azure Portal에서 사용자와 그룹을 Grafana 역할에 할당할 수 있어요. Grafana는 UI, Terraform provider, Grafana 구성 파일 세 가지 방식으로 Entra ID OAuth 클라이언트를 구성할 수 있어요.

출처: 문서

본문

Caution Microsoft Entra ID와 다른 인증 공급자(예: Grafana.com)에서 같은 이메일 주소를 쓰면, 사용자가 올바르게 매칭되도록 추가 구성이 필요해요. "다른 ID 공급자로 로그인할 때 같은 이메일 주소 사용" 문서를 참고하세요.

애플리케이션을 Microsoft Entra ID에 등록

1. Azure Portal에 로그인하고 사이드 메뉴에서 Microsoft Entra ID를 클릭해요. 여러 테넌트에 접근할 수 있다면 오른쪽 위에서 계정을 선택하고 사용할 Entra ID 테넌트로 세션을 설정해요.
2. Manage 아래 App Registrations > New Registration을 클릭하고 설명적인 이름을 입력해요.
3. Redirect URI에서 앱 유형을 Web으로 선택해요.
4. 리다이렉트 URL https://<grafana domain>/login/azuread와 https://<grafana domain>을 추가하고 Register를 클릭해요. 앱의 Overview 페이지가 열려요.
5. Application ID를 기록해요. 이것이 OAuth 클라이언트 ID예요.
6. 상단 메뉴에서 Endpoints를 클릭해요. OAuth 2.0 authorization endpoint (v2) URL(authorization URL)과 OAuth 2.0 token endpoint (v2)(token URL)를 기록해요.
7. Certificates & secrets에서 원하는 클라이언트 인증 옵션에 따라 항목을 추가해요. 지원되는 클라이언트 인증 옵션:
   • Client secrets: Client secrets에 Description(Grafana OAuth 2.0), Expires를 설정하고 Value를 복사. 이것이 OAuth 2.0 클라이언트 시크릿. Grafana 서버 구성에서 [auth.azuread]의 client_authentication을 client_secret_post로 설정해야 동작해요.
   • Federated credentials - Managed Identity: Federated credentials에 Federated credential scenario를 Other issuer로, Issuer는 Entra ID 권한의 OAuth 2.0/OIDC issuer URL(예: https://login.microsoftonline.com/{tenantID}/v2.0), Subject identifier는 Managed Identity의 Object (Principal) ID, Audience는 api://AzureADTokenExchange(Public cloud)로 설정. client_authentication을 managed_identity로 설정해야 동작. Managed identity는 Azure에 호스팅된 워크로드에만 적용되고, Entra ID 앱에는 user-assigned managed identity만 federated credential로 추가 가능해요.
   • Federated credentials - Workload Identity (K8s/AKS): Kubernetes accessing Azure resources 시나리오로, Cluster issuer URL, Namespace(예: grafana), Service account name(예: grafana), Subject identifier(예: system:serviceaccount:grafana:grafana), Audience(api://AzureADTokenExchange)를 설정. client_authentication을 workload_identity로, client_id(Entra ID App Registration Application ID), token_url(https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token), auth_url을 설정해야 동작.
8. Azure Portal이나 manifest 파일로 Grafana용 애플리케이션 역할을 정의해요.
9. Microsoft Entra ID > Enterprise Applications > Manage로 이동해 애플리케이션을 검색하고, Users and Groups > Add user/group으로 사용자·그룹을 Grafana 역할에 추가해요.

Note 그룹을 Grafana 역할에 할당할 때 사용자가 그룹의 직접 멤버인지 확인하세요. 중첩 그룹의 사용자는 Entra ID의 제한 때문에 Grafana에 접근할 수 없어요.

Entra ID 포털에서 애플리케이션 역할 구성

• App Registrations > 앱 선택 > App roles > Create app role.
• Grafana 역할(Viewer, Editor, Admin) 각각에 역할을 정의해요. Display name(예: "Grafana Editor"), Allowed member types를 Users/Groups로, Value 필드는 Grafana 역할 이름과 일치(예: "Editor")해야 해요. Apply 클릭.

manifest 파일에서 애플리케이션 역할 구성

App Registrations > 앱 선택 > Manifest를 클릭해요. 각 역할에 Universally Unique Identifier를 추가해요 (Linux uuidgen, Windows PowerShell New-Guid로 생성). manifest의 각 "SOME_UNIQUE_ID"를 생성된 ID로 바꿔요:

"appRoles": [
		{
			"allowedMemberTypes": [
				"User"
			],
			"description": "Grafana org admin Users",
			"displayName": "Grafana Org Admin",
			"id": "SOME_UNIQUE_ID",
			"isEnabled": true,
			"lang": null,
			"origin": "Application",
			"value": "Admin"
		},
		{
			"allowedMemberTypes": [
				"User"
			],
			"description": "Grafana read only Users",
			"displayName": "Grafana Viewer",
			"id": "SOME_UNIQUE_ID",
			"isEnabled": true,
			"lang": null,
			"origin": "Application",
			"value": "Viewer"
		},
		{
			"allowedMemberTypes": [
				"User"
			],
			"description": "Grafana Editor Users",
			"displayName": "Grafana Editor",
			"id": "SOME_UNIQUE_ID",
			"isEnabled": true,
			"lang": null,
			"origin": "Application",
			"value": "Editor"
		}
	],

서버 관리자 권한 할당

GrafanaAdmin 애플리케이션 역할로 사용자에게 서버 관리자 권한을 부여할 수 있어요. 이 역할 JSON:

{
  "allowedMemberTypes": ["User"],
  "description": "Grafana server admin Users",
  "displayName": "Grafana Server Admin",
  "id": "SOME_UNIQUE_ID",
  "isEnabled": true,
  "lang": null,
  "origin": "Application",
  "value": "GrafanaAdmin"
}

동작하려면 [auth.azuread]에서 allow_assign_grafana_admin을 true로 설정해야 해요. false로 설정하면 기본 조직의 Admin 역할만 부여되고 서버 관리자 권한은 부여되지 않아요.

Grafana UI로 클라이언트 구성

Grafana Admin으로 Administration > Authentication > Entra ID 페이지에서 양식을 채워 구성할 수 있어요. 구성 파일에 현재 설정이 있으면 양식이 미리 채워지고, 없으면 기본값이 표시돼요. Save 후 성공하면 새 구성이 적용돼요. UI 변경을 기본값으로 되돌리려면 Reset을 클릭해요. 고가용성 모드에서는 변경이 모든 인스턴스에 즉시 적용되지 않을 수 있으니 몇 분 기다려야 할 수 있어요.

Terraform provider로 클라이언트 구성

resource "grafana_sso_settings" "azuread_sso_settings" {
  provider_name = "azuread"
  oauth2_settings {
    name                          = "Entra ID"
    auth_url                      = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize"
    token_url                     = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token"
    client_authentication         = "CLIENT_AUTHENTICATION_OPTION"
    client_id                     = "APPLICATION_ID"
    client_secret                 = "CLIENT_SECRET"
    managed_identity_client_id    = "MANAGED_IDENTITY_CLIENT_ID"
    federated_credential_audience = "FEDERATED_CREDENTIAL_AUDIENCE"
    allow_sign_up                 = true
    auto_login                    = false
    scopes                        = "openid email profile"
    allowed_organizations         = "TENANT_ID"
    role_attribute_strict         = false
    allow_assign_grafana_admin    = false
    skip_org_role_sync            = false
    use_pkce                      = true
    custom = {
      domain_hint = "contoso.com"
      force_use_graph_api = "true"
    }
  }
}

Terraform Registry에서 grafana_sso_settings 리소스의 전체 참조를 확인하세요.

Grafana 구성 파일로 클라이언트 구성

Entra ID OAuth 활성화

[auth.azuread]
name = Entra ID
enabled = true
allow_sign_up = true
auto_login = false
client_authentication = CLIENT_AUTHENTICATION_OPTION
client_id = APPLICATION_ID
client_secret = CLIENT_SECRET
managed_identity_client_id = MANAGED_IDENTITY_CLIENT_ID
federated_credential_audience = FEDERATED_CREDENTIAL_AUDIENCE
scopes = openid email profile
auth_url = https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize
token_url = https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token
allowed_domains =
allowed_groups =
allowed_organizations = TENANT_ID
role_attribute_strict = false
allow_assign_grafana_admin = false
skip_org_role_sync = false
use_pkce = true

환경 변수로도 구성할 수 있어요:

GF_AUTH_AZUREAD_CLIENT_AUTHENTICATION
GF_AUTH_AZUREAD_CLIENT_ID
GF_AUTH_AZUREAD_CLIENT_SECRET
GF_AUTH_AZUREAD_MANAGED_IDENTITY_CLIENT_ID
GF_AUTH_AZUREAD_FEDERATED_CREDENTIAL_AUDIENCE

Note Grafana root_url이 Azure Application Redirect URLs에 설정되어 있는지 확인하세요.

refresh token 구성

Grafana는 사용자 로그인 시 액세스 토큰 만료 여부를 확인해요. 액세스 토큰이 만료되면 제공된 refresh token(존재 시)으로 새 토큰을 얻어요. refresh token이 없으면 액세스 토큰 만료 후 사용자를 로그아웃해요. Entra ID 공급자에서는 Grafana v10.1.0부터 기본적으로 활성화돼요. 꺼려면 use_refresh_token을 false로 설정. (전용 accessTokenExpirationCheck 피처 토글은 v10.3.0에서 제거됨.)

allowed tenants 구성

한 개 이상 테넌트 멤버로 접근을 제한하려면 allowed_organizations를 쉼표·공백 구분 테넌트 ID 목록으로 설정해요. 테넌트 ID는 Azure Portal의 Microsoft Entra ID > Overview에서 찾을 수 있어요. Entra ID에 외부 ID가 있으면 federated 사용자들의 루트 디렉토리 테넌트 ID도 포함하세요. 예:

allowed_organizations = 8bab1c86-8fba-33e5-2089-1d1c80ec267d

allowed groups 구성

Entra ID 그룹으로 사용자 접근을 제한하려면 allowed_groups를 그룹 object ID 목록으로 설정해요. Azure Portal에서 Microsoft Entra ID > Manage > Groups > 그룹 > Properties에서 Object ID를 찾을 수 있어요. 토큰에 그룹 속성을 추가하도록 Entra ID App registration을 활성화해야 해요.

• Azure Portal에서 그룹 멤버십 클레임 구성: App Registrations > 앱 > Token configuration > Add groups claim에서 적절한 옵션(예: Security groups) 선택.
• manifest 파일에서 그룹 멤버십 클레임 구성: Manifest의 루트에 "groupMembershipClaims": "ApplicationGroup, SecurityGroup" 추가.

Note 사용자가 200개 이상 그룹의 멤버면, Entra ID는 토큰에 groups 클레임 대신 group overage claim을 내보내요. 자세한 내용은 "Users with over 200 Group assignments" 참고.

allowed_domains 구성

allowed_domains 옵션은 특정 도메인에 속한 사용자로 접근을 제한해요. 공백·쉼표로 구분:

allowed_domains = mycompany.com mycompany.org

PKCE

RFC 7636의 "proof key for code exchange"(PKCE)는 인가 코드 가로채기 공격의 일부 형태에 대한 추가 보호를 제공하며 OAuth 2.1에서 요구될 예정이에요. [auth.azuread]에서 use_pkce를 false로 설정해 비활성화할 수 있어요.

자동 로그인

로그인 화면을 건너뛰고 자동 로그인하려면 auto_login 기능을 활성화해요. 여러 auth provider가 auto login을 쓰면 이 설정은 무시돼요.

auto_login = true

Team Sync

Note Grafana Enterprise와 일부 Grafana Cloud 플랜에서 사용 가능.

Team Sync로 Entra ID 그룹을 Grafana 팀에 매핑해 사용자를 올바른 팀에 자동 추가할 수 있어요. Entra ID 그룹은 object ID(예: 8bab1c86-8fba-33e5-2089-1d1c80ec267d)로 참조할 수 있어요.

조직 역할 동기화 건너뛰기

Entra ID 인증이 사용자 역할과 조직 멤버십을 동기화하지 않게 하려면 skip_org_role_sync를 true로 설정해요. Grafana 안에서 사용자 조직 역할을 직접 관리하고 싶을 때 쓰세요.

[auth.azuread]
# ..
# prevents the sync of org roles from Entra ID
skip_org_role_sync = true

주요 구성 옵션

설정	필수	설명	기본값
enabled	아니요	Entra ID 인증 활성화	false
client_authentication	예	토큰 엔드포인트 인증 방법. 지원 값: none, client_secret_post, managed_identity, workload_identity
client_id	예	앱의 클라이언트 ID
client_secret	예	앱의 클라이언트 시크릿
auth_url	예	Entra ID OAuth2 공급자 인가 엔드포인트
token_url	예	OAuth2 액세스 토큰을 얻는 엔드포인트
scopes	아니요	쉼표·공백 구분 OAuth2 스코프	openid email profile
allow_sign_up	아니요	Entra ID 로그인으로 Grafana 사용자 생성 제어. false면 기존 사용자만 로그인 가능	true
auto_login	아니요	로그인 화면 생략하고 자동 로그인	false
role_attribute_strict	아니요	true면 role_attribute_path/org_mapping으로 역할을 추출할 수 없으면 로그인 거부	false
allow_assign_grafana_admin	아니요	Grafana 서버 관리자 역할 자동 동기화	false
skip_org_role_sync	아니요	사용자 역할 자동 동기화 중지	false
allowed_groups	아니요	접근 허용 그룹 목록
allowed_organizations	아니요	접근 허용 Azure 테넌트 ID 목록
allowed_domains	아니요	접근 허용 도메인 목록
use_pkce	아니요	PKCE 사용 (S256)	true
use_refresh_token	아니요	refresh token 사용 및 액세스 토큰 만료 확인. offline_access 스코프 자동 추가	true
force_use_graph_api	아니요	id_token 대신 항상 Microsoft Graph API에서 그룹 조회	false

일반적인 문제 해결

200개 초과 그룹 할당 사용자

토큰 크기가 HTTP 헤더 크기 한도를 넘지 않도록 Entra ID는 groups 클레임에 포함하는 object ID 수를 제한해요. 사용자가 커버리지 한도(200)보다 많은 그룹의 멤버면, groups 클레임 대신 group overage claim을 내보내요. Grafana가 overage claim을 받으면 포함된 엔드포인트를 호출해 그룹 멤버십을 가져오려 시도해요. 그러려면 Entra ID App registration에 다음 API 권한이 필요해요:

권한 이름	유형	관리자 동의 필요	상태
GroupMember.Read.All	Delegated	예	Granted
User.Read	Delegated	아니요	Granted

force_use_graph_api 설정을 켜면 항상 Microsoft Graph API에서 그룹 정보를 얻을 수 있어요.

역할 매핑

기본적으로 Entra ID 인증은 Entra ID에서 사용자에게 할당된 최상위 애플리케이션 역할에 따라 사용자를 조직 역할로 매핑해요. 애플리케이션 역할이 없으면 auto_assign_org_role 옵션이 지정한 역할을 할당해요. role_attribute_strict = true로 기본 역할 할당을 비활성화할 수 있어요. org_mapping으로 사용자를 여러 조직에 할당하고 Entra ID 그룹 멤버십에 따라 역할을 지정할 수 있어요. 로그인할 때마다 사용자 조직 역할이 Entra ID 애플리케이션 역할과 일치하도록 재설정돼요.

Org roles 매핑 예제: 사용자가 org_foo에서 Viewer, org_bar와 org_baz에서 Editor 역할을 부여받았고, Entra ID 그룹 032cb8e0-240f-4347-9120-6f33013e817a와 bce1c492-0679-4989-941b-8de5e6789cb9에 속해 있는 경우:

org_mapping = ["032cb8e0-240f-4347-9120-6f33013e817a:org_foo:Viewer", "bce1c492-0679-4989-941b-8de5e6789cb9:org_bar:Editor", "*:org_baz:Editor"]

더 알아보기 (Learn more)

• Configure authentication
• Team Sync
• Map roles
• Microsoft Azure Portal