Download

Ep. 52: Configuring SAML authentication in Checkmk

[0:00:00] Welcome to the Checkmk channel. Today I'll be talking about the SAML authentication in Checkmk.
[0:00:15] Starting from version 2.2, in all the commercial editions the SAML authentication has been integrated with the Checkmk UI. Now in the setup menu you have an option to configure multiple SAML connections with your preferred IDPs, automatic creation of the user, and the user attribute synchronization happens at the login time. 
[0:00:35] For administrative and debugging purposes you can have a look at the site “web.log”. You can also raise the lock level in order to troubleshoot any authentication problems. For more technical information like signing of requests and responses and the supported algorithms you can have a look at our technical documentation. 
[0:01:00] If you are a Raw Edition user you can use the SAML authentication at the Apache level via the “mod_auth_mellon” module. This is also described in our documentation. So without further Ado let's get started.
[0:01:14] For this demo, I'm using the Checkmk Enterprise Edition 2.20p11 and the IDP that we are integrating against today will be Azure AD. Like every integration there are some prerequisites, so first let's have a look at those prerequisites.
[0:01:30] For that I will be going to the official documentation where we have already defined these prerequisites and that must be met for the SAML to function. The first prerequisite is that the web interface of Checkmk must be secured with HTTPS, this is we already did. If you look at the URL, the URL of the Checkmk instance is already secured with HTTPS.
[0:01:54] The second prerequisite is we need to make sure that the Checkmk SAML endpoints for the requests and the responses must have been registered with the IDP. We will see that how this is configured on the IDP side. And the third one is, the messages directed by the IDP to Checkmk. That is, the responses to authentication requests and attribute statements must be signed with one of these supported algorithms. Checkmk itself uses SHA56 for signing its request.
[0:02:31] So that was the prerequisites, so we can now go ahead and proceed with the configuration of the IDP. For that I will log into to my Azure AD and directly click on “Enterprise applications”. If you have opened the Enterprise application multiple times it will show up in that area as soon as you log in under Azure services, but otherwise you can simply search for it as well. So if I click on Enterprise applications you can already see that I have one application available.
[0:03:04] To create an Enterprise application is pretty straightforward, you need to click on “New application”, fill out the name, go to “Single sign-on”, and then set up the SAML. It's also mentioned in our documentation how to do that. I can also share you some screenshots here from the documentation where we create an application. We fill out a name, after that we go to “Single sign-on” and start filling out the information that is needed for the SAML configuration.
[0:03:37] In order to save time, I already created an app. So let's just simply click on the app. We will see that it already has some details like the Name, application ID and Object ID. And on the left-hand side you have the “Single sign-on”. When you click there you will see already the configuration that has been filled.
[0:04:00] This configuration is divided into several sections, the first section is a basic SAML configuration, where the first two fields are the required fields which is the identifier “Entity ID” and the “Reply URL”. It has a URL that is pasted in its value.
[0:04:21] If you look closely to how the URL has been constructed. This is basically your Checkmk URL, and after this you are just putting a simple slash and putting “saml_metadata.py”.
[0:04:36] And in case of the reply URL, the Checkmk URL Remains the same, and you just put “saml_acs.py?acs”. After you have provided these values, that's basically the basics and SAML configuration.
[0:04:55] Rest are the other things like attributes and claims, which you can see that some claims are available by default. The group claim is something that I have added. It is also possible to have a look at these claim names. These URLs will be used on the Checkmk site for the mapping of different attributes. So we will also come to this page again.
[0:05:19] So let's go back to our previous page and look at the other section which is SAML certificates. Here you can already see that the status is set to 'Active', you have a 'Thumbprint', you have an “App Federation metadata URL” which will be used in the Checkmk SAML configuration.
[0:05:44] Either you can use this URL or you could also download the XML and upload it if you have no connectivity to the internet, that is your Checkmk instance cannot talk to the Azure AD directly via the internet. So it's also possible to download this and upload this XML.
[0:06:02] Then that's it. If we click on the edit button under SAML certificates, we can also see that the signing algorithm for the SAML response and assertion is already SHA256 which already meets our requirement. Now we can proceed with the configuration of the service provider which is Checkmk in this case. 
[0:06:28] So for that you need to go back to the Checkmk web UI. Let's quickly log in here. And as soon as you are logged in you can directly go to the setup menu and search for the word 'SAML'. 
[0:06:42] And this is our SAML authentication connection page, where you can view all the connections or simply if there are none then we can click on ADD connection. You will see a configuration page divided into different sections, in the general properties you have to define the connection ID, it has to be unique connection ID, and then you can choose any name that you like.
[0:07:12] Since I'm using Azure as an IDP, so I chose Azure as a name here. And then we can move on to the next section. The second one will be generated automatically, so we can skip this and move to the connection. Here, you can provide the identity provider metadata in three different ways. Either you can provide the URL, you can download the XML file from the Azure portal and upload it, or you can simply paste the contents of the XML file.
[0:07:44] Today, we will be using the URL, for that I need to go back to my Azure portal where I was using the SAML configuration. And scroll a little bit down where we can see under SAML Certificates, the "App Federation Metadata" URL. I'll simply copy this, go back to the Checkmk web UI and paste this information.
[0:08:09] So I have now copied the identity provider metadata. The next setting is Checkmk server URL. This I can grab from the browser itself where I have this thing already created. Simply paste in here. The second the next setting is I didn't provide a connection timeout. I will keep this as a default setting, but depending on your setup if you're facing some timeouts during 'Read', or 'Connection', you can adjust these timeouts accordingly. 
[0:08:40] Under “Security”, you have the option to provide the certificate to sign the requests. You have two possibilities here, either you can use a Checkmk certificate or you could upload your own company specific certificate. For that you need to upload a 'Key' as well as the 'Certificate'. If you are using public certificate then it should be a single certificate and not a chain, it's also defined in the 'Help' menu. 
[0:09:09] If you click 'Help' menu you will see that message here we need a public certificate which should be a single certificate and not a certificate chain. Let's switch off this inline help and use the Checkmk certificate.
[0:09:25] The last and the most, important configuration section is under users which is about syncing the attributes. Here you have to define the mapping, the left-hand side is the 'User ID' attribute that is required by Checkmk and in here you need to now provide the mapping from your Azure AD portal. So we go back to the Azure AD portal and directly look at the attributes and claims. If you click on the edit button, you see the claim names they are in the form of URLs, maybe with your IDP providers they are with names. You could also create names here, but I try to stick to with the defaults here, where I can see the different possibilities of the claim names.
[0:10:16] So for the User ID, I'm going to use the name attribute. Let's paste that in there, the second option that you can choose here is the full name attribute, for that I'm using the given name. And the email address attribute you also have a claim name available, let's copy this and also paste it here.
[0:10:53] And last but not the least is your contact groups and roles. For contact groups we will be we have four different options the default is do not synchronize, second one is map value to the specific groups, third one user attribute value and then you have a possibility to use the CN from your LDAP distinguish name string. We will be using the map value to specific group, I already have some groups defined inside the Azure.
[0:11:25] So I will be using those groups and mapping them to the contact groups that I have defined inside Checkmk. In addition to the by default contact group that is everything I have also defined two contact groups by the name of 'Linux Admins' and 'Windows Admins'. And now we are going to sync that or map it what we see for a particular user inside Azure.
[0:11:54] Here also you need to paste a group claim name. I already see that here on the claim name page. Let's copy this, go back and let's paste this group here, and now you have the possibility to match the attribute. This attribute can be found under if you directly search for groups.
[0:12:18] I have two types of two groups that I have created in my Azure account one is Team Linux, Team Windows. If you look at Team Linux they have some members. Linuxuser1 is one of the member which has an email ID, and it is a member. Similar way, the other group Windows has a user, Windowuser1 and this will be the user that will be logging to Checkmk and get all the attributes synced from the Azure AD to Checkmk.
[0:12:59] Let's now go back to the group page where we can copy these unique object IDs against each attribute. So we will copy this object ID for Team Linux and paste it in here and at the same time we will attach it to the Linux Admins. The sub second object ID is for Team windows we will also copy this and paste it here.
[0:13:24] And attach it to the windows admins. For the roles it's also the same process which I'm not going to do right now, but again it is a matter of pasting the attribute you can choose the particular role and then assign those different mapped attributes here.
[0:13:47] For the time being I'm not going to use any roles, so I'll simply I have filled all the prerequisites, and now I'm going to save this form. As soon as I save it and I log out from Checkmk you will notice a difference on the web GUI.
[0:14:03] Here you see another button now which says “Login with Azure”. So you still have the possibility to use SAML as well as your LDAP integration. I mean your LDAP credentials, and at the same time your local users via “htpasswd”. I will open a private window so that I can show you the user login via SAML.
[0:14:29] So let me open a private window open, and we can straight away open the demo instance. And now if we click on login with Azure. It will ask for a user ID, so I have to look for the user ID from the screen. Let's go to: Home > users > Linuxuser1. It is one of the user. I will copy the user principal name.
[0:15:06] And go back to the screen type in the username. Paste the username and now I will type the password. Let's sign in, and we are authenticated against the Checkmk UI. The user was created at the login time and as well as the attributes got synchronized.
[0:15:30] To look at that you can log out and simply log in via “cmkadmin” and go to the setup and look at the users. If you open now there you can already see that this user was created that there was a change that was created. In the “Edit menu”, you can see now these are the attributes we specified, and they got synchronized. It got a role by default as 'Normal monitoring user', and this Linux user was automatically attached to the contact groups 'Linux Admins'. Let's now try a different example with the Windows user where we close this private window and maybe let's open another one. Let's open the URL.
[0:16:22] And here we will now try with the different user not the Linuxuser1 but maybe the Windows user for that we can also copy the user principal name and paste it in here press 'Enter' and type in the password. I don't want to use any authenticator right now, so I will just skip that part, and it will now allow me to log into Checkmk, and at the same time it also registers a change.
[0:16:59] So the user was created, and again the attributes got synchronized the same way. Now we will try another way to use a third user where I would like to show you some common problems that you may face, when you are setting up the SAML authentication. We have another user by the name of Foobar which is added to the Linux group and I would like to demonstrate some common errors that you may face while setting up the SAML authentication.
[0:17:31] So this is like any other user which I showed you before. Let's also copy the username and open a private window. And after that we will put the Checkmk URL as like before and try to authenticate via this user. Now let's click on login user put in this username and if I now put the password and this will be redirected to Checkmk you will see “Authentication failed please contact your administrator”. I have typed in the right password, but I still get this message now how to troubleshoot this common problem. 
[0:18:22] For that I can directly go to my Checkmk site and have a look in the var/log. And let's simply open the web.log. If you open this lock file you will see the complete request and response. It's accessing the SAML connector it's doing an authentication request with the identity provider and the relay state, it performs a 'Get' response Code and finally at the bottom it also gives you the complete error message.
[0:18:59] This is the error message that we are getting. And if you carefully look at that exception there's a “Key Error” here, which says that the email address that is being supplied from this user is empty that's why this authentication is failing. 
[0:19:16] So this claim name claim email address that we have defined in the email attribute synchronization it doesn't have any value from Azure. So to fix this let's go back to Azure. And let's open this user. And if you edit the properties of this user we can see that it has a principal name, last name, full name is all correct under the contact information the email value is blank. So let's simply paste it we will paste the same principal name and save this now.
[0:19:56] And now we will perform the authentication the same way, click on Azure again, Ask later, and you will see now the authentication was through, and this user was successfully created. So these are some common problems why you may get the authentication failed on the web UI, so make sure that all the users that you are adding they have all the proper attributes. But if it is not there, and you would like to see which one is missing then enabling, raising the log level to debug may show you this information. 
[0:20:41] But don't forget to reset it to the defaults after you are done with your troubleshooting because this can fill up your disk space very quickly. Activate on the selected sites, and now we have all the three users that we needed. Let's quickly have a look at those users they are all coming from the SAML connector that we defined. And if you look at the attributes they have the standard username, full name, and email address, the password and under contact groups they also get synced.
[0:21:17] So that's it for today. Thank you for watching, please don't forget to like and subscribe and I'll see you around.

