DocumentationGrafana CloudAccount managementAuthorization and permissionsConfigure OAuth

Configure OAuth

You can configure OAuth 2.0 to allow users to login with their Google, GitHub, GitLab, Azure AD, or Okta account. If you use a different provider, you can use Generic OAuth or contact Support.

Configure OAuth with Google

To configure OAuth2 using Google Cloud, you must register an application and create a Google OAuth client. You can then enable the client on your Grafana Cloud instance.

Create a Google OAuth client

1. Go to the Google Cloud Platform API page.
2. Agree to the Terms of Service.
3. Create a project. Enter a project name. The Organization and Location fields should both be set to your organization’s information.
4. In OAuth consent screen select the External User Type. Click CREATE.
5. Fill out the requested information using the URL of your Grafana Cloud instance.
6. Accept the defaults, or customize the consent screen options.
7. Click + CREATE CREDENTIALS and select OAuth client ID. Enter the following, substituting your instance URL where appropriate:
   • Application Type: Web application
   • Name: Grafana
   • Authorized JavaScript origins: https://<YOUR_GRAFANA_URL>
   • Authorized redirect URIs: https://<YOUR_GRAFANA_URL>/login/google
     

     NOTE: The URL you enter is the one for your Grafana instance home page, not your Grafana Cloud portal URL.

8. Click CREATE. Make a note of your OAuth client ID and client secret.

Enable the Google client on your Grafana instance

1. From the Cloud Portal, select the Advanced Auth option in the Security section.
2. Click the Google option and enter your client ID and client secret. List allowed domains, for example, grafana.com, and click Submit.

Configure OAuth with GitHub

To configure OAuth2 using GitHub, you must register an application and create a GitHub OAuth client. You can then enable the client on your Grafana Cloud instance.

Create a GitHub OAuth client

1. Log in to your GitHub account. In Profile > Settings > Developer settings, select OAuth Apps.
2. Click Register a new application.
3. Fill out the fields, using your Grafana homepage URL when appropriate. In the Authorization callback URL field, enter the following: https://<YOUR-GRAFANA-URL>/login/github .
4. Note your client ID.
5. Generate, then note, your client secret.

Enable the GitHub client on your Grafana instance

1. From the Cloud Portal, select the Advanced Auth option in the Security section.
2. Click the GitHub option and enter your client ID and client secret. List allowed GitHub organizations, for example, Grafana, add any Team IDs, and click Submit.

Confirm Organization Access within Github

If you enable allowed_organizations, confirm the organization access request within Github for the Grafana instance; this can be done at the following path: Profile -> Settings -> Applications -> Authorized OAuth Apps -> My Grafana -> Organization access or via https://github.com/settings/applications

Configure OAuth with GitLab

To configure OAuth2 using GitLab, you must register an application and create a GitHub OAuth client. You can then enable the client on your Grafana Cloud instance.

Create a GitLab OAuth client

1. Log in to your GitLab account and go to Profile > Preferences > Applications.
2. Click Add new application.
3. Fill out the fields. In the Redirect URI field, enter the following: https://<YOUR-GRAFANA-URL>/login/gitlab and check openid, email, profile in the Scopes list.
4. Click Save application.
5. Note your Application ID and Secret.

Enable the GitLab client on your Grafana instance

1. Go to your instance and using the left-hand menu, navigate to Administration > Authentication > GitLab.
2. Switch the Enabled toggle to the right.
3. Enter the required information for your OAuth provider like the client ID (Application ID), client secret (Secret), and other settings.
4. Click Save.

Configure OAuth with Microsoft Azure AD

To enable the Azure AD OAuth2 you must create a tenant or use an existing tenant and register an application with Azure AD.

Create a Azure AD OAuth client

1. Log in to the Azure Portal and click View for the Manage Azure Active Directory tile. Select the Azure AD tenant you want to use if you have more than one.

2. Go to App registrations in the Manage section and click + New registration.

3. Fill in the following fields:

   • Name: Choose a name for the app.
   • Supported account types: Choose what kind of user accounts can be used to authorize users.
   • Redirect URI Select Web, then enter the following: https://<YOUR-GRAFANA-URL>/login/azuread.
   • Click Register.

4. Make a note of your Application (client) ID.

5. Click Save.

6. In Certificates & secrets, click + New client secret.

7. Enter a name and certificate expiration.

8. Make a note of the Value. This is the OAuth client secret.
   

   Make sure that you copy the string in the Value field, rather than the one in the Secret field.

9. Find your API endpoints.

   Click the Endpoints (globe) button. Make a note of the following endpoints:

   • OAuth 2.0 authorization endpoint (v2)
   • OAuth 2.0 token endpoint (v2)

   If you don’t see the Endpoints option, it is because you are using a personal account. You must use a tenant to create an OAuth client.

10. Configure user and group permissions.

    Click Manifest.

    • Set groupMembershipClaims to ApplicationGroup. This setting will allow access to groups specified in the allowed_groups setting in your Grafana configuration.
    • You must define the Application Role settings for Grafana for each user ID. If you don’t, all users will default to view mode only when accessing the Grafana instance.

    You can generate random identifiers on Linux or Mac by using the uuidgen command in a terminal, or on Windows through PowerShell using New-Guid.

11. Assign a unique ID to each role.

    Add users and their roles to the appRoles field of the manifest.

    json Copy

     "appRoles": [
     		{
     			"allowedMemberTypes": [
     				"User"
     			],
     			"description": "Grafana admin Users",
     			"displayName": "Grafana Admin",
     			"id": "<SOME_UNIQUE_ID_1>",
     			"isEnabled": true,
     			"lang": null,
     			"origin": "Application",
     			"value": "Admin"
     		},
     		{
     			"allowedMemberTypes": [
     				"User"
     			],
     			"description": "Grafana read only Users",
     			"displayName": "Grafana Viewer",
     			"id": "<SOME_UNIQUE_ID_2>",
     			"isEnabled": true,
     			"lang": null,
     			"origin": "Application",
     			"value": "Viewer"
     		},
     		{
     			"allowedMemberTypes": [
     				"User"
     			],
     			"description": "Grafana Editor Users",
     			"displayName": "Grafana Editor",
     			"id": "<SOME_UNIQUE_ID_3>",
     			"isEnabled": true,
     			"lang": null,
     			"origin": "Application",
     			"value": "Editor"
     		}
     	],

12. Find your application. In Azure Active Directory, click Enterprise Applications. Search for and select your application.

13. Click on 1. Assign users and groups. Search for a user and assign them a Grafana role. Do this for every user that will need a role other than the default View role.

Enable the Azure client on your Grafana instance

1. From the Grafana Cloud Portal, select the Advanced Auth option in the Security section.
2. Click the Azure AD option.
3. Enter your client ID, client secret, and authorization and token URLs. Add scopes. Enter allowed Azure Groups and allowed domains, for example, Grafana. For more information on Azure AD groups, refer to Configure allowed groups.
4. Click Submit.

Configure OAuth with Okta

To enable Okta OAuth2 you must create an Okta app from the Okta Admin Console.

Create an Okta app

1. From the Okta Admin Console, select Create App Integration from the Applications menu.

2. For Sign-in method, select OIDC - OpenID Connect.

3. For Application type, select Web Application and click Next.

4. Configure New Web App Integration Operations:

   • App integration name: Choose a name for the app.
   • Logo (optional): Add a logo.
   • Grant type: Authorization Code
   • Sign-in redirect URIs: Replace the default setting with the Grafana Cloud Okta path, replacing <YOUR_ORG> with the name of your Grafana organization: https://<YOUR_ORG>.grafana.net/login/okta
   • Sign-out redirect URIs (optional): Replace the default setting with the Grafana Cloud Okta path, replacing <YOUR_ORG> with the name of your Grafana organization: https://<YOUR_ORG>.grafana.net/login/okta
   • Base URIs (optional): Add any base URIs
   • Controlled access: Select whether to assign the app integration to everyone in your organization, or only selected groups. You can assign this option after you create the app.

5. Make a note of the following:

   • ClientID
   • Client Secret
   • Auth URL For example: https://<TENANT_ID>.okta.com/oauth2/v1/authorize
   • Token URL For example: https://<TENANT_ID>.okta.com/oauth2/v1/token
   • API URL For example: https://<TENANT_ID>.okta.com/oauth2/v1/userinfo

Enable Okta on your Grafana instance

1. From the Cloud Portal, select the Advanced Auth option in the Security section.
2. Click the Okta option and enter your client ID, client secret, and the authorization and token endpoints. List allowed Okta groups and allowed domains, for example, Grafana, add any Team IDs, and click Submit.

Configure Okta to Grafana Cloud role mapping

1. In the Okta Admin Console, select Directory > Profile Editor.

2. Select the Okta user profile you want to modify.

3. Select Add Attribute and fill in the following fields:

   • Data Type: string
   • Display Name: Meaningful name. For example, grafana role.
   • Variable Name: Meaningful name. For example, grafana_role.
   • Description (optional): A description of the role.
   • Enum: Select Define enumerated list of values and add the following:
     • Display Name: Admin Value: Admin
     • Display Name: Editor Value: Editor
     • Display Name: Viewer Value: Viewer

   The remaining attributes are optional.

4. Click Save

5. Return to the Directory section and select Profile Editor.

6. Select the Okta Application Profile you created previously, and click Add Attribute.

7. Set all of the attributes in the same way you did in Step 3.

8. Select Add Mapping to add your new attributes. For example, user.grafana_role -> grafana_role.

9. To add a role to a user, select the user from the Directory, and click Profile -> Edit.

10. Select an option from your new attribute and click Save.

11. In your Cloud Portal Admin configuration, modify [okta.auth] with the new configuration option role_attribute_path = <YOUR_ROLE_VARIABLE>. For example: role_attribute_path = grafana_role.

    Note: You might have to contact support to change this configuration setting.

Configure OAuth with Generic OAuth

1. Go to your instance and using the left-hand menu, navigate to Administration > Authentication > Generic OAuth.
2. Switch the Enabled toggle to the right.
3. Enter the required information for your OAuth provider, such as the client ID, client secret, and other settings.
4. Click Save.