Grafana OSS Team Sync

Report a Bug · Request a 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 set-up as plug-ins, 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 "plug-in" feature.
Feel free to contribute your desired source.

This tool works with Grafana versions >=11.1.0.
We are running tests against versions v11.1.0, v12.0.0, v13.0.0 and latest

( 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 repository on GitHub. It is currently available for architectures linux/amd64 as well as linux/arm64.
You can start evaluating by using the latest tag and then switch to a release version. 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 favourite (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 installation method or OS architecture of choice, 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 command arguments.
The following hierarchy is used when merging different config sources, overriding already existing data (with the exception of the authfile in step 4):

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

Configuration	Configuration via	Description
Configuration file	argument: --config or -c env var: GOTS_CONFIG	Define the path to your config file (required)
Log level	config.yaml: loglevel argument: --loglevel or -l env var: GOTS_LOGLEVEL	Define the log level Type: int Allowed: 0 (INFO), 1 (WARN), 2 (ERROR), 99 (DEBUG) Default: 0 (INFO)
Source plug-in	config.yaml: source argument: --source or -s env var: GOTS_SOURCE	Define the source plug-in you want to use Type: string Allowed: entraid
Authentication file	config.yaml: authfile argument: --authfile env var: GOTS_AUTHFILE	Define 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 argument: --disablefolders env var: GOTS_DISABLEFOLDERS	Control the folder sync feature Type: bool Default: false
Feature: disable user sync	config.yaml: features.disableUserSync argument: --disableusersync env var: GOTS_DISABLEUSERSYNC	Control the user sync feature Type: bool Default: false
Feature: add local admin to teams	config.yaml: features.addLocalAdminToTeams argument: --addlocaladmintoteams env var: GOTS_ADDLOCALADMINTOTEAMS	Control adding Grafana local admin to each team Type: bool Default: true
Team sync	config.yaml: teams argument: --teams or -t env var: GOTS_TEAMS	Define the list of teams to sync Type: []string
Folder sync	config.yaml: folders	Define the list of folders to sync Type: []interface

Grafana

Ideally you have set-up SSO authentication with the same source as your group and user sync

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

Configuration	Configuration via	Description
Authentication Type	config.yaml: grafana.authtype argument: --authtype env var: GOTS_AUTHTYPE	Define the authentication type to use Type: string Allowed: basicauth, token Default: basicauth
Authentication: Basic Auth	argument: --username and --password or -u and -p env var: GOTS_USERNAME and GOTS_PASSWORD	Define user name and password for basic authentication to Grafana Type: string
Authentication: Service Account Token	argument: --token or -t env var: GOTS_TOKEN	Define token for service account token auth to Grafana Type: string
Connection: Scheme	config.yaml: grafana.connection.scheme argument: --scheme env var: GOTS_SCHEME	Define the scheme to use Type: string Allowed: http, https Default: http
Connection: Host	config.yaml: grafana.connection.host argument: --host or -h env var: GOTS_HOST	Define the host to use Type: string Default: localhost:3000
Connection: Base Path	config.yaml: grafana.connection.basepath argument: --basepath env var: GOTS_BASEPATH	Define the base path to use Type: string Default: /api
Connection: Retry	config.yaml: grafana.connection.retry argument: --retry or -r env var: GOTS_RETRY	Define 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
Authentication	Using Azure app via environment variables: CLIENT_ID, TENANT_ID, CLIENT_SECRET
Application 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 added additional users or changed their permission (to "admin" e.g.), 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 for example)
  • 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 command argument
• 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 set-up 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 repository

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 repository 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 available 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 basicauth. ↩