Want to know more about Checkmk? Join us for our Introduction to Checkmk Webinar

Register now

More Checkmk Videos

Ep. 1: Installing Checkmk 2.0 and monitoring your first host
13:23 English
Ep. 1: Installing Checkmk 2.0 and monitoring your first host
In this video, Baris explains how to take get started with Checkmk and start monitoring your first host within a few minutes.
Ep. 2: The Checkmk 2.0 user interface
10:23 English
Ep. 2: The Checkmk 2.0 user interface
In this video, Baris take you through the new user interface in Checkmk 2.0. He explains the various components of the User interface such as the new navigation menus, the Sidebar, main dashboard, tactical overview, how to switch between the Checkmk interface themes and much more
Ep. 3: Using SNMP to monitor network devices in Checkmk 2.0
07:09 English
Ep. 3: Using SNMP to monitor network devices in Checkmk 2.0
In this episode, Baris explains how to monitor network devices with Checkmk. SNMP is a protocol that many switches, routers, printers, UPSs, hardware sensors and other devices have implemented with the purpose of being able to monitor them easily.
Ep. 4: Monitoring Windows in Checkmk
05:33 English
Ep. 4: Monitoring Windows in Checkmk
In this video of our Getting started with Checkmk series, Baris explains how to install a Checkmk agent on a Windows host system and add that into your monitoring environment.
Ep. 5: Using metrics and graphs in Checkmk 2.0
05:21 English
Ep. 5: Using metrics and graphs in Checkmk 2.0
In the 5th episode of the Getting started with Checkmk series, Baris explains using various metrics that you can monitor in Checkmk such as CPU utilization, CPU load etc. You can also see graph visualizations for these metrics or create and customize your own as per your requirements.
Ep. 6: Updating Checkmk 2.0 and using multiple instances
08:30 English
Ep. 6: Updating Checkmk 2.0 and using multiple instances
In this video, Baris explains how to update your Checkmk instance. It is very easy and can be done within minutes. You can run multiple Checkmk instances with different versions on the same system. This gives you the flexibility to test the new version before using it in production.
Ep. 7 (part 1): Working with rules and setting thresholds in Checkmk
18:34 English
Ep. 7 (part 1): Working with rules and setting thresholds in Checkmk
In the following three-part videos series, Baris explains rule-based monitoring with Checkmk. In the first part, he shows you how you can work with rules and set threshold values. Rule-based configuration is one of the key features for Checkmk which helps you to scale your monitoring easily within minutes.
Ep. 7 (part 2): Smart rules with Host Tags in Checkmk
16:41 English
Ep. 7 (part 2): Smart rules with Host Tags in Checkmk
In the second part of this video, Baris explains using Smart rules with host tags in Checkmk. In the first part, he shows you how you can work with rules and set threshold values. These are features that you can use to build your rules even more intelligently and to better organize your monitoring.
Ep. 7 (part 3): Managing Hosts in Folder in Checkmk
11:42 English
Ep. 7 (part 3): Managing Hosts in Folder in Checkmk
In this final part of our episode on Rule-based monitoring in Checkmk, Baris demonstrates how to manage hosts in folders in Checkmk. This helps you to apply your monitoring configurations at scale and organize your hosts according to your needs.
Ep. 8: Working with Host and Service Groups in Checkmk
07:51 English
Ep. 8: Working with Host and Service Groups in Checkmk
In this Baris demonstrates how to create host and service groups in Checkmk, so you can perform actions on an entire group instead of configuring each of them individually.
Ep. 9: Using the Quicksearch function in Checkmk
06:02 English
Ep. 9: Using the Quicksearch function in Checkmk
In this episode of the Checkmk tutorials, Baris shows how you can use the Quicksearch function in Checkmk. You can use it to easily find and manage certain hosts or services. He also explains some examples of filters to you. In Checkmk 2.0 you can use the same syntax in the Seach function found in the monitor menu to get identical results.
Ep. 10: Detecting configuration errors with the Analyze Configuration feature
04:24 English
Ep. 10: Detecting configuration errors with the Analyze Configuration feature
With the Analyze Configuration feature, you can check if there are any configuration errors in your installation. Checkmk controls a number of possible security risks or potential performance restrictions and indicates if there are any problems.
Ep. 11: View creation and customization in Checkmk
10:22 English
Ep. 11: View creation and customization in Checkmk
In this video, Baris demonstrates how to customize headers, columns, and more in Views in Checkmk for yourself or other users. He also explains how to create custom views and add desired information to these views.
Ep. 12: Acknowledging problems in Checkmk
08:39 English
Ep. 12: Acknowledging problems in Checkmk
In this video, Baris explains how you can acknowledge problems in Checkmk. This function helps you to qualify the states of hosts and services. This allows you to keep track of messages in the main dashboard and, for example, you can add comments to problems.
Ep. 13: Scheduling downtimes in Checkmk
10:06 English
Ep. 13: Scheduling downtimes in Checkmk
In the episode of our Getting started with Checkmk series, Baris explains how you can manage the maintenance times of your systems in Checkmk. Such scheduled downtimes prevent your monitoring from sending false alarms when a host or service goes to WARN or CRIT during maintenance work. You can also inform the users concerned about the maintenance via Checkmk.
Ep. 14: Distributed monitoring with Checkmk
17:27 English
Ep. 14: Distributed monitoring with Checkmk
In this video, Baris explains how you can connect several Checkmk instances to a monitoring system and then manage it.
Ep. 15: MKPs and Plugins in Checkmk
07:53 English
Ep. 15: MKPs and Plugins in Checkmk
In the 15th episode of our Getting started with Checkmk tutorial series, Baris explains what are Checkmk Extension Packages (MKPs) and how easy it is to integrate them into your Checkmk monitoring environment. MKPs are the preferred format when you make your own extensions as it makes it easy to share with other users or deploy in distributed environments.
Ep. 16: Working with 'Bulk Actions' in Checkmk
19:49 English
Ep. 16: Working with 'Bulk Actions' in Checkmk
In this episode of our Checkmk tutorials series, Baris explains how you can save a lot of time with bulk actions. With this feature you can perform various tasks such as deleting, renaming, service discovery etc. on a large number of hosts simultaneously.
Ep. 17: Working with network topologies in Checkmk
10:30 English
Ep. 17: Working with network topologies in Checkmk
In this video of our gettign startted with Checkmk series, Baris explains how to map network topologies in Checkmk. This feature is quite helpful to manage your network and prevent any unnecessary notifications from the devices in your network.
Ep. 18: Creating and customizing dashboards in Checkmk
11:38 English
Ep. 18: Creating and customizing dashboards in Checkmk
In this video of our Getting started with Checkmk series, Mathias explains how you can create and customize dashboards in Checkmk 2.0, so you can get insights into your monitoring according to your requirements. Find out more in this video.
Ep. 19: Monitoring websites and their certificates with Checkmk
15:43 English
Ep. 19: Monitoring websites and their certificates with Checkmk
In this episode, Bastian demonstrates how to monitor a website and its certificate with Checkmk. You can also monitor specific web pages with Checkmk by using the several options that will suit your use case. Learn more in this video.
Ep. 20: Configuring dashboard elements in Checkmk
9:14 English
Ep. 20: Configuring dashboard elements in Checkmk
Learn how to add data visualization elements of the various metrics into your Checkmk Dashboard. In this video, Mathias explains how you can configure these elements and create a dashboard as per your requirements.
Ep. 21: Setting up notifications in Checkmk
8:37 English
Ep. 21: Setting up notifications in Checkmk
Learn how to set up notifications in Checkmk and assign relevant contacts and contact groups to be notified for various events. Later in this video, our presenter Bastian also demonstrates how you can set up rule-based notifications according to different conditions for hosts and services.
Ep. 22: Monitoring logfiles with Checkmk
10:19 English
Ep. 22: Monitoring logfiles with Checkmk
Monitor your logfiles with Checkmk using its Logwatch plugin. It is very useful when you want to monitor your logfiles regardless of whether you are using a UNIX/Linux or a windows based system. Learn more in this video.
Ep. 24: 3 Rules for efficient network monitoring
10:59 English
Ep. 24: 3 Rules for efficient network monitoring
In this video, Bastian demonstrates 3 rules that will help you to efficiently monitor your network interfaces. With Checkmk 2.0, with just three rules, you can set up an efficient network monitoring that will not only monitor all of your network interfaces but also simultaneously provide a detailed overview of all of your ports.
Ep. 25: New UX and security improvements in Checkmk 2.1
9:01 English
Ep. 25: New UX and security improvements in Checkmk 2.1
Checkmk 2.1 come with many UX improvements such as pre-built dashboards for Linux and Windows, faster core performance and much more. Security features such as two-factor authentication etc. were also added in this new version. Watch this video to learn how to use these new features and enhancements in Checkmk.
Ep. 28: Working with InfluxDB integration in Checkmk
5:36 English
Ep. 28: Working with InfluxDB integration in Checkmk
Learn how to send data to InfluxDB from Checkmk. As InfluxDB introduced a new protocol to send data to it, a new connector was developed with Checkmk to talk natively with it. Learn more about it in this video.
Ep. 29: New agent architecture in Checkmk 2.1
11:00 English
Ep. 29: New agent architecture in Checkmk 2.1
With Checkmk 2.1, the agent architecture was modified to enable performance improvements and add new features such as TLS encryption, data compression, and the reversal of direction of communication from the agent. This will enable push mode and pull mode.
Ep. 30: Clustering the Checkmk appliance
9:17 English
Ep. 30: Clustering the Checkmk appliance
In this video, Robin demonstrates how you can cluster your Checkmk appliance to make it resilient against hardware failures. If you are using the Checkmk hardware appliance, it may be helpful to cluster your appliance to maintain high availability.
Ep. 32: Working with the Agent bakery in Checkmk
13:40 English
Ep. 32: Working with the Agent bakery in Checkmk
In this video, Robin demonstrates how to roll out agent packages with the required configuration for different monitored systems using the agent bakery in Checkmk. The "Automatic agent update" is quite a helpful feature as it pulls the latest configurations for an agent automatically and you don't need to manually update all of your agents deployed on different systems.
Ep 33: Monitoring Docker containers with Checkmk
9:20 English
Ep 33: Monitoring Docker containers with Checkmk
Learn how to monitor Docker containers with Checkmk.In this video, Robin demonstrates the process of setting up a rule to configure the docker plugin and bake an agent with the desired settings for the Docker host.
Ep 34: Introduction to Checkmk Ansible collection
5:06 English
Ep 34: Introduction to Checkmk Ansible collection
Last year the Checkmk Ansible collection was created to interact with the Checkmk REST API. In this video, Robin demonstrates how you can use this Ansible collection to automate your monitoring with Checkmk.
Ep 35: Monitoring SQL databases with Checkmk
5:18 English
Ep 35: Monitoring SQL databases with Checkmk
In this video, Robin demonstrates how you can configure your Checkmk site to monitor your SQL databases. As there are many flavours of SQL databases, the process is mostly the same.
Ep. 36: Introduction to different types of checks for monitoring with Checkmk
11:22 English
Ep. 36: Introduction to different types of checks for monitoring with Checkmk
Learn about the different types of "checks" and services in Checkmk. In this video, Robin demonstrates how you can expand the information collected by your Checkmk agent using these different "Checks".
Ep. 43: Working with Hardware/Software inventory in Checkmk
7:12 English
Ep. 43: Working with Hardware/Software inventory in Checkmk
In this video, Robin demonstrates the hardware/software inventory feature in Checkmk. With this feature one can get an overview of various pieces of hardware present in their servers, switches etc. and also the software packages installed on their operating system. Watch this video to learn more.
Ep. 48: Monitoring file servers with Checkmk
12:11 English
Ep. 48: Monitoring file servers with Checkmk
Monitoring file servers is essential for ensuring best experience for people working remotely. In this video, Bastian demonstrates various configuration options in the file system check one can use to monitor their file server efficiently.
Ep. 50: Working with the push mode of the Checkmk agent
10:17 English
Ep. 50: Working with the push mode of the Checkmk agent
A new feature “Push mode” has been added in the Checkmk agent since the Checkmk version 2.2. The Checkmk agent pushes the data transmission on its own and does not wait for a request from the server. This is especially useful when Checkmk server cant access the network of the monitored host or for example in the cloud.
Ep. 51: Automated host creation in Checkmk
15:56 English
Ep. 51: Automated host creation in Checkmk
In this tutorial, Sudhir demonstrates how to use the auto-registration and automated host creation feature in Checkmk. The user can easily create hosts and register for the push mode automatically. As cloud objects are created and often deleted, they needed to be added to checkmk without delay, this feature helps in solving this problem.
See it yourself

Try out Checkmk now.

Get the Raw Edition Free and open source monitoring
Play with Checkmk Try Checkmk without installing