Skip to main content

User Management and Permissions

In this lesson, we'll explore how to manage users and control access to your Grafana instance. As your monitoring setup grows, you'll need to onboard team members, assign appropriate permissions, and secure sensitive dashboards and data sources.

Learning Goals:

  • Understand Grafana's user roles and permission system
  • Create and manage user accounts
  • Assign permissions to dashboards, folders, and data sources
  • Configure authentication providers
  • Implement team-based access control

User Roles and Permissions​

Grafana provides four built-in roles with hierarchical permissions:

  • Viewer: Can view dashboards and explore data
  • Editor: Can create and edit dashboards
  • Admin: Full access to all organization resources
  • Grafana Admin: Superuser with access to all organizations
View current user role
# Check your current permissions in Grafana UI
# Navigate to Configuration -> Users in the sidebar
# Your role is displayed in the users table
note

Role hierarchy matters: Admin includes Editor permissions, which includes Viewer permissions. You cannot assign partial permissions outside this hierarchy.

Managing User Accounts​

Creating Local Users​

Create user via API
curl -X POST http://localhost:3000/api/admin/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "John Doe",
    "email": "john@company.com",
    "login": "johndoe",
    "password": "securepassword123"
  }'

Updating User Roles​

Update user role to Editor
curl -X PATCH http://localhost:3000/api/org/users/123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "role": "Editor"
  }'

Folder and Dashboard Permissions​

Setting Folder Permissions​

Folders inherit permissions from the organization level, but you can override them for specific teams or users.

Set folder permissions via API
const folderPermissions = {
  items: [
    {
      role: "Viewer",
      permission: 1 // 1 = View
    },
    {
      teamId: 2,
      permission: 2 // 2 = Edit
    },
    {
      userId: 5,
      permission: 4 // 4 = Admin
    }
  ]
};

// Apply permissions to folder
fetch('/api/folders/uid:main-dashboards/permissions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify(folderPermissions)
});
tip

Use folder-level permissions instead of individual dashboard permissions for better maintainability. This way, you can manage access to groups of related dashboards at once.

Dashboard Permission Levels​

  • View (1): Can view the dashboard
  • Edit (2): Can edit and save the dashboard
  • Admin (4): Can manage permissions and delete the dashboard

Team-Based Access Control​

Teams allow you to manage permissions for groups of users rather than individuals.

Create a new team
curl -X POST http://localhost:3000/api/teams \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Platform Engineering",
    "email": "platform@company.com"
  }'
Add user to team
curl -X POST http://localhost:3000/api/teams/2/members \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": 123
  }'

Data Source Permissions​

Control which users or teams can access specific data sources.

Restrict data source access
// Make PostgreSQL datasource accessible only to specific team
const dsPermissions = {
  enabled: true,
  permissions: [
    {
      teamId: 2,
      permission: 1 // 1 = Query
    }
  ]
};

fetch('/api/datasources/uid:postgres-prod/permissions', {
  method: 'POST', 
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify(dsPermissions)
});

Authentication Providers​

Grafana supports multiple authentication methods. Here's how to configure OAuth with GitHub:

grafana.ini - GitHub OAuth
[auth.github]
enabled = true
client_id = YOUR_GITHUB_CLIENT_ID
client_secret = YOUR_GITHUB_CLIENT_SECRET
scopes = user:email,read:org
auth_url = https://github.com/login/oauth/authorize
token_url = https://github.com/login/oauth/access_token
api_url = https://api.github.com/
team_ids =
allowed_organizations = my-company
grafana.ini - LDAP Auth
[auth.ldap]
enabled = true
config_file = /etc/grafana/ldap.toml

Common Pitfalls​

  • Over-assigning Admin roles: Start users with Viewer roles and escalate only when necessary
  • Ignoring team management: Managing users individually becomes unmaintainable beyond 10-15 users
  • Mixed permission sources: When using external auth, ensure role mappings are clear and consistent
  • Forgetting data source permissions: Users might see dashboards but get "data source not found" errors
  • Not testing user experience: Always verify permissions work as expected by testing with different user roles

Summary​

Effective user management in Grafana involves understanding the role hierarchy, using teams for scalable permission management, and applying permissions at the appropriate level (organization, folder, or dashboard). Remember to leverage external authentication providers for enterprise environments and always follow the principle of least privilege when assigning permissions.

Quiz​

Show quiz

  1. What is the correct hierarchy of Grafana's built-in roles from least to most privileged?

    • A) Viewer → Admin → Editor → Grafana Admin
    • B) Viewer → Editor → Admin → Grafana Admin
    • C) Editor → Viewer → Admin → Grafana Admin
    • D) All roles have equal but different privileges

  2. Which permission level allows a user to manage permissions on a dashboard?

    • A) View (1)
    • B) Edit (2)
    • C) Admin (4)
    • D) Owner (8)

  3. True or False: Folder permissions automatically apply to all dashboards within that folder.

    • A) True
    • B) False

  4. What is the main advantage of using Teams for permission management?

    • A) Teams have higher permissions than individual users
    • B) Teams allow you to manage permissions for groups rather than individuals
    • C) Teams bypass the need for user authentication
    • D) Teams can only be used with external authentication providers

Answers:

  1. B) Viewer → Editor → Admin → Grafana Admin
  2. C) Admin (4)
  3. A) True
  4. B) Teams allow you to manage permissions for groups rather than individuals