RBAC API

이 API를 사용해 역할(role)을 생성, 업데이트, 삭제, 조회, 나열할 수 있어요.

필요한 권한을 가진 기본(basic) 또는 고정(fixed) 역할을 확인하려면 "RBAC role definitions" 문서를 참조해요.

⚠️ Grafana 13부터 /api 엔드포인트가 /apis 라우트로 대체되어 더 이상 사용되지 않게(deprecated) 되고 있어요. Grafana가 기존 API를 마이그레이션하는 동안 현재 사용 중인 레거시 API와 정확히 일치하지 않을 수 있어요. 이 변경으로 현재 설정이 중단되거나 깨지지는 않아요. 레거시 API는 비활성화되지 않으며 완전히 접근·사용 가능하지만, /api 라우트는 더 이상 업데이트되지 않아요. 자세한 내용은 "Grafana의 새 API 구조" 문서를 참조해요.

요구 사항

역할 기반 접근 제어(RBAC) API는 Grafana Cloud 또는 Grafana Enterprise에서만 사용할 수 있어요. Grafana Enterprise에 대해 자세히 알아보세요.

출처: 문서

본문

상태 가져오기

GET /api/access-control/status

역할 기반 접근 제어가 활성화되어 있는지 확인할 수 있는 표시를 반환해요.

필요한 권한:

Action	Scope
status:accesscontrol	services:accesscontrol

예제 요청:

GET /api/access-control/status
Accept: application/json
Content-Type: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "enabled": true
}

상태 코드:

Code	Description
200	역할 기반 접근 제어가 활성화되었는지 여부를 나타내는 플래그 반환.
403	Access denied
404	Not found, 역할 기반 접근 제어가 전혀 사용 불가능함을 나타냄.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

사용자 정의 역할 생성 및 관리

모든 역할 가져오기

GET /api/access-control/roles

모든 기존 역할을 가져와요. 응답에는 사용자가 로그인한 조직에 대한 모든 글로벌 역할과 조직 로컬 역할이 포함돼요.

쿼리 매개변수:

includeHidden: 선택 사항. hidden인 역할을 포함하려면 true로 설정.

필요한 권한:

Action	Scope
roles:read	roles:*

예제 요청:

GET /api/access-control/roles
Accept: application/json
Content-Type: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 3,
        "uid": "XvHQJq57z",
        "name": "fixed:reports:reader",
        "displayName": "Report reader",
        "description": "Read all reports and shared report settings.",
        "group": "Reports",
        "updated": "2021-11-19T10:48:00+01:00",
        "created": "2021-11-19T10:48:00+01:00",
        "global": false
    },
    {
        "version": 5,
        "uid": "vi9mlLjGz",
        "name": "fixed:datasources.permissions:writer",
        "description: "Create, read or delete data source permissions.",
        "global": true,
        "updated": "2021-05-13T22:41:49+02:00",
        "created": "2021-05-13T16:24:26+02:00"
    }
]

상태 코드:

Code	Description
200	글로벌 및 조직 로컬 역할이 반환됨.
403	Access denied
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

역할 가져오기

GET /api/access-control/roles/:uid

주어진 UID에 대한 역할을 가져와요.

필요한 권한:

Action	Scope
roles:read	roles:*

예제 요청:

GET /api/access-control/roles/PYnDO3rMk
Accept: application/json
Content-Type: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "version": 4,
    "uid": "6dNwJq57z",
    "name": "fixed:reports:writer",
    "displayName": "Report writer",
    "description": "Create, read, update, or delete all reports and shared report settings.",
    "group": "Reports",
    "permissions": [
        {
            "action": "reports:delete",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:read",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:send",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:create",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:write",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.settings:read",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.settings:write",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        }
    ],
    "updated": "2021-11-19T10:48:00+01:00",
    "created": "2021-11-19T10:48:00+01:00",
    "global": false
}

상태 코드:

Code	Description
200	역할이 반환됨.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

새 사용자 정의 역할 생성

POST /api/access-control/roles

새 사용자 정의 역할을 생성하고 주어진 권한을 그 역할에 매핑해요. Fixed 역할과 같은 접두사를 가진 역할은 생성할 수 없어요.

필요한 권한:

