Grafana OSS Team Sync

Report Bug · Request Feature

Table of Contents

 

• About The Project
• Requirements
• Installation
• Configuration
• Grafana
• Source: EntraID
• Opinionated Behaviour
• Build It Yourself
• Contributing
• Versioning
• License

About The Project

I created this project to get into Go development and as such, it is probably far from being perfect. Keep an open mind to that and feel free to contribute if you want to optimize or extend its functionality.

The idea is to use grafana-oss-team-sync as an FOSS tool to create teams, users and even folders in Grafana and keep them (and their permissions) in sync with a configured source.
This functionality does exist in Grafana itself ("Team Sync"), but is a is an enterprise feature and as such only usable with an appropriate license key.

Sources are internally setup as plugins, which can be easily extended to others in the future.
Currently the following sources are supported:

• Entra ID (formerly "Azure Active Directory")

Current feature list

The list of features include:

• search your source for specific groups and create them as teams in your Grafana instance
• (optional) create users from each configured source group
• (optional) create folders from config input and add groups to the permission list as either a viewer, editor or admin role

Possible future improvements

Things which potentially will be added in the future:

• allow to reference users on folder permissions
• allow to reference roles on folder permissions
• allow to assign admin permissions to team members
• delete users and groups when removed from the source / sync list

( Back to top )

Requirements

In it's current state, only Microsoft Entra ID is available as a source for groups and users.
The idea is to add new sources in the future as a "plugin" feature.
Feel free to contribute your desired source.

This tool works with Grafana versions >=11.1.0.

( Back to top )

Installation

There are multiple ways of using this tool. The easiest option would be to use the ready-to-go container image which is automatically uploaded as a package to this repo on GitHub. It is currently available for architectures linux/amd64 as well as linux/arm64.
You can start by using latest tag for evaluation and then switch to a versioned release. Just have a look at available tags in the package linked above.
Example:

podman pull ghcr.io/skuethe/grafana-oss-team-sync:latest

As an alternative, you can download your favorite (linux) binary which is attached to each release. Have a look at the latest release to find your preferred one (currently building apk, deb and rpm for both linux/amd64 as well as linux/arm64).

If you are still missing your needed installation method or OS architecture, you can either Build It Yourself, or open a PR with an enhancement to the build-process (goreleaser).

( Back to top )

Configuration

The following tool specific configuration is available.
Details on Grafana and source specific requirements can be found below.

You can configure these either in the config.yaml, via environment variables (starting with GOTS_) or via cli flags.
The following hirarchy is used when merging the different config sources, overriding existing data:

1. The config.yaml you specify
2. Environment variables set (also respecting a .env file)
3. CLI flags passed
4. (Optional) content from an authfile¹

Configuration	Config via	Description
Log level	config.yaml: loglevel flag: --loglevel or -l env var: GOTS_LOGLEVEL	Configure the log level Type: int Allowed: 0 (INFO), 1 (WARN), 2 (ERROR), 99 (DEBUG) Default: 0 (INFO)
Source plugin	config.yaml: source flag: --source or -s env var: GOTS_SOURCE	Configure the source plugin you want to use Type: string Allowed: entraid
Auth file	config.yaml: authfile flag: --authfile env var: GOTS_AUTHFILE	Configure an optional file to load authentication data from. File content needs to be in .env syntax (so key=value per line) Type: string
Feature: disable folder sync	config.yaml: features.disableFolders flag: --disablefolders env var: GOTS_DISABLEFOLDERS	Control the folder sync feature Type: bool Default: false
Feature: disable user sync	config.yaml: features.disableUserSync flag: --disableusersync env var: GOTS_DISABLEUSERSYNC	Control the user sync feature Type: bool Default: false
Feature: add local admin to teams	config.yaml: features.addLocalAdminToTeams flag: --addlocaladmintoteams env var: GOTS_ADDLOCALADMINTOTEAMS	Control adding Grafana local admin to each team Type: bool Default: true
Team sync	config.yaml: teams flag: --teams or -t env var: GOTS_TEAMS	Configure the list of teams to sync Type: []string
Folder sync	config.yaml: folders	Configure the list of folders to sync Type: []interface

