Related documentation

• Checkmk official documentation

• SAML authentication in distributed monitoring setups KB

• How-to work with Cyberark Workforce SAML KB

• Troubleshooting Azure SAML authentication failure KB

Overview

This guide walks you through the process of setting up SAML authentication in Checkmk with Okta as the identity provider. It covers configuration steps in both Checkmk and Okta, such as creating the SAML connection, exchanging metadata, and configuring user attribute mappings, to enable users to log in to Checkmk using their Okta credentials.

Step-by-step guide

These are preliminary steps to set up SAML authentication with Okta as the provider. This example covers a basic configuration to get started and may require further refinement for production use.

Create a new SAML authentication connection in Checkmk

1. Click Setup → Users → SAML Connection → SAML Authentication → Add Connection.
   

   
   
   

2. In the Connection section, select URL for Identity Provider metadata. Enter a placeholder domain for now, this is only to allow the page to save.
   
   

3. Enter the FQDN (Fully Qualified Domain Name) of your Checkmk instance. Ensure that HTTPS is enabled, and the site is publicly accessible.
   

   
   
   

4. In the Users section, use the following schema URI to set the email address as the User ID attribute:

   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

   Open

   

    

5. Save the connection.
   
   

6. Click the Edit icon (pencil) next to the new connection.

    

7. Checkmk generates the connection information that you will use to configure Okta.

   Open

   

Create a new App Integration in Okta

1. Log in to the Okta Admin Console at https://admin.okta.com.
   
   

2. Click on Applications → Applications.

   Open

   

    

3. Click on Create App Integration.

   Open

   

   
   
   

4. Select SAML 2.0.

   Open

   

    

5. Enter a name in the App name field.

   Open

   

    

6. In Checkmk, find the Assertion Consumer Service endpoint in your saved SAML connector and enter it as the Single Sign-On URL in your Okta app.
   
   Via Checkmk
   

   
   
   

7. Enter the Entity ID value from Checkmk into the Audience URI (SP Entity ID) field in Okta.

    

8. Enter the Metadata endpoint value from Checkmk into the Default RelayState field in Okta.

    

9. Set the Name ID format dropdown to EmailAddress.

    

10. Set the Application username dropdown to Okta username.
    
    

11. Set the Update application username on dropdown to Create and update.
    
    Required URLs

    • Single Sign-on URL: https://monitor.example.com/cmk/check_mk/saml_acs.py?acs

    • Audience URI: https://monitor.example.com/cmk/check_mk/saml_metadata.py

    • Default RelayState: https://monitor.example.com/cmk/check_mk/saml_metadata.py?RelayState=okta

    Open

    

     

12. Go to Applications → Applications → Click on the application you made → General tab → Click Edit next to SAML Settings.
    
    

    Open

    

     

    Open

    

     

13. Under Attribute Statements, add one with the following settings:

    • Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    • Name format: URI reference

    • Value: user.email

    Open

    

     

14. Assign users to the application in Okta by navigating to the Assignments tab of your app and selecting one or more users or groups.
    
    

    Open

    

Completing configuration

1. Click Setup → Users → SAML Connection → SAML Authentication → Edit the Connection

   Open

   

    

2. In Okta, go to the Sign On tab of your application, copy the Metadata URL, and paste it into the field that contains the placeholder under the Identity Provider metadata key in Checkmk.

   Open

   
   Open

   

3. Save the configuration and Activate changes.
   
   

4. Sign out of Checkmk.

    

5. At the sign-in screen, select Sign in with Okta and enter the Okta credentials you configured.

Configuring and syncing contact groups and roles

By integrating Okta groups with Checkmk, users can be automatically assigned the appropriate contact groups and roles based on their group membership in Okta. This eliminates the need for manual user role or contact group configuration after the initial setup.

Create and assign Okta groups

1. In Okta, click on Directory → Groups.

   Open

   

    

2. Click Add group.

   Open

   

   
   
   

3. Create user groups that align with your Checkmk contact groups and roles. You must ensure that the contact group names match exactly. 
   

   
   
   Example:

   • Role Group: Checkmk_Admins for users who should have administrator privileges.

   • Contact Group: Network_Operations for users in the corresponding Checkmk contact group.
     
     

4. Click Save.
   
   

5. Add the appropriate users to each group based on their responsibilities.
   
   

Add group attribute statements in Okta

1. In Okta, go to Applications → select your Checkmk app.

   Open

   

    

   Open

   

   
   
   

2. Navigate to the Sign On tab and click Edit under the SAML Settings section. Scroll Down and click in Show legacy configuration.

   Open

   

    

   Open

   

   
   
   

3. Scroll down to Group Attribute Statements (optional) and click Add Group.

   Open

   

    

4. Fill in the fields as follows:

   • Name: http://schemas.xmlsoap.org/claims/Group

   • Name format: URI Reference

   • Filter: Select Matches regex

   • Value: .*

5. Click Save.

This configuration allows Okta to include all group names in the SAML assertion sent to Checkmk.

Map groups to contact groups in Checkmk

1. In Checkmk, go to Setup > General > User Management > SAML Authentication.

2. Edit your Okta SAML configuration.

3. In the Contact groups section:

   • Set the dropdown to Map value to specific groups.

   • For Claim name, enter:
     http://schemas.xmlsoap.org/claims/Group

   • For each group mapping:

     • Enter the Okta group name (e.g., Network_Operations) in the Attribute match value field.

     • Select the corresponding Checkmk contact group.

   Open

   

Map groups to roles in Checkmk

1. In the same SAML configuration screen, scroll to the Roles section.
   
   

2. Set the dropdown to Map roles.
   
   

3. For Role attribute, enter:
   http://schemas.xmlsoap.org/claims/Group
   
   

4. For each role:
   

   • Check the box next to the role (e.g., Administrator).

   • Enter the Okta group name (e.g., Checkmk_Admins) in the corresponding text field.
     
     

5. Click Save and activate changes.

Optional for Testing Purpose Password Only Policy

Whenever you would like to setup a SAML Okta Test environment, it might be useful to setup a Password only Policy. This can be done by at Authentication Policies.

Open

Create the policy

Open

Setup Access Allowed with password

Open

Add the Application to the Policy

Open

Related articles