permissions:type:delegate scope는 사용자가 자신이 가진 권한과 같거나 그 부분집합인 사용자 정의 역할만 생성할 수 있게 해요. 예를 들어 사용자가 사용자 생성에 필요한 권한이 없다면, 그렇게 할 수 있게 하는 사용자 정의 역할도 생성할 수 없어요. 이는 권한 상승(privilege escalation)을 방지하기 위함이에요.

Action	Scope
roles:write	permissions:type:delegate

예제 요청:

POST /api/access-control/roles
Accept: application/json
Content-Type: application/json

{
    "uid": "jZrmlLCGka",
    "name": "custom:delete:roles",
    "displayName": "custom delete roles",
    "description": "My custom role which gives users permissions to delete roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions:type:delegate"
        }
    ]
}

JSON body 스키마:

Field Name	Date Type	Required	Description
uid	string	No	역할의 UID. 없으면 UID가 자동 생성되어 응답에 반환됨. Custom roles 참조.
global	boolean	No	역할이 글로벌인지 여부를 나타내는 플래그. false로 설정하면 인증된 사용자의 기본 org ID가 요청에서 사용됨.
version	number	No	더 이상 사용되지 않음(deprecated). 생성 시 무시됨. 서버는 항상 새 역할에 version 1을 할당함. 응답은 할당된 버전을 반환함.
name	string	Yes	역할의 이름. Custom roles 참조.
description	string	No	역할의 설명.
displayName	string	No	UI에 표시되는 역할의 표시 이름.
group	string	No	역할이 속한 그룹 이름.
hidden	boolean	No	역할이 숨김인지 여부를 지정함. true로 설정하면 역할 선택기에서 표시되지 않음. 명시적으로 지정하지 않으면 API 엔드포인트로 나열되지 않음.
permissions	Permission	No	없으면 권한 없이 역할이 생성됨.

Permission:

Field Name	Data Type	Required	Description
action	string	Yes	사용 가능한 action 전체 목록은 Custom role actions and scopes 참조.
scope	string	No	없으면 어떤 scope도 권한에 매핑되지 않음. 사용 가능한 scope 전체 목록은 Custom role actions and scopes 참조.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "version": 2,
    "uid": "jZrmlLCGka",
    "name": "custom:delete:create:roles",
    "displayName": "custom delete create roles",
    "description": "My custom role which gives users permissions to delete and create roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions:type:delegate",
            "updated": "2021-05-13T23:19:46+02:00",
            "created": "2021-05-13T23:19:46+02:00"
        }
    ],
    "updated": "2021-05-13T23:20:51.416518+02:00",
    "created": "2021-05-13T23:19:46+02:00"
}

역할 생성 검증 오류

권한 검증은 권한 검증이 활성화되어 있을 때만 발생해요 (rbac.permission_validation_enabled = true).

Grafana 10.2부터 기본적으로 활성화되어 있어요.

잘못된 action

다음 예제는 잘못된 action이 있는 요청을 보여줘요. serviceaccounts.permissions:reader action은 유효하지 않아요. 올바른 action은 serviceaccounts.permissions:read이에요.

POST /api/access-control/roles HTTP/1.1
Content-Type: application/json
{
	"Name": "Read Service Account with id 6",
	"Permissions": [
			{
			"action": "serviceaccounts.permissions:reader",
			"scope": "serviceaccounts:uid:6"
		}
	]
}

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
	"extra": {
		"validationError": "the provided action was not found in the list of valid actions: serviceaccounts.permissions:reader"
	},
	"message": "Permission contains an invalid action",
	"messageId": "accesscontrol.permission-invalid-action",
	"statusCode": 400,
	"traceID": ""
}

잘못된 scope

다음 예제는 잘못된 scope가 있는 요청을 보여줘요. serviceaccounts:serviceaccount6 scope는 serviceaccounts.permissions:read action에 대해 유효하지 않아요. 이 action의 유효한 scopes는 *, serviceaccounts:*, serviceaccounts:id:*이에요.

POST /api/access-control/roles HTTP/1.1
Content-Type: application/json
{
	"Name": "Read Service Account with id 6",
	"Permissions": [
			{
			"action": "serviceaccounts.permissions:read",
			"scope": "serviceaccounts:serviceaccount6"
		}
	]
}

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
	"extra": {
		"validationError": "unknown scope: serviceaccounts:serviceaccount6 for action: serviceaccounts.permissions:read provided, expected prefixes are [* serviceaccounts:* serviceaccounts:id:*]"
	},
	"message": "Invalid scope",
	"messageId": "accesscontrol.permission-invalid-scope",
	"statusCode": 400,
	"traceID": ""
}