Grafana

Ideally you have setup SSO authentication with the same source as your group and user sync

Requirements
Version	>= 11.1.0 2
Auth	Using either one of the available authentication options basic auth or service account token 3

Configuration	Config via	Description
Auth Type	config.yaml: grafana.authtype flag: --authtype env var: GOTS_AUTHTYPE	Configure the auth type to use Type: string Allowed: basicauth, token Default: basicauth
Auth: Basic Auth	flag: --username and --password or -u and -p env var: GOTS_USERNAME and GOTS_PASSWORD	Set username and password for basic authentication to Grafana Type: string
Auth: Service Account Token	flag: --token or -t env var: GOTS_TOKEN	Set token for service account token auth to Grafana Type: string
Connection: Scheme	config.yaml: grafana.connection.scheme flag: --scheme env var: GOTS_SCHEME	Configure the scheme to use Type: string Allowed: http, https Default: http
Connection: Host	config.yaml: grafana.connection.host flag: --host or -h env var: GOTS_HOST	Configure the host to use Type: string Default: localhost:3000
Connection: Base Path	config.yaml: grafana.connection.basepath flag: --basepath env var: GOTS_BASEPATH	Configure the base path to use Type: string Default: /api
Connection: Retry	config.yaml: grafana.connection.retry flag: --retry or -r env var: GOTS_RETRY	Configure the connection retry, waiting 2 seconds in between each. Only used when the return status code equals 429 or 5xx Type: int Default: 0

Source: entraid

If you have enabled EntraID OAuth for SSO authentication in Grafana with the same entraid tenant, it is possible to set allow_sign_up = false in your EntraID OAuth configuration options, so that only users which are synced by Grafana OSS Team Sync are able to log into your Grafana instance.

Requirements
Auth	Using Azure app via env variables: CLIENT_ID, TENANT_ID, CLIENT_SECRET
App permissions	Minimum: User.ReadBasic.All, GroupMember.Read.All To list the members of a hidden membership group, the Member.Read.Hidden permission is required

( Back to top )

Opinionated Behaviour

Please note the following opinionated behaviour of this tool.

• this tool should be the single point of truth for creating groups in Grafana. For that matter, we are enforcing the following:
  • Teams: all members of each configured team are completely overridden with matching users from the source. If you, f.e. added other additional users or canged their permission (to "admin" f.e.), these changes will be lost during the next sync operation. This also helps with keeping the groups up to date with your configured source (when removing users f.e.)
  • Folders: the permissions of each folder are completely overridden with the input from your config. If you don't want this to happen, you can always disable the folder sync feature via config / env variable or cli flag
• if the user sync feature is enabled, all newly created users will get a randomly generated password assigned. This password is not available afterwards, as it should not be used in the first place. Ideally you have setup SSO authentication with the same source as your group and user sync

( Back to top )

Build It Yourself

If you want to build the project yourself, do the following

1. Clone this repo

git clone https://github.com/skuethe/grafana-oss-team-sync.git
cd grafana-oss-team-sync

2. Build the binary

CGO_ENABLED=0 go build .

3. Create the container image (adapt to your preferred tool for creating images)

podman build -t localhost/grafana-oss-team-sync:dev -f build/package/Dockerfile .

( Back to top )

Contributing

Contributions are what makes the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

See CONTRIBUTING for more information.

( Back to top )

Versioning

This projects uses Semantic Versioning ("SemVer") for releases.
All avialable versions can be found on the releases page.

( Back to top )

License

Distributed under the GNU General Public License v3.0 or later ("GPL-3.0-or-later").
This project adheres to the SPDX® open standard. It is also REUSE-compliant

See LICENSE for more information.

( Back to top )

Footnotes

1. We are using godotenv, which will NOT override existing environment variables. ↩

2. Minimum Grafana version is 11.1.0 as it introduced a new bulk team membership endpoint we are currently using. ↩

3. Please note that service account token auth only works if you disable the UserSync feature, as creating new users in Grafana uses the Admin API, which requires the usage of basic auth. ↩