Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

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

FOSS tool to sync teams, users and folders from different sources to Grafana without the need for an enterprise license
https://github.com/skuethe/grafana-oss-team-sync

entraid grafana grafana-oss sync team-sync

Last synced: about 1 month ago
JSON representation

FOSS tool to sync teams, users and folders from different sources to Grafana without the need for an enterprise license

Awesome Lists containing this project

README 

          











  

  
Grafana OSS Team Sync


  


    Report a Bug

    ·

    Request a Feature

    


    



[![Go Report Card][goreportcardbadge]][goreportcardlink]

[![REUSE status][reusebadge]][reuselink]

![GitHub License][githublicensebadge]



  





  Table of Contents

   

  







## 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](#contributing) 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][enterprisefeature] 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][githubpackagelink] 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:

```script

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][githublatestrelease] 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](#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`[^authfilehirarchy]



[^authfilehirarchy]: We are using [godotenv][godotenv], which will **NOT** override existing environment variables.  



| 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][setupssoauth] with the same source as your group and user sync



| Requirements   | |

|--------------- |-|

| Version        | `>= 11.1.0` [^grafanaversion]  |

| Authentication | Using either one of the [available authentication options][availableauthoptions] `basic auth` or `service account token` [^grafanatokenauth] |



| 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` |



[^grafanaversion]: Minimum Grafana version is `11.1.0` as it introduced [a new bulk team membership endpoint][newbulkendpoint] we are currently using.  

[^grafanatokenauth]: 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][requirebasicauth].



### Source: `entraid`



If you have [enabled EntraID OAuth][entraidoauth] 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][entraidoauthconfig], 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][setupssoauth] 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

  ```shell

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

  cd grafana-oss-team-sync

  ```

2. Build the binary

  ```shell

  CGO_ENABLED=0 go build .

  ```

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

  ```shell

  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`](CONTRIBUTING.md) for more information.



( Back to top )



## Versioning



This projects uses [Semantic Versioning ("SemVer")][semver] for releases.  

All available versions can be found on the [releases page][githubreleases].



( 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][spdxopenstandard]. It is also [`REUSE`-compliant][reusecompliant]



See [`LICENSE`](LICENSE.md) for more information.



( Back to top )



[goreportcardbadge]:     "Go Report Card: badge"

[goreportcardlink]:      "Go Report Card: link"

[reusebadge]:            "REUSE: badge"

[reuselink]:             "REUSE: link"

[githublicensebadge]:    "License"



[githubpackagelink]:     "grafana-oss-team-sync package"

[githublatestrelease]:   "Latest grafana-oss-team-sync release"

[godotenv]:              "GoDotEnv"

[enterprisefeature]:     "Grafana Enterprise - Team Sync"

[availableauthoptions]:  "Authentication options for the HTTP API"

[newbulkendpoint]:       "Team: Add an endpoint for bulk team membership updates"

[requirebasicauth]:      "Admin API"

[setupssoauth]:          "Configure authentication"

[entraidoauth]:          "Entra ID OAuth authentication"

[entraidoauthconfig]:    "Entra ID OAuth - Configuration options"

[semver]:                "Semantic Versioning"

[githubreleases]:        "Releases"

[spdxopenstandard]:      "The System Package Data Exchange™"

[reusecompliant]:        "REUSE SOFTWARE - an initiative by the Free Software Foundation Europe"