상태 코드:

Code	Description
200	Role is updated.
400	Bad request (잘못된 json, 누락된 content-type, 누락되거나 잘못된 필드 등).
403	Access denied (지정된 권한 중 하나가 요청자에게 할당되지 않음)
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

역할 업데이트

PUT /api/access-control/roles/:uid

주어진 UID의 역할과 그 권한을 업데이트해요. 이 작업은 멱등(idempotent)이며 역할의 모든 권한은 요청 내용에 따라 대체돼요. 낙관적 잠금(optimistic locking)을 위해 역할의 현재 version(마지막 GET 또는 list 응답의)을 보내세요. 다른 곳에서 역할이 업데이트되면 요청은 실패해요. 서버는 각 업데이트마다 저장된 버전을 자동 증가시켜요.

custom 역할과 basic 역할 권한은 업데이트할 수 있지만, fixed 역할은 업데이트할 수 없어요.

필요한 권한:

permissions:type:delegate scope는 사용자가 자신이 가진 권한과 같거나 그 부분집합인 사용자 정의 역할만 업데이트할 수 있게 해요. 예를 들어 사용자가 사용자 생성에 필요한 권한이 없다면, 그렇게 할 수 있게 하는 사용자 정의 역할도 업데이트할 수 없어요. 이는 권한 상승을 방지하기 위함이에요.

Action	Scope
roles:write	permissions:type:delegate

예제 요청:

PUT /api/access-control/roles/jZrmlLCGka
Accept: application/json
Content-Type: application/json

{
    "version": 3,
    "name": "custom:delete:write:roles",
    "displayName": "custom delete write roles",
    "description": "My custom role which gives users permissions to delete and write roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions:type:delegate"
        },
        {
            "action": "roles:write",
            "scope": "permissions:type:delegate"
        }
    ]
}

JSON body 스키마:

Field Name	Data Type	Required	Description
version	number	Yes	역할의 현재 버전 (마지막 GET 또는 list에서). 낙관적 잠금에 필요. 저장된 버전이 더 크면 요청이 실패함. 값을 설정하는 입력으로는 deprecated — 서버가 업데이트 시 저장된 버전을 자동 증가시킴.
name	string	Yes	역할의 이름.
description	string	No	역할의 설명.
displayName	string	No	UI에 표시되는 역할의 표시 이름.
group	string	No	역할이 속한 그룹 이름.
hidden	boolean	No	역할이 숨김인지 여부를 지정함. true로 설정하면 역할 선택기에서 표시되지 않음. 명시적으로 지정하지 않으면 API 엔드포인트로 나열되지 않음.
permissions	List of Permissions	No	업데이트 후 역할의 전체 권한 목록.

Permission:

Field Name	Data Type	Required	Description
action	string	Yes	사용 가능한 action 전체 목록은 Custom role actions and scopes 참조.
scope	string	No	없으면 어떤 scope도 권한에 매핑되지 않음. 사용 가능한 scope 전체 목록은 Custom role actions and scopes 참조.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "version":3,
    "uid":"jZrmlLCGka",
    "name":"custom:delete:write:roles",
    "displayName":"custom delete write roles",
    "description":"My custom role which gives users permissions to delete and write roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "permissions":[
        {
            "action":"roles:delete",
            "scope":"permissions:type:delegate",
            "updated":"2021-08-06T18:27:40+02:00",
            "created":"2021-08-06T18:27:40+02:00"
        },
        {
            "action":"roles:write",
            "scope":"permissions:type:delegate",
            "updated":"2021-08-06T18:27:41+02:00",
            "created":"2021-08-06T18:27:41+02:00"
        }
    ],
    "updated":"2021-08-06T18:27:41+02:00",
    "created":"2021-08-06T18:27:40+02:00",
    "global":false
}

역할 업데이트 검증 오류

권한 검증은 권한 검증이 활성화되어 있을 때만 발생해요 (rbac.permission_validation_enabled = true).

Grafana 10.2부터 기본적으로 활성화되어 있어요.

자세한 내용은 "Create role validation errors" 문서를 참조해요.

상태 코드:

Code	Description
200	Role is updated.
400	Bad request (잘못된 json, 누락된 content-type, 누락되거나 잘못된 필드 등).
403	Access denied (지정된 권한 중 하나가 요청자에게 할당되지 않음)
404	업데이트할 역할을 찾지 못함.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

