This is archived documentation for v1.6.0. Go to the latest version.

OAuth integration

OAuth integration

Grafana Enterprise Metrics supports the OpenID Connect (OIDC) core standard to validate tokens. This allows you to integrate GEM with an existing OAuth token provider at your organization.

To support OIDC, provide the URL of the OIDC provider (issuer) in the auth.admin.oidc.issuer-url setting. The provider is required to have the OIDC Discovery endpoint (also known as “well known endpoint”) at <issuer-url>/.well-known/openid-configuration, as described in the openid standard.

A JWT is included as the password in HTTP basic authentication or as part of a bearer token in bearer authentication. The bearer token should have two parts separated by a :. The first part is the tenant ID. The second part is the JWT.

The JWT is validated against the OIDC provider specified above. If it is valid then an access policy name is extracted. The regular expression in auth.admin.oidc.access_policy_regex is run against each value in the the JWT claim field specified in auth.admin.oidc.access_policy_claim, which can either be a single string or a list of strings.

A sub-match has to be present to extract the access policy. If the value in the JWT claim field is a string, then only the first sub-match is used. If it is a list of strings, then the first submatch for each entry is used. You can use the regular expression (.*) for the whole claim field.

The regular expression syntax is RE2.

Configuration

To use OIDC, specify the auth.type as enterprise. Here is an example authentication section:

auth:
  type: enterprise
  admin:
    oidc:
      issuer_url: https://accounts.authprovider.com/realms/example
      access_policy_claim: "sub"
      access_policy_regex: "pref-([0-9]+)-.*"

Here is an example payload section of a valid JWT:

{
  "sub": "pref-1234567890-abc",
  "name": "John Doe",
  "admin": true
}

The extracted access policy is 1234567890.

Note: OpenID Connect (OIDC) converts the encoded access policies to lowercase (downcase). For example, if your OpenID system has an access policy called Team1, then you need to create an access policy in GEM called team1 so the integration works.

Multiple access policies

It is possible to provide an array of strings in the JWT claim field. If this array only includes one item, then the behavior is the same as when providing a string in this field. In the case where multiple access policies are provided as a list in the JWT claim field, they will be aggregated into a “virtual” access policy. This “virtual” access policy will provide metric read access to the union of all tenants contained in the original access policies. For example, given the following JWT and config above:

{
  "sub": ["pref-1234567890-abc", "pref-9876543210-xyz"],
  "name": "John Doe",
  "admin": true
}

The resulting access policy would be an aggregate of 1234567890 and 9876543210. If 1234567890 provided read and write access to tenant-1, and 9876543210 provided read and write access to tenant-2 and tenant-3, the resulting virtual access policy would provide read-only access to tenant-1, tenant-2, and tenant-3. This generated access policy is cached for the period specified in auth.cache.ttl.duration, which defaults to 10m.