Grafana login with GitHub or GitLab OAuth for engineering teams
A platform or SRE team often wants engineers to sign in to self-hosted Grafana with the code platform they already use. GitHub and GitLab OAuth are supported in all Grafana editions, and access can be limited by GitHub organization or GitLab group, so the integration does not require Grafana Enterprise to start. The integration handles OAuth sign-in, restricts who may log in to members of allowed organizations or groups, and assigns a Grafana role based on the identity the provider returns. Users sign in with their existing code platform account, and Grafana creates the local user on first login.
What the open-source edition does not provide matters as much as what it does. According to the Grafana authentication docs, team sync, SAML, active sync and SCIM provisioning are available only in Grafana Enterprise and Grafana Cloud. In practice, this means group membership is not synchronized into Grafana teams, and removing someone from a GitHub organization or GitLab group does not automatically remove their Grafana account or update its teams. Your team should decide how it will handle offboarding, for example by disabling accounts on a schedule or reviewing active users, and confirm the current allowed-group and role settings in the Grafana authentication docs for the version you run.
Choose this path when your engineers already live in one code platform and the access model is simple: who may view dashboards, and who may edit them. Put a central identity provider in front of Grafana instead when you need SAML, automated provisioning and deprovisioning, team-level access tied to directory groups, or one login across many internal tools. Before you commit, confirm with the platform owners how group membership is managed and who can change it, because Grafana will trust whatever the code platform reports.
What the team needs before enabling GitHub or GitLab sign-in
Enabling GitHub or GitLab sign-in touches the Grafana version, its database, its public address and the source identity system at the same time. Confirm each of the items below before changing any authentication settings, because a mismatch in one usually surfaces as a failed login rather than a clear error.
A confirmed Grafana version and edition
Pick the Grafana release your organization will run and check it against the releases page before you plan the change. GitHub and GitLab OAuth are available in the open-source edition, while team sync and SAML are not, so confirm the edition you have. Record the exact version in the change request, since the authentication settings and callback behavior are documented per release line.
A production database
Grafana stores users, sessions and OAuth-linked accounts in its configuration database. SQLite is not supported for production, so confirm that you run MySQL 8.0 or later or PostgreSQL 12 or later. If you plan two or more Grafana servers behind a load balancer, the database must be shared, because database-backed auth tokens are what let a signed-in user reach any node.
A public HTTPS root URL
The OAuth provider redirects users back to Grafana's callback address, so Grafana needs a stable public root URL with HTTPS. Confirm the value you will set for the root URL and whether it sits behind a reverse proxy or load balancer. A change to the hostname later means updating the OAuth application as well, so settle the address before registration.
An OAuth application with the right callback path
Register an OAuth application in GitHub or GitLab that points to the callback path Grafana expects for that provider. Use the exact path from the Grafana authentication docs, not one copied from a blog post, and confirm the redirect URL matches your root URL character for character. Store the client ID and secret in a secrets store, not in plain configuration files.
Owner and admin rights in the source system
Registering the application usually requires an owner account on the GitHub organization or a group Owner or Maintainer role in GitLab. Reading organization or group membership for role mapping needs read access that users in the identity source may not have by default. Confirm which account will register the app, who can read membership, and that a second administrator can recover access if the mapping locks out the team.
How to configure Grafana sign-in with GitHub or GitLab
This sequence takes a self-hosted Grafana instance from an unconfigured login page to a working OAuth sign-in restricted to the GitHub organization or GitLab group your engineers belong to. Each step ends with a check you can run before moving on.
Register the OAuth application at the provider
An engineer with owner or admin rights on the GitHub organization or the GitLab group creates an OAuth application for Grafana. Set the homepage URL to your Grafana root URL and the callback URL to the path Grafana documents for the GitHub or GitLab provider, using the exact host name users will type in their browser. Copy the client ID and client secret the provider generates. The step is done when the application appears in the provider's settings with the callback URL you intended, and you can see the client ID listed.
Store the client ID and secret outside plain config
Put the client secret into a secret store your platform team already operates, or into an environment variable injected at runtime, rather than pasting it into grafana.ini. Grafana reads values from environment variables that follow its configuration naming convention, so confirm the variable name for your version in the Grafana configuration documentation. Restrict read access to the file or secret store to the service account running Grafana. The check is that a search of your configuration repository and host files finds no plain-text secret, and that Grafana starts with the variable set.
Enable the provider in the authentication settings
Edit the Grafana configuration to enable the provider under the auth.github section for GitHub or the auth.gitlab section for GitLab. Set enabled, the client ID and the client secret reference, and the scopes the provider requires. For GitLab self-managed instances, also set the base URL of your GitLab server. Key names change between Grafana releases, so confirm each one against the version you run before you restart the service. The check is that the Grafana login page shows the new sign-in button after restart and that the server log records no configuration errors for the provider.
Restrict sign-in to allowed organizations or groups
Set the allowed_organizations option under auth.github, or the allowed_groups option under auth.gitlab, to the organization or group your engineers belong to. Without this restriction, any account the provider authenticates can reach your instance, so treat this step as a access control requirement rather than a convenience. Confirm how the provider reports membership for your plan and visibility settings, because private membership can prevent Grafana from seeing it. The check is that one account inside the allowed set signs in successfully and that an account outside the set is refused at the login screen.
Set the default role and role mapping
Choose the role new OAuth users receive by setting auto sign-up and the default role for the instance and organization. Then decide whether role assignment should come from provider group or team membership, which requires a role mapping expression. Confirm which mapping options your edition and version support for these providers, since the Grafana authentication documentation lists the features available in each edition. Keep the default role at Viewer until mappings are tested. The check is that a user with no mapped group lands with the default role and cannot change dashboards or data sources.
Test with a non-admin account
Sign in with a standard engineer account from the allowed set, not with the local admin account or the account that configured Grafana. Confirm the user gets the expected organization and role, can open the dashboards intended for them, and cannot reach server administration pages. Then sign in with an account outside the allowed set and confirm it is refused. Record both results with the date and the Grafana version so the test can be repeated after upgrades. The step is complete when both checks match your written access expectations.
Which provider attributes map to Grafana access
This table compares the GitHub and GitLab attributes that can gate sign-in or set access in self-hosted Grafana, and the Grafana settings that act on them. Read each row as a question to answer before rollout: which attribute your provider can send, which Grafana option consumes it, and whether your Grafana version and edition support that option for that provider.
| Provider attribute or membership | Grafana setting | What it controls | What to confirm |
|---|---|---|---|
| GitHub organization membership | allowed_organizations in the GitHub auth section | Limits sign-in to users who belong to the listed GitHub organizations, so people outside those organizations cannot log in. | Confirm the key name and behavior in the authentication docs for your version, and whether members with private membership are matched. |
| GitHub team membership | team_ids in the GitHub auth section | Restricts sign-in to members of specific teams, which requires team IDs rather than team names. Team-based role mapping may need a separate option. | Confirm the team ID format, how nested teams are handled, and whether team membership can set the role or only gate access. |
| GitLab group membership | allowed_groups in the GitLab auth section | Limits sign-in to members of listed GitLab groups, including subgroups if your GitLab version includes them in the group path check. | Confirm the group path format, whether subgroup membership counts, and whether the instance is self-managed or GitLab.com. |
| Account email | Email returned by the OAuth provider, stored on the Grafana user record | Grafana needs an email for each OAuth user to create and match the user record. A missing or private email can block sign-in or create duplicate accounts. | Confirm the OAuth scope that returns email for your provider and whether private or unverified emails are accepted by your policy. |
| Default role for new users | Default organization role for OAuth users in the auth settings | Sets the role a user receives when no role mapping applies, so a sign-in that matches no rule still lands at a known permission level. | Confirm the setting name and default value for your version, and whether role mapping from provider attributes is available for GitHub or GitLab in your edition. |
| Grafana organization on first sign-in | Auto-assigned organization and org mapping options | Determines which Grafana organization a new user joins, which controls the dashboards and data sources they can see. | Confirm whether org mapping from provider attributes is supported for GitHub and GitLab, or whether users must be moved to organizations by an administrator. |
Security controls for OAuth sign-in to Grafana
GitHub and GitLab sign-in puts the provider in charge of who can reach Grafana, so the controls below focus on limiting which accounts get in, what they receive once inside, and how quickly access ends. Several controls sit on the Grafana side, while others depend on how the provider application and its groups are administered.
Restrict allowed organizations or groups
Set the allowed organizations or groups in the Grafana OAuth settings so that only members of approved GitHub organizations or GitLab groups can complete sign-in. Without this restriction, any account the provider authenticates may be able to reach your instance, depending on how the OAuth application is configured. Test the restriction with a user who is outside the approved group, and confirm the behavior against the current Grafana authentication docs for your version.
Keep the client secret out of source control
The OAuth client secret lets Grafana exchange sign-in codes with GitHub or GitLab, so anyone holding it can impersonate your application. Supply it through environment variables, a secrets manager or a restricted provisioning file rather than committing grafana.ini or a Helm values file with the value inline. Rotate the secret if it has ever appeared in a repository, a chat log or a ticket, and check your Git history before you rely on the new value.
Serve Grafana over HTTPS with secure cookies
OAuth redirects and session cookies must travel over HTTPS, or a network observer can capture sessions. The Grafana security hardening docs recommend secure and SameSite cookie settings, and they should be enabled with the redirect URL matching the public HTTPS address. Confirm the callback URL registered in GitHub or GitLab uses the exact scheme, host and path that Grafana expects, because mismatches are a common cause of failed logins.
Set the default role to least privilege
Users who sign in through OAuth receive the role set by the default and any role mapping, so a permissive default turns every authenticated provider account into an editor or admin. Start with Viewer as the default role and grant higher roles only through explicit mapping to groups you control. Ask your team to document which provider groups grant Editor or Admin, and review that list whenever a team is added or reorganized.
Review who holds server admin
Server admin rights apply across the whole instance, including data sources, plugins and other organizations, so they should be held by few people. Review the accounts with that role on a fixed schedule and compare them with the current provider group membership. Keep the number of server admins small and record the reason for each one, because a single over-privileged login can change data sources or disable protections for everyone.
Remove access at the provider
Grafana does not sync group membership from GitHub or GitLab in the open-source edition, and team membership inside Grafana is not kept in step with the provider. Membership changes in the provider take effect at the user's next login, so an account removed from a group keeps its Grafana access until it signs in again. To end access quickly, remove the user from the organization or group, or block or delete the account in the provider, and remove any Grafana team membership manually.
GitHub or GitLab: choosing the identity source for Grafana
GitHub suits teams whose engineers already work inside GitHub organizations. The natural access boundary is the organization, with teams nested inside it, so role and access decisions usually start there. Grafana's GitHub provider can restrict sign-in to members of selected organizations and can use team membership when mapping users to roles or organizations. Check the Grafana authentication docs for the exact settings in your Grafana version before you design the mapping.
- Organization membership: Limit sign-in to the organizations that own the systems Grafana displays, so people in unrelated organizations cannot log in.
- Team membership: Teams are the unit most engineering groups use for role decisions, but confirm how Grafana reads team data for your organization type.
- Account ownership: Confirm whether engineers use personal accounts or accounts managed by an enterprise, because ownership determines who can remove access when someone leaves.
- Team sync limits: Team sync is an Enterprise feature, so plan for membership to be applied through role mapping at sign-in rather than kept continuously in step.
Confirm which account type your organization issues and who removes Grafana access when an engineer leaves the organization.
GitLab suits organizations that model ownership as groups and subgroups, because those map closely to teams, products and environments. Grafana's GitLab provider can restrict sign-in to members of named groups, which gives you a clear boundary for who can view operational data. Review the GitLab authentication and authorization docs alongside the Grafana settings, since the GitLab side defines which groups and identities are available.
- Groups and subgroups: Restrict access to a top-level group or a specific subgroup, and test whether nested membership behaves the way your team expects.
- Endpoints: Self-managed GitLab changes the authorization, token and API endpoints Grafana calls, so every address points at your own hostname.
- Certificates: Grafana must trust the certificate chain for your GitLab host, including any internal certificate authority, on the Grafana server and inside any container images.
- Account source: Confirm whether users come from local accounts, LDAP, SAML or another source on your GitLab, because that affects the login flow and the group data Grafana receives.
- Upgrade alignment: GitLab upgrades pass through required upgrade stops, so recheck the OAuth application and endpoint settings after each upgrade.
Before cutover, test sign-in against your GitLab hostname with a non-administrator account and confirm that the certificate chain validates from the Grafana host.
Some organizations keep public or vendor-facing repositories on GitHub and internal work on GitLab, so engineers hold two identities. Grafana can be configured with both providers at the same time, but that creates a login design decision with an owner, and the decision affects users, roles and audit records. Decide the rules before the second provider goes live, then test each sign-in path with a sample account.
- Duplicate users: A person with a GitHub account and a GitLab account may appear as two Grafana users unless Grafana links them, so confirm how matching works in your version.
- Conflicting roles: Each provider sends different identity data, so the same person may receive different roles depending on which button they use.
- Single source of truth: Name one provider as authoritative for Grafana access, so offboarding removes access in one place.
- Support load: Two sign-in buttons send users to different identity sources, which increases questions during rollout unless the login page explains the choice.
- Audit clarity: Dashboards, annotations and logs should attribute actions to one identity per person.
If the number of providers keeps growing, a central identity provider in front of Grafana is usually easier to govern, and that option is covered later on this page.
Why sign-in fails and how to fix it
This table pairs the sign-in failures teams hit most often with GitLab or GitHub OAuth in self-hosted Grafana, the usual cause of each, and the fix to try first. Work through it top to bottom when a login breaks, because the first rows are usually configuration errors and the later rows depend on the environment around Grafana.
| Symptom | Likely cause | Fix |
|---|---|---|
| Provider shows a redirect URI error after clicking sign-in | The callback URL registered in the GitLab or GitHub OAuth application does not exactly match the URL Grafana sends, including scheme, host, port and path | Copy the callback URL from the Grafana log or the provider error, register that exact value in the OAuth application, and align it with the Grafana root URL setting |
| Login redirects to a wrong host, localhost or an internal address | The root URL is missing or wrong when Grafana sits behind a reverse proxy or load balancer, so Grafana builds callback links from the internal address | Set the public root URL in the Grafana server configuration to the address users type, and confirm the proxy passes the original host and protocol headers |
| User is denied even though they belong to the allowed group or organization | Membership is private at the provider, or the OAuth application token cannot see the group, so Grafana never receives the membership claim | Ask the user to make membership visible in the GitLab group or GitHub organization settings, then confirm the allowed groups or organizations setting matches the exact group path or org name |
| Login fails with a certificate or TLS error when using self-managed GitLab | The Grafana server does not trust the certificate authority that signed the GitLab certificate, often because the internal CA is missing from the host trust store | Install the internal CA certificate on the Grafana host or container, restart Grafana, and test the GitLab endpoints from the Grafana server before retrying |
| User signs in but lands in the wrong organization or with the wrong role | Role or organization mapping does not match the group or team names returned by the provider, or the role defaults to Viewer when no mapping rule applies | Compare the claim values in a test login with the mapping rules, correct the group names, and confirm the strict role setting and default role match the access model you approved |
| Users are logged out or get errors after a redirect when running several Grafana nodes | Sessions are not shared across nodes, so a request lands on a server that does not recognize the login token; high availability needs database-backed auth tokens and a shared database | Run two or more nodes against a shared MySQL or PostgreSQL database with database-backed tokens and a load balancer, as described in the Grafana high availability documentation, and test sign-in through each node |
When a central identity provider should sit in front of Grafana
Put a central identity provider in front of Grafana when you need one place to manage joiners, movers and leavers across many tools, when you require SAML or SCIM provisioning, or when you need team sync. The open-source edition of Grafana does not provide SAML, team sync, active sync or SCIM, according to the Grafana authentication docs, and those are the features that usually push an organization away from direct GitHub or GitLab sign-in. Sign-in alone does not remove access when someone leaves, so if offboarding must be enforced from HR or the corporate directory, plan for a directory-driven control rather than relying on a code platform account being disabled.
GitHub and GitLab sign-in ties Grafana access to the code platform's membership model: organizations, groups and projects that engineers join for source control reasons. That membership often does not match HR records, contractor end dates, or the groups your auditors and security team use to define who may see operational data. Check whether your source code platform accounts are provisioned from the same directory as the rest of your estate, whether contractors and bots hold accounts, and who administers the GitHub organization or GitLab group that controls Grafana access. If those answers are unclear, the identity model is the first thing to fix.
The main options to evaluate are Microsoft Entra ID, Okta, generic OAuth against an existing corporate provider, LDAP or Active Directory, and a self-hosted broker such as Keycloak or authentik that federates to your sources and presents a single OIDC client to Grafana. The right choice depends on your identity estate and on which Grafana edition you run, because SAML and team sync availability differ between them. Confirm with your Grafana edition, your directory, and your audit requirements before committing, and confirm the current Grafana authentication documentation for each provider's supported features.
Questions teams ask before setting up GitHub or GitLab login
What drives the cost of setting up Grafana login with GitHub or GitLab?
The cost follows the written scope, and the main drivers are the number of Grafana organizations, how your GitHub organizations or GitLab groups map to Grafana roles, and whether your GitLab is self-managed with a private certificate authority that Grafana must trust. Each additional organization or role mapping adds design and test work, and a high availability setup with two or more Grafana servers sharing a MySQL or PostgreSQL database adds build and verification effort. Ask for a quote that separates one-time work (OAuth app registration, configuration, testing, handover) from anything recurring, such as support or upgrades under a retainer. If you are weighing this against a central identity provider in front of Grafana, include that comparison in the scope so the choice is priced on the same basis.
How long does Grafana OAuth sign-in with GitHub or GitLab take to set up?
The duration depends on how quickly your team can grant access, how many groups and organizations need mapping, and whether Grafana already runs in production. Work that tends to take the most time includes confirming which GitHub organizations or GitLab groups should get which Grafana role, getting certificate and public URL details settled for a self-managed GitLab, and running sign-in tests with real accounts from each group. Ask the engagement lead for a timeline in the written scope, and confirm which steps depend on your provider administrators or change approval windows. No duration is given here because it depends on your environment.
What does our team need to provide before the work starts?
You need administrator rights in the GitHub organization or GitLab group that will register the OAuth application, a stable public HTTPS URL for Grafana, and access to the Grafana server configuration and its database. Grafana uses a database for configuration, and production setups should run on MySQL 8.0 or later or PostgreSQL 12 or later rather than SQLite. You should also provide a small set of test accounts across the groups you plan to map, plus the names of the people who approve role assignments. Confirm these items in the written scope so that waiting on access does not delay testing.
Can an internal team set up GitHub or GitLab login alone?
Yes, a team that already runs Grafana and manages its identity provider can do this internally, using the generic OAuth and GitHub or GitLab provider settings in the Grafana authentication documentation. The work is manageable when there is one organization and a simple group structure, but the risk grows with multiple organizations, nested groups, self-managed GitLab certificates or HA. A fixed-scope engagement from DeployOpen would typically cover the agreed provider and Grafana configuration, role and organization mapping, testing, hardening of the sign-in path and a handover document, all defined in writing before work begins. Request a quote based on that written scope to compare it with your own effort.
Can GitHub or GitLab group membership replace SCIM or team sync in open-source Grafana?
Not fully. In the open-source edition, GitHub and GitLab OAuth can restrict sign-in to members of specific organizations or groups and assign a Grafana role from claims, but team sync and SCIM provisioning are documented as available only in Grafana Enterprise and Grafana Cloud. This means Grafana team membership and user deprovisioning are not driven automatically in open source. Confirm this against the current Grafana authentication documentation for your version, and decide whether manual team management or an Enterprise license is needed for your audit and offboarding requirements.
What happens to Grafana access when someone leaves the company?
Removing a person from the GitHub organization or GitLab group blocks new sign-ins only when the group restriction is enforced at login, but existing Grafana user records and sessions may remain until they expire or are removed. Open-source Grafana does not automatically deprovision users through SCIM, so offboarding should include disabling the Grafana user, revoking active sessions and checking service accounts and API tokens that the person created. Ask for an offboarding procedure in the written scope and confirm how session lifetimes are set in your environment, since these settings control how quickly access ends.
How DeployOpen scopes and delivers Grafana sign-in
DeployOpen plans, builds, documents and hands over Grafana sign-in with GitLab or GitHub OAuth inside infrastructure you control. We start from who should be able to log in, which group or organization gates access, and how each team's role maps to what they can do. Engagements are fixed-scope, with the scope agreed in writing before work starts.
How we scope
- Confirm which GitLab groups or GitHub organizations and teams may sign in to your Grafana instance
- Agree which Grafana organization and role each identity group receives, and who keeps server admin rights
- Record whether GitLab or GitHub is the right identity source, or whether a central identity provider should sit in front
How we build
- Register the OAuth application in GitLab or GitHub with callback URLs matched to your Grafana domain
- Configure allowed groups, organization restrictions and role mapping in the Grafana authentication settings
- Test sign-in, denied sign-in and role assignment for each group with separate test accounts before cutover
How we hand over
- Deliver the configuration as files your team can review, version and reproduce in your own environment
- Document the OAuth client secret location, rotation steps and who approves changes to group mappings
- Walk your engineers through how to add a team, change a role and investigate a failed login
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer, scoped separately from the build
- Review group mappings and OAuth settings when Grafana upgrades change authentication behavior
- Confirm with your team which support hours, response expectations and change process apply before signing