사용자 정의 역할 삭제

DELETE /api/access-control/roles/:uid?force=false

주어진 UID의 역할과 그 권한을 삭제해요. 역할이 할당되어 있으면 force 쿼리 매개변수가 true로 설정되지 않는 한 삭제가 실패하며, 그 경우 모든 할당도 함께 삭제돼요.

필요한 권한:

permissions:type:delegate scope는 사용자가 자신이 가진 권한과 같거나 그 부분집합인 사용자 정의 역할만 삭제할 수 있게 해요. 예를 들어 사용자가 사용자 생성에 필요한 권한이 없다면, 그렇게 할 수 있게 하는 사용자 정의 역할도 삭제할 수 없어요.

Action	Scope
roles:delete	permissions:type:delegate

예제 요청:

DELETE /api/access-control/roles/jZrmlLCGka?force=true&global=false
Accept: application/json

쿼리 매개변수:

Param	Type	Required	Description
force	boolean	No	true로 설정하면 모든 할당과 함께 역할이 삭제됨.
global	boolean	No	역할이 글로벌인지 여부를 나타내는 플래그. false로 설정하면 인증된 사용자의 기본 org ID가 요청에서 사용됨. About RBAC 참조.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role deleted"
}

상태 코드:

Code	Description
200	Role is deleted.
400	Bad request (잘못된 json, 누락된 content-type, 누락되거나 잘못된 필드 등).
403	Access denied
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

사용자 역할 할당 생성 및 제거

사용자에게 할당된 역할 나열

GET /api/access-control/users/:userId/roles

주어진 사용자에게 직접 할당된 역할을 나열해요. 이 목록에는 기본 역할(Viewer, Editor, Admin 또는 Grafana Admin)이 포함되지 않으며, 팀에서 상속된 역할도 포함되지 않아요.

쿼리 매개변수:

includeHidden: 선택 사항. hidden인 역할을 포함하려면 true로 설정.
includeMapped: 선택 사항. 그룹 속성 동기화 기능을 통해 매핑된 역할을 포함하려면 true로 설정.

필요한 권한:

Action	Scope
users.roles:read	users:id:<user ID>

예제 요청:

GET /api/access-control/users/1/roles
Accept: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 4,
        "uid": "6dNwJq57z",
        "name": "fixed:reports:writer",
        "displayName": "Report writer",
        "description": "Create, read, update, or delete all reports and shared report settings.",
        "group": "Reports",
        "updated": "2021-11-19T10:48:00+01:00",
        "created": "2021-11-19T10:48:00+01:00",
        "global": false
    }
]

상태 코드:

Code	Description
200	할당된 역할 집합이 반환됨.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

내 권한 나열

GET /api/access-control/user/permissions

로그인한 사용자에게 부여된 권한을 나열해요.

필요한 권한: 없음.

쿼리 매개변수:

Param	Type	Required	Description
reloadcache	boolean	No	권한 캐시를 다시 로드하는 플래그.

예제 요청:

GET /api/access-control/user/permissions
Accept: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "dashboards:read": ["dashboards:uid:70KrY6IVz"],
  "dashboards:write": ["dashboards:uid:70KrY6IVz"],
  "datasources.id:read": ["datasources:*"],
  "datasources:read": ["datasources:*"],
  "datasources:explore": [""],
  "datasources:query": ["datasources:uid:grafana"],
  "datasources:read": ["datasources:uid:grafana"],
  "orgs:read": [""]
}

상태 코드:

Code	Description
200	할당된 권한 집합이 반환됨.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

사용자에게 할당된 권한 나열

GET /api/access-control/users/:userId/permissions

주어진 사용자에게 부여된 권한을 나열해요.

필요한 권한:

Action	Scope
users.permissions:read	users:id:<user ID>

예제 요청:

GET /api/access-control/users/1/permissions
Accept: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "action": "ldap.status:read",
        "scope": ""
    },
    {
        "action": "ldap.user:read",
        "scope": ""
    }
]

상태 코드:

Code	Description
200	할당된 권한 집합이 반환됨.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

사용자 역할 할당 추가

POST /api/access-control/users/:userId/roles

특정 사용자에게 역할을 할당해요.

일괄 업데이트에는 "Set user role assignments"를 고려해요.

필요한 권한:

permissions:type:delegate scope는 사용자가 자신이 가진 권한과 같거나 그 부분집합인 역할만 할당할 수 있게 해요. 예를 들어 사용자가 사용자 생성에 필요한 권한이 없다면, 그렇게 할 수 있게 하는 역할도 할당할 수 없어요. 이는 권한 상승을 방지하기 위함이에요.

Action	Scope
users.roles:add	permissions:type:delegate

예제 요청:

POST /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUid": "XvHQJq57z"
}

JSON body 스키마:

Field Name	Data Type	Required	Description
roleUid	string	Yes	역할의 UID.
global	boolean	No	할당이 글로벌인지 여부를 나타내는 플래그. false로 설정하면 인증된 사용자의 기본 org ID가 조직 로컬 할당을 생성하는 데 요청에서 사용됨.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the user."
}

상태 코드:

Code	Description
200	역할이 사용자에게 할당됨.
403	Access denied.
404	Role not found.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

사용자 역할 할당 제거

DELETE /api/access-control/users/:userId/roles/:roleUID

사용자로부터 역할을 회수해요.

일괄 업데이트에는 "Set user role assignments"를 고려해요.

필요한 권한:

permissions:type:delegate scope는 사용자가 자신이 가진 권한과 같거나 그 부분집합인 역할만 할당 해제할 수 있게 해요. 예를 들어 사용자가 사용자 생성에 필요한 권한이 없다면, 그렇게 할 수 있게 하는 역할도 할당 해제할 수 없어요. 이는 권한 상승을 방지하기 위함이에요.

Action	Scope
users.roles:remove	permissions:type:delegate

쿼리 매개변수:

Param	Type	Required	Description
global	boolean	No	할당이 글로벌인지 여부를 나타내는 플래그. false로 설정하면 인증된 사용자의 기본 org ID가 할당을 제거하는 데 요청에서 사용됨.

예제 요청:

DELETE /api/access-control/users/1/roles/AFUXBHKnk
Accept: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role removed from user."
}

상태 코드:

Code	Description
200	Role is unassigned.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

사용자 역할 할당 설정

PUT /api/access-control/users/:userId/roles

사용자의 역할 할당이 제공된 UID 집합과 일치하도록 업데이트해요. 요청에 없는 할당된 역할은 제거하고, 집합에 있지만 아직 사용자에게 할당되지 않은 역할은 추가해요.

단일 역할을 추가하거나 제거하려면 "Add a user role assignment" 또는 "Remove a user role assignment"를 대신 사용해요.

필요한 권한:

permissions:type:delegate scope는 사용자가 자신이 가진 권한과 같거나 그 부분집합인 역할만 할당하거나 할당 해제할 수 있게 해요. 예를 들어 사용자가 사용자 생성에 필요한 권한이 없다면, 그렇게 할 수 있게 하는 역할도 할당하거나 할당 해제할 수 없어요. 이는 권한 상승을 방지하기 위함이에요.

Action	Scope
users.roles:add	permissions:type:delegate
users.roles:remove	permissions:type:delegate

예제 요청:

PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

JSON body 스키마:

Field Name	Date Type	Required	Description
global	boolean	No	할당이 글로벌인지 여부를 나타내는 플래그. false로 설정하면 인증된 사용자의 기본 org ID가 요청에서 사용됨.
roleUids	list	Yes	역할 UID 목록.
includeHidden	boolean	No	숨겨진 역할 할당을 업데이트할지 여부를 지정함.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "User roles have been updated."
}

상태 코드:

Code	Description
200	Roles have been assigned.
403	Access denied.
404	Role not found.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

서비스 계정 역할 할당 생성 및 제거

서비스 계정에 할당된 역할 나열

GET /api/access-control/users/:serviceAccountId/roles

주어진 서비스 계정에 직접 할당된 역할을 나열해요. 이 목록에는 기본 역할(Viewer, Editor, Admin 또는 Grafana Admin)이 포함되지 않아요.

쿼리 매개변수:

includeHidden: 선택 사항. hidden인 역할을 포함하려면 true로 설정.

필요한 권한:

Action	Scope
users.roles:read	users:id:<service account ID>

예제 요청:

GET /api/access-control/users/1/roles
Accept: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 4,
        "uid": "6dNwJq57z",
        "name": "fixed:reports:writer",
        "displayName": "Report writer",
        "description": "Create, read, update, or delete all reports and shared report settings.",
        "group": "Reports",
        "updated": "2021-11-19T10:48:00+01:00",
        "created": "2021-11-19T10:48:00+01:00",
        "global": false
    }
]

상태 코드:

Code	Description
200	할당된 역할 집합이 반환됨.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

서비스 계정에 할당된 권한 나열

GET /api/access-control/users/:serviceAccountId/permissions

주어진 서비스 계정이 가진 권한을 나열해요.

필요한 권한:

Action	Scope
users.permissions:read	users:id:<service account ID>

예제 요청:

GET /api/access-control/users/1/permissions
Accept: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "action": "ldap.status:read",
        "scope": ""
    },
    {
        "action": "ldap.user:read",
        "scope": ""
    }
]

상태 코드:

Code	Description
200	할당된 권한 집합이 반환됨.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

서비스 계정 역할 할당 추가

POST /api/access-control/users/:serviceAccountId/roles

특정 서비스 계정에 역할을 할당해요.

일괄 업데이트에는 "Set service account role assignments"를 고려해요.

필요한 권한:

Action	Scope
users.roles:add	permissions:type:delegate

예제 요청:

POST /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUid": "XvHQJq57z"
}

JSON body 스키마:

Field Name	Data Type	Required	Description
roleUid	string	Yes	역할의 UID.
global	boolean	No	할당이 글로벌인지 여부를 나타내는 플래그. false로 설정하면 인증된 사용자의 기본 org ID가 조직 로컬 할당을 생성하는 데 요청에서 사용됨.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the user."
}

상태 코드:

Code	Description
200	Role is assigned to a user.
403	Access denied.
404	Role not found.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

서비스 계정 역할 할당 제거

DELETE /api/access-control/users/:serviceAccountId/roles/:roleUID

서비스 계정으로부터 역할을 회수해요.

일괄 업데이트에는 "Set service account role assignments"를 고려해요.

필요한 권한:

Action	Scope
users.roles:remove	permissions:type:delegate

쿼리 매개변수:

Param	Type	Required	Description
global	boolean	No	할당이 글로벌인지 여부를 나타내는 플래그. false로 설정하면 인증된 사용자의 기본 org ID가 할당을 제거하는 데 요청에서 사용됨.

예제 요청:

DELETE /api/access-control/users/1/roles/AFUXBHKnk
Accept: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role removed from user."
}

상태 코드:

Code	Description
200	Role is unassigned.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

서비스 계정 역할 할당 설정

PUT /api/access-control/users/:serviceAccountId/roles

서비스 계정의 역할 할당이 제공된 UID 집합과 일치하도록 업데이트해요. 요청에 없는 할당된 역할은 제거하고, 집합에 있지만 아직 서비스 계정에 할당되지 않은 역할은 추가해요.

단일 역할을 추가하거나 제거하려면 "Add a service account role assignment" 또는 "Remove a service account role assignment"를 대신 사용해요.

필요한 권한:

Action	Scope
users.roles:add	permissions:type:delegate
users.roles:remove	permissions:type:delegate

예제 요청:

PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

JSON body 스키마:

Field Name	Date Type	Required	Description
global	boolean	No	할당이 글로벌인지 여부를 나타내는 플래그. false로 설정하면 인증된 사용자의 기본 org ID가 요청에서 사용됨.
roleUids	list	Yes	역할 UID 목록.
includeHidden	boolean	No	숨겨진 역할 할당을 업데이트할지 여부를 지정함.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "User roles have been updated."
}

상태 코드:

Code	Description
200	Roles have been assigned.
403	Access denied.
404	Role not found.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

팀 역할 할당 생성 및 제거

팀에 할당된 역할 나열

GET /api/access-control/teams/:teamId/roles

주어진 팀에 직접 할당된 역할을 나열해요.

쿼리 매개변수:

includeHidden: 선택 사항. hidden인 역할을 포함하려면 true로 설정.

필요한 권한:

Action	Scope
teams.roles:read	teams:id:<team ID>

예제 요청:

GET /api/access-control/teams/1/roles
Accept: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 4,
        "uid": "j08ZBi-nk",
        "name": "fixed:licensing:reader",
        "displayName": "Licensing reader",
        "description": "Read licensing information and licensing reports.",
        "group": "Licenses",
        "updated": "2022-02-03T14:19:50+01:00",
        "created": "0001-01-01T00:00:00Z",
        "global": false
    }
]

상태 코드:

Code	Description
200	할당된 역할 집합이 반환됨.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

팀 역할 할당 추가

POST /api/access-control/teams/:teamId/roles

특정 팀에 역할을 할당해요.

일괄 업데이트에는 "Set team role assignments"를 고려해요.

필요한 권한:

permissions:type:delegate scope는 사용자가 자신이 가진 권한과 같거나 그 부분집합인 역할만 할당할 수 있게 해요. 예를 들어 사용자가 사용자 생성에 필요한 권한이 없다면, 이러한 권한을 포함하는 역할도 할당할 수 없어요. 이는 권한 상승을 방지하기 위함이에요.

Action	Scope
teams.roles:add	permissions:type:delegate

예제 요청:

POST /api/access-control/teams/1/roles
Accept: application/json
Content-Type: application/json

{
    "roleUid": "XvHQJq57z"
}

JSON body 스키마:

Field Name	Data Type	Required	Description
roleUid	string	Yes	역할의 UID.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the team."
}

상태 코드:

Code	Description
200	Role is assigned to a team.
403	Access denied.
404	Role not found.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

팀 역할 할당 제거

DELETE /api/access-control/teams/:teams/roles/:roleUID

팀으로부터 역할을 회수해요.

일괄 업데이트에는 "Set team role assignments"를 고려해요.

필요한 권한:

permissions:type:delegate scope는 사용자가 자신이 가진 권한과 같거나 그 부분집합인 역할만 할당 해제할 수 있게 해요. 예를 들어 사용자가 사용자 생성에 필요한 권한이 없다면, 이러한 권한을 포함하는 역할도 할당할 수 없어요. 이는 권한 상승을 방지하기 위함이에요.

Action	Scope
teams.roles:remove	permissions:type:delegate

예제 요청:

DELETE /api/access-control/teams/1/roles/AFUXBHKnk
Accept: application/json

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role removed from team."
}

상태 코드:

Code	Description
200	Role is unassigned.
403	Access denied.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

팀 역할 할당 설정

PUT /api/access-control/teams/:teamId/roles

팀의 역할 할당이 제공된 UID 집합과 일치하도록 업데이트해요. 요청에 없는 할당된 역할은 제거하고, 집합에 있지만 아직 사용자에게 할당되지 않은 역할은 추가해요.

단일 역할을 추가하거나 제거하려면 "Add a team role assignment" 또는 "Remove a team role assignment"를 대신 사용해요.

필요한 권한:

permissions:type:delegate scope는 사용자가 자신이 가진 권한과 같거나 그 부분집합인 역할만 할당하거나 할당 해제할 수 있게 해요. 예를 들어 사용자가 사용자 생성에 필요한 권한이 없다면, 그렇게 할 수 있게 하는 역할도 팀에 할당하거나 할당 해제할 수 없어요. 이는 권한 상승을 방지하기 위함이에요.

Action	Scope
teams.roles:add	permissions:type:delegate
teams.roles:remove	permissions:type:delegate

예제 요청:

PUT /api/access-control/teams/1/roles
Accept: application/json
Content-Type: application/json

{
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

JSON body 스키마:

Field Name	Date Type	Required	Description
roleUids	list	Yes	역할 UID 목록.
includeHidden	boolean	No	숨겨진 역할 할당을 업데이트할지 여부를 지정함.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Team roles have been updated."
}

상태 코드:

Code	Description
200	Roles have been assigned.
403	Access denied.
404	Role not found.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

기본 역할을 기본값으로 재설정

POST /api/access-control/roles/hard-reset

permissions:type:escalate scope는 사용자가 기본 역할 권한을 재설정할 수 있게 해요. 이로 인해 기본 역할의 권한이 호출자의 권한을 초과할 수 있어요.

기본 역할 권한을 기본값으로 재설정해요.

필요한 권한:

Action	Scope
roles:write	permissions:type:escalate

예제 요청:

POST /api/access-control/roles/hard-reset
Accept: application/json
Content-Type: application/json

{
    "BasicRoles": true
}

JSON body 스키마:

Field Name	Data Type	Required	Description
BasicRoles	boolean	No	기본 역할 권한을 재설정하는 옵션.

예제 응답:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Reset performed"
}

상태 코드:

Code	Description
200	Reset performed
500	기본 역할 재설정 실패

더 알아보기 (Learn more)

역할 기반 접근 제어 (RBAC) 개요
사용자 정의 역할 action 및 scope
Grafana의 새 API 구조