In this step-by-step tutorial, you will learn how to enable Azure AD SAML SSO for open source Grafana via Datawiza. Note that open source Grafana does not support SAML natively, so in the past, you had to buy the enterprise license if you wanted to use SAML. Datawiza eliminates this license requirement by enabling SAML with open source Grafana. Datawiza is a generic identity-aware OIDC/OAuth/SAML proxy with a centralized management console that you can easily use to achieve the same integration with other identity providers like Okta, Auth0, PingIdentity, Google, etc.
Prerequisites
- For creating the Grafana and running Datawiza:
- Docker (18.03+)
- Docker Compose
Run Grafana
Grafana provides the official docker images, so we use these to run Grafana:
docker run -d -p 3000:3000 --name grafana grafana/grafana
Then go to http://localhost:3000
And login with the default username/password:
Stop and remove this Grafana container:
docker stop Grafana && docker rm grafana
Grafana provides many ways to authenticate users. We will use auth proxy authentication to achieve our goal. Grafana provides a full walkthrough using docker, and we will use the first part of the walkthrough to run Grafana:
Create the grafana.ini with the following contents:
[users]
allow_sign_up = false
auto_assign_org = true
auto_assign_org_role = Editor
[auth.proxy]
enabled = true
header_name = X-WEBAUTH-USER
header_property = username
auto_sign_up = true
Launch the Grafana container. Note that we will expose port 3000 at the moment:
docker run -i -p 3000:3000 -v $(pwd)/grafana.ini:/etc/grafana/grafana.ini --name grafana grafana/grafana
Introduction to the Datawiza Platform
The Datawiza Platform is a cloud-delivered platform. It includes a data plane and a control plane: Datawiza Access Proxy (DAP) and Datawiza Cloud Management Console (DCMC).
DAP is a lightweight, container-based access proxy deployed close to your application via the sidecar (agent) or gateway mode. It talks to Azure AD SAML on behalf of your applications, so you don’t need to worry about the integration work. DCMC is a cloud-based management console where you can configure and manage the policies of DAPs. Such a SaaS-based design makes the whole platform much easier to use.
Create an App registration in Azure AD
First, we need to create an App registration in the Azure portal. When performing this step, make sure to log in to your account on Azure portal.
You can skip this step if you already have an app integration with the following value: Metadata URL.
Choose Enterprise Applications from the left sidebar and create a new Registration by clicking New registration.
Click Create your own application, input the name and select Integrate any other application you don’t find in the gallery (Non-gallery), then click Create:
Select Users and Groups, and click Add user/group:
By default, no one was assigned to this application. So click None Selected and select the users and groups that should have access to log in:
Click Assign:
On the left-hand navigation under Manage, click Single sign-on. Select SAML on the Select a single sign-on method page:
You will then be directed to the Set up Single Sign-On with SAML page.
For Basic SAML Configuration, click Edit and configure with the following values:
* Identifier (Entity ID): http://localhost:9772/saml/metadata
* Reply URL (Assertion Consumer Service URL): http://localhost:9772/saml/acs
For Attributes & Claims, under Additional Claims, click “…” (the three dots), then delete and confirm the action next to each row and delete the four default claims.
Click + Add new claim at the top of the page. Configure with the following values:
Name | Namespace | Source | Source attribute |
Leave Empty | Attribute | user.userprincipalname | |
givenName | Leave Empty | Attribute | user.givenname |
surname | Leave Empty | Attribute | user.surname |
displayName | Leave Empty | Attribute | user.displayname |
For groups, click + Add a group claim, select Security groups and customize the name of the group claim as groups:
Go back to Set up Single Sign-On with SAML page. For SAML Signing Certificate, copy the App Federation Metadata Url, which is the Metadata Url needed for DCMC configuration.
Configurations in Datawiza Cloud Management Console
Self-register an account in the Datawiza Management Console. You can easily get started with your Google account, Microsoft account, or GitHub account.
Upon logging into the Datawiza Management Console, click the orange Getting started button.
This runs a step-by-step guide for configuring your application.
Add a New Deployment
The first step of the configuration process is creating a “deployment.” A deployment is a way of organizing applications and identity providers that are associated with the same cluster as Datawiza Access Proxies. Don’t worry if this seems a bit complicated to understand in the beginning. You will get used to it when you work with it more. For now, just give your deployment a meaningful name and description.
Add a New Application
The second step is to create an application. This is simply collecting the network information of your application.
Here is an explanation of each field.
- Platform: Select WEB here.
- App Name: The name of your application. Put a meaningful name here. We use Grafana demo app.
- Description: A meaningful description for you to understand this application.
- Public Domain: This is how your user will access your application. Normally it’s the URL in the address bar. You can use http://localhost if you are running locally. Be sure to add the port if you have a non-standard one. We use http://localhost:9772 as an example.
- Listen Port: This is the port that the Datawiza Access Proxy listens on. For simplicity, you can use the same port as the one in Public Domain above if you are not deploying the Datawiza Access Proxy behind a load balancer.
- Upstream Servers: This configuration tells Datawiza Access Proxy where the actual Grafana application resides. Enter http://host.docker.internal:3000.
Note that the upstream server is the address of the application for which you want to enable SSO.
- If you use the DAP in sidecar mode and your application is running on http://localhost:3000 on Mac or Windows, then set the upstream server to http://host.docker.internal:3000 (Docker 18.03+).
If your application is running on Linux, use ip addr show docker0 to get docker host IP (e.g., 172.17.0.1) and then set the upstream server to http://172.17.0.1:3000 (see this for more details).
Add a New Identity Provider
The third step is to fill in the identity provider information. Select SAML as the Protocol and Azure AD as the Identity Provider. Input the Metadata Url you saved when creating the app integration in the Azure portal. Upload the cert and key. Certificates in SAML are only used as a convenient way to handle the signing and encryption keys. A pair of self-signed cert and key is OK. Click on Create to proceed.
Start the Access Proxy
The last step of the guide will provide you with the environment configurations. Here you will see the Provision Key and Provision Secret.
Follow the steps (1, 2, and 3) on the page to log in to our docker registry, pull the Access Proxy image, and use the docker-compose.yml file we provided to start the DAP.
Click Done, and you will then be redirected to the configuration page. Click the Application tab and click the application:
Click Attribute Pass and Add New Attribute pass:
Set the email as the X-WEBAUTH-USER in Header, then click Save:
Now run
docker-compose -f docker-compose.yml up -d
or
docker compose -f docker-compose.yml up -d
In your browser, hit the Public Domain URL as you set previously. You should then see the identity provider login page.
Note that if you are already logged into Azure AD in your browser, you may need to log out to see the login page.
After logging in to Azure AD SAML, Grafana will be shown.
Go to profile page:
Advanced
Although you have added Azure AD authentication to Grafana, there are still several areas you can improve.
As the Grafana walkthrough said, you should not expose ports for Grafana, which should only be connected to by the DAP. An easy way to connect Grafana and DAP without exposing ports is adding Grafana into the DAP docker-compose file:
version: "3"
services:
# Configuration of Datawiza Access Proxy image begins here.
# Unless you know what you are doing, do not modify this block.
# If you need any assistant, please contact: info@datawiza.com
datawiza-access-broker:
image: registry.gitlab.com/datawiza/access-broker
container_name: datawiza-access-broker
ports:
- "9772:9772"
restart: always
environment:
PROVISIONING_KEY: YOUR_PROVISIONING_KEY
PROVISIONING_SECRET: YOUR_PROVISIONING_SECRET
grafana:
image: grafana/grafana
container_name: grafana
volumes:
- ./grafana.ini:/etc/grafana/grafana.ini
You will need to change the Upstream Servers in DCMC to http://grafana:3000
In the grafana.ini provided by the walkthrough, we simply use X-WEBAUTH-USER as the username. What’s more, Grafana provides the configuration called headers in auth.proxy, which can optionally define more headers to sync other user attributes. We can use it to enrich user info. For example, we want to use user group as a Grafana role and Azure AD email as email:
[auth.proxy]
headers = Role:X-WEBAUTH-ROLE Email:X-WEBAUTH-EMAIL
And add the attribute pass in DCMC:
After logging in, we can see our updated user info:
One last thing, DAP has its own logout URL, so we need to add it to grafana.ini:
[auth]
signout_redirect_url = /ab-logout
Summary
Congratulations!
You secured Grafana by adding Azure AD SAML SSO using Datawiza — and without requiring the enterprise license. This is only a small sampling of what Datawiza can do. See Datawiza’s online docs or official website for much more information. You can also get a free trial by signing up here!
