SSO 설정 API

이 문서는 OAuth2와 SAML에 대한 SSO 설정(Single Sign-On settings)을 생성, 갱신, 삭제, 조회, 나열하는 API를 설명해요. Grafana Enterprise에서 일부 엔드포인트는 특정 권한이 필요합니다. 자세한 내용은 역할 기반 접근 제어 권한을 참고하세요.

출처: 문서

본문

참고: Grafana 13부터 /api 엔드포인트는 /apis 경로를 위해 더 이상 사용되지 않습니다(deprecated). Grafana가 기존 API를 마이그레이션하는 동안 현재 여러분이 사용하는 레거시 API와 정확히 일치하는 항목이 없을 수도 있어요. 이 변경은 현재 설정을 방해하거나 깨지 않습니다. 레거시 API는 비활성화되지 않으며 완전히 접근 가능하고 정상 작동하지만, /api 경로는 더 이상 업데이트되지 않습니다. 자세한 내용은 Grafana의 새 API 구조를 참고하세요.

이 API로 관리되는 설정은 데이터베이스에 저장되며 다른 소스의 설정 (인자, 환경 변수, 설정 파일 등)을 덮어씁니다. 따라서 특정 공급자의 설정을 런타임에 제거하거나 기본값으로 재설정할 때마다 설정은 우선순위의 역순으로 다른 소스에서 상속됩니다(arguments > environment variables > settings file).

SSO 설정 나열하기

GET /api/v1/sso-settings

모든 공급자의 SSO 설정을 나열합니다. 이 API로 관리되지 않는 공급자나 SSO 키는 다른 소스(설정 파일, 환경 변수, 기본값)에서 가져옵니다.

필요 권한 (소개 부분의 참고를 참고하세요):

액션	범위
settings:read	settings:auth.{provider}:*

예시 요청:

GET /api/v1/sso-settings HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예시 응답:

HTTP/1.1 200
Content-Type: application/json
[
  {
    "id":        "1",
    "provider":  "github",
    "settings": {
      "apiUrl": "https://api.github.com/user",
      "clientId": "my_github_client",
      "clientSecret": "*********",
      "enabled": true,
      "scopes": "user:email,read:org"
      // rest of the settings
    },
    "source":    "system",
  },
  {
    "id":        "2",
    "provider":  "azuread",
    "settings": {
      "authUrl": "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0/authorize",
      "clientId": "my_azuread_client",
      "clientSecret": "*********",
      "enabled": true,
      "scopes": "openid,email,profile"
      // rest of the settings
    },
    "source":    "system",
  }
]

상태 코드:

200 – SSO 설정을 찾음
400 – 잘못된 요청 (Bad Request)
401 – 인증되지 않음 (Unauthorized)
403 – 접근 거부 (Access Denied)

SSO 설정 가져오기

GET /api/v1/sso-settings/:provider

공급자의 SSO 설정을 가져옵니다. 이 API로 관리되지 않는 SSO 키는 다른 소스(설정 파일, 환경 변수, 기본값)에서 가져옵니다.

필요 권한:

액션	범위
settings:read	settings:auth.{provider}:*

예시 요청:

GET /api/v1/sso-settings/github HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예시 응답:

HTTP/1.1 200
Content-Type: application/json
ETag: db87f729761898ee
{
  "id":        "1",
  "provider":  "github",
  "settings": {
    "apiUrl": "https://api.github.com/user",
    "clientId": "my_github_client",
    "clientSecret": "*********",
    "enabled": true,
    "scopes": "user:email,read:org"
    // rest of the settings
  },
  "source":    "system",
}

상태 코드:

200 – SSO 설정을 찾음
400 – 잘못된 요청
401 – 인증되지 않음
403 – 접근 거부
404 – SSO 설정을 찾을 수 없음

SSO 설정 갱신하기

PUT /api/v1/sso-settings/:provider

공급자의 SSO 설정을 갱신합니다. API로 공급자의 새 설정을 제출하면 Grafana는 주어진 설정이 허용되고 유효한지 검증합니다. 유효하다면 Grafana는 설정을 데이터베이스에 저장하고 인스턴스를 재시작하지 않고 Grafana 서비스를 다시 로드합니다.

참고: 고가용성(high availability) 모드에서 Grafana를 실행하면 구성 변경이 모든 Grafana 인스턴스에 즉시 적용되지 않을 수 있어요. 설정이 모든 Grafana 인스턴스로 전파되려면 몇 분 기다려야 할 수 있습니다.

필요 권한:

액션	범위
settings:write	settings:auth.{provider}:*

예시 요청:

PUT /api/v1/sso-settings/github HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "settings": {
    "apiUrl": "https://api.github.com/user",
    "clientId": "my_github_client",
    "clientSecret": "my_github_secret",
    "enabled": true,
    "scopes": "user:email,read:org"
  }
}

예시 응답:

HTTP/1.1 204
Content-Type: application/json

상태 코드:

204 – SSO 설정 갱신됨
400 – 잘못된 요청
401 – 인증되지 않음
403 – 접근 거부

SSO 설정 삭제하기

DELETE /api/v1/sso-settings/:provider

공급자의 기존 SSO 설정 항목을 삭제합니다.

필요 권한:

액션	범위
settings:write	settings:auth.{provider}:*

예시 요청:

DELETE /api/v1/sso-settings/azuread HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예시 응답:

HTTP/1.1 204
Content-Type: application/json

상태 코드:

204 – SSO 설정 삭제됨
400 – 잘못된 요청
401 – 인증되지 않음
403 – 접근 거부
404 – SSO 설정을 찾을 수 없음

더 알아보기 (Learn more)

원문 문서