Kimai Kimai - Documentation
Cloud

Azure SAML

Go back to general SAML configuration for Kimai.

SAML authentication with Azure accounts has proven to work. It requires four phases to get SAML configured. We will call them:

  • Toolkit Setup
  • Kimai Configuration
  • Adding Users and Testing the Toolkit

Note: The Azure AD is a part of the Microsoft Cloud offerings; you will likely need either a Microsoft Cloud license or an Office 365 license associated with your domain. But it also works with a “Usage based Microsoft Azure Plan” account in which Azure AD can be used free of charge.

Toolkit Setup

Please check the following steps to set up an enterprise application using the SAML toolkit. This documentation is available in other languages as well in the Microsoft documentation

  1. Sign in to the Azure portal.
  2. On the left navigation pane, select the Azure Active Directory service.
  3. Navigate to Enterprise Applications and then select All Applications.
  4. To add new application, select New application.
  5. In the Add from the gallery section, type Azure AD SAML Toolkit in the search box.
  6. Select Azure AD SAML Toolkit from the results panel and then add the app.
  7. On the left navigation panel, select the Azure Active Directory service.
  8. Navigate to App registrations and then select All Applications.
  9. Please click on the newly created application Azure AD SAML Toolkit and then select Branding on the left navigation bar to change the name of the application to “Kimai”.
    Note: The name of the application has no technical effect, but could be displayed to users during login.
  10. Click on Overview on the left navigation panel. Now click on the value under Managed application in local directory: Picture
  11. Now navigate to Single sign-on on the left navigation and choose SAML as your choice: Picture

  12. Edit the Basic SAML Configuration at the top and add the required URLs: Picture

    Setting Value
    Identifier (Entity ID) https://timetracking.example.com/auth/saml/metadata
    Reply URL (Assertion Consumer Service URL) https://timetracking.example.com/auth/saml/acs
    Sign on URL https://timetracking.example.com/
    Logout Url https://timetracking.example.com/auth/saml/logout
  13. Edit the User Attributes & Claims and ensure the following settings: Picture
  14. Return to the Single Sign-On (visible in the left navigation panel) and download Certificate (Base64): Picture
  15. Copy the three values of Set up Kimai, as we will need them to configure Kimai: Picture

Kimai Configuration

Please copy & paste the entire SAML configuration. Adjust the following keys with your Azure / App specific settings:

kimai:
    saml:
        activate: true
        title: Login with Azure
        mapping:
            - { saml: $http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name, kimai: username }
            - { saml: $http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, kimai: email }
            - { saml: $http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname $http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname, kimai: alias }
            - { saml: $http://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname, kimai: title }
            - { saml: $http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid, kimai: accountNumber }
        roles:
            attribute: Groups
            mapping:
                - { saml: xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx, kimai: ROLE_ADMIN }
                - { saml: Azure-Group-Object-Id, kimai: ROLE_TEAMLEAD }
        connection:
            idp:
                entityId: 'https://sts.windows.net/****-****-***/'
                singleSignOnService:
                    url: 'https://login.microsoftonline.com/****-****-***/saml2'
                x509cert: 'ADD YOUR CERTIFICATE HERE'
            sp:
                entityId: 'https://timetracking.example.com/auth/saml/metadata'
                assertionConsumerService:
                    url: 'https://timetracking.example.com/auth/saml/acs'
                singleLogoutService:
                    url: 'https://timetracking.example.com/auth/saml/logout'
  1. Change the title to the wanted text on the login screen 
    title: Login with Azure
  2. Change the idp configuration and add the before copied URLs: 
    entityId: 'https://sts.windows.net/****-****-***/'                # Azure AD Identifier
singleSignOnService:
 url: 'https://login.microsoftonline.com/****-****-***/saml2'  # Login URL
 binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'
singleLogoutService:
 url: 'https://login.microsoftonline.com/****-****-***/saml2'  # Logout URL
 binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'
  3. Change the sp configuration: 
    entityId: 'https://timetracking.example.com/auth/saml/metadata'
assertionConsumerService:
 url: 'https://timetracking.example.com/auth/saml/acs'
 binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST'
# logout does not seem to work properly
#singleLogoutService:
#    url: 'https://timetracking.example.com/auth/saml/logout'
#    binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'
  4. Change the x509cert by opening the earlier downloaded certificate and copy it, without “Next-line” Enters into the configuration: 
    x509cert:  'REALLY LONG SET OF CHARACTERS'
  5. Reload your cache

Adding Users and Testing the Toolkit

  1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.
  2. On the left navigation panel, select the Azure Active Directory service.
  3. Navigate to App registrations and then select All Applications.
  4. Please click on the Kimai application , we called it Kimai, and then navigate to Users and groups on the left navigation bar.
  5. Click on Add user/group and add the groups or users, who should have access.

You should now be able to test the Login by visiting https://timetracking.example.com/ and clicking on the title of the SAML method, you defined earlier.