Grafana

This guide explains how to set up Single Sign-On (SSO) between SmartLink and Grafana using OpenID Connect. Grafana provides excellent native support for OAuth2/OpenID Connect.

Prerequisites

• Grafana version 7.0 or higher
• Administrative access to Grafana
• Application configured in SmartLink with OpenID Connect
• HTTPS configured on Grafana (recommended)

Configuration in SmartLink

1. Create the application

1. Log in to SmartLink as an administrator
2. Go to Applications → Add
3. Create a new application:
   • Name: Grafana
   • URL: https://grafana.example.com
   • Description: Monitoring and observability platform
   • Icon: Choose the Grafana icon

2. Configure OpenID Connect

1. In the Authentication tab
2. Select OpenID Connect
3. Note the information:
   • Client ID: grafana-xxxxxx
   • Client Secret: secret-xxxxxx
   • Issuer URL: https://your-smartlink.link.vaultys.org/api/oidc/[appid]
   • App ID: [appid] (unique identifier of the application in SmartLink)

3. Redirect URLs

Add to Allowed Redirect URLs:

https://grafana.example.com/login/generic_oauth

4. Scopes and claims

Required scopes:

• openid
• profile
• email
• groups (for role mapping)

Configuration in Grafana

1. Configuration via INI file

Edit /etc/grafana/grafana.ini or /conf/grafana.ini:

#################################### Auth ####################################
[auth]
# Disable account creation via the interface
disable_login_form = false
disable_signout_menu = false
# OAuth auto login
oauth_auto_login = true
# Automatic team synchronization
oauth_allow_insecure_email_lookup = false

#################################### Generic OAuth ##########################
[auth.generic_oauth]
enabled = true
name = SmartLink SSO
allow_sign_up = true
auto_login = false
client_id = grafana-xxxxxx
client_secret = secret-xxxxxx
scopes = openid profile email groups
email_attribute_name = email
email_attribute_path = email
login_attribute_path = email
name_attribute_path = name
groups_attribute_path = groups
role_attribute_path = contains(groups[*], 'grafana-admins') && 'Admin' || contains(groups[*], 'grafana-editors') && 'Editor' || 'Viewer'
role_attribute_strict = false
allow_assign_grafana_admin = true
auth_url = https://your-smartlink.link.vaultys.org/api/oidc/[appid]/authorize
token_url = https://your-smartlink.link.vaultys.org/api/oidc/[appid]/token
api_url = https://your-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
signout_redirect_url = https://your-smartlink.link.vaultys.org/logout
use_pkce = true
use_refresh_token = true

# Team mapping (optional)
team_ids_attribute_path = groups
teams_url = https://your-smartlink.link.vaultys.org/api/teams

2. Configuration via environment variables

For Docker or Kubernetes:

version: '3.8'
services:
  grafana:
    image: grafana/grafana:latest
    environment:
      # OAuth configuration
      - GF_AUTH_GENERIC_OAUTH_ENABLED=true
      - GF_AUTH_GENERIC_OAUTH_NAME=SmartLink SSO
      - GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP=true
      - GF_AUTH_GENERIC_OAUTH_CLIENT_ID=grafana-xxxxxx
      - GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=secret-xxxxxx
      - GF_AUTH_GENERIC_OAUTH_SCOPES=openid profile email groups
      - GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_NAME=email
      - GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_PATH=email
      - GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH=email
      - GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH=name
      - GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://your-smartlink.link.vaultys.org/api/oidc/[appid]/authorize
      - GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://your-smartlink.link.vaultys.org/api/oidc/[appid]/token
      - GF_AUTH_GENERIC_OAUTH_API_URL=https://your-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
      - GF_AUTH_GENERIC_OAUTH_USE_PKCE=true
      # Auto login
      - GF_AUTH_OAUTH_AUTO_LOGIN=true
      # Disable anonymous authentication
      - GF_AUTH_ANONYMOUS_ENABLED=false
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana

volumes:
  grafana-data:

3. Helm Configuration (Kubernetes)

# values.yaml for Grafana chart
grafana:
  grafana.ini:
    auth:
      oauth_auto_login: true
    auth.generic_oauth:
      enabled: true
      name: SmartLink SSO
      allow_sign_up: true
      client_id: grafana-xxxxxx
      client_secret: secret-xxxxxx
      scopes: openid profile email groups
      auth_url: https://your-smartlink.link.vaultys.org/api/oidc/[appid]/authorize
      token_url: https://your-smartlink.link.vaultys.org/api/oidc/[appid]/token
      api_url: https://your-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
      role_attribute_path: |
        contains(groups[*], 'grafana-admins') && 'Admin' || 
        contains(groups[*], 'grafana-editors') && 'Editor' || 
        'Viewer'

Role and Permission Management

Automatic Role Mapping

Grafana supports three main roles: Admin, Editor, and Viewer.

Basic Configuration

# Default role for new users
[auth.generic_oauth]
role_attribute_path = contains(groups[*], 'grafana-admins') && 'Admin' || contains(groups[*], 'grafana-editors') && 'Editor' || 'Viewer'

Advanced Configuration with JMESPath

# Complex mapping based on multiple attributes
role_attribute_path = |
  (contains(groups[*], 'grafana-super-admins') || email == 'admin@example.com') && 'GrafanaAdmin' ||
  contains(groups[*], 'grafana-admins') && 'Admin' ||
  contains(groups[*], 'grafana-editors') && 'Editor' ||
  contains(groups[*], 'grafana-viewers') && 'Viewer' ||
  'Viewer'

Organization Synchronization

For multi-tenant environments:

[auth.generic_oauth]
# Enable multi-organization support
org_attribute_path = organization
# Organization mapping
org_mapping = SmartLink:1:Editor, Marketing:2:Viewer, Engineering:3:Admin

Team Synchronization

[auth.generic_oauth]
# Automatic team synchronization
team_ids_attribute_path = groups
# Format: group:organization:team
teams_mapping = developers:1:Developers, operations:1:Operations

Automatic Provisioning

Dashboards and Datasources

Create /etc/grafana/provisioning/datasources/smartlink.yaml:

apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false

  - name: Loki
    type: loki
    access: proxy
    url: http://loki:3100
    editable: false

Team-Based Folder Configuration

# /etc/grafana/provisioning/dashboards/teams.yaml
apiVersion: 1

providers:
  - name: 'team-dashboards'
    orgId: 1
    folder: ''
    type: file
    disableDeletion: false
    updateIntervalSeconds: 10
    allowUiUpdates: true
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

Configuration Testing

1. Connection Test

1. Restart Grafana:

   systemctl restart grafana-server
   # or
   docker-compose restart grafana

2. Access https://grafana.example.com

3. Click on Sign in with SmartLink SSO

4. Authenticate through SmartLink

5. You should be logged in to Grafana

2. Permission Verification

# Using Grafana API
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://grafana.example.com/api/user

# Expected response
{
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "login": "johndoe",
  "role": "Admin",
  "isGrafanaAdmin": false
}

3. Role Testing

1. Log in with different users
2. Check permissions:
   • Admin: Can create/modify dashboards and datasources
   • Editor: Can create/modify dashboards
   • Viewer: Read-only access

Troubleshooting

Error "login.OAuthLogin(missing saved state)"

Issue: Session/cookies problem

Solution:

1. Check cookie configuration:

   [security]
   cookie_secure = true
   cookie_samesite = lax
2. Ensure HTTPS is used
3. Verify domain matching

Error "User not a member of one of the required organizations"

Issue: User lacks proper permissions

Solution:

1. Check user groups in SmartLink
2. Adjust role_attribute_path
3. Verify allow_sign_up = true

Groups not mapped correctly

Issue: Roles not assigned correctly

Solution:

1. Enable debug:

   [log]
   level = debug
   filters = auth.generic_oauth:debug
2. Check logs:

   tail -f /var/log/grafana/grafana.log | grep oauth
3. Test JMESPath on the UserInfo response

Error "Failed to get user info"

Issue: Grafana unable to retrieve user information

Solution:

1. Test the UserInfo endpoint:

   curl -H "Authorization: Bearer TOKEN" \
     https://your-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
2. Check api_url in the configuration
3. Verify requested scopes

Security

Recommendations

1. Mandatory HTTPS: Always use HTTPS
2. Enabled PKCE: use_pkce = true
3. Secure Cookies:

   [security]
   cookie_secure = true
   cookie_httponly = true
4. Limit Anonymous Viewers:

   [auth.anonymous]
   enabled = false
5. Audit Logs:

   [log]
   mode = file
   level = info
   [log.file]
   log_rotate = true
   max_lines = 1000000
   max_size_shift = 28
   daily_rotate = true
   max_days = 7

Protection Against Brute Force

[security]
# Enable brute force protection
disable_brute_force_login_protection = false
# Secret key for cookie signing
secret_key = YOUR_SECRET_KEY

Advanced Configuration

Multi-Tenancy with Organizations

[auth.generic_oauth]
# Automatically create organization if it does not exist
auto_assign_org = true
auto_assign_org_id = 1
# Organization mapping based on an attribute
org_attribute_path = organization
# Allow organization switching
allow_org_switch = true

Integration with Terraform

resource "grafana_folder" "team_folders" {
  for_each = var.teams
  title    = each.value.name
}

resource "grafana_team" "teams" {
  for_each = var.teams
  name     = each.value.name
  members  = each.value.members
}

resource "grafana_dashboard_permission" "team_permissions" {
  for_each     = var.teams
  dashboard_id = grafana_folder.team_folders[each.key].id
  permissions {
    team_id    = grafana_team.teams[each.key].id
    permission = "Edit"
  }
}

Authentication Monitoring

# Prometheus metrics for authentication
[metrics]
enabled = true
interval_seconds = 10

[metrics.graphite]
address = localhost:2003
prefix = prod.grafana.%(instance_name)s.

Resources

• Grafana Auth Documentation
• Generic OAuth Documentation
• JMESPath Documentation
• Grafana Forum