SAML with EntraID (Azure AD)

The following example assumes your Knocknoc instance is located at https://demo.knoc.cloud. Wherever you see that, please substitute it for your own instance URL.

Setting Up the IdP

Create an Application

1. Navigate to the Microsoft Entra admin center and login with administrator credentials.
2. Go to Identity and select Enterprise Applications
   
3. Click New Application
4. Click Create your own application.
5. Type a name for your application (e.g  knocknoc)
6. Check "Integrate any other application you don't find in the gallery (Non-gallery)"
7. Click Create.

Assign Groups

1. Click "Assign users and groups"
2. Click "None Selected" under groups.
3. Add the user groups you wish to access Knocknoc protected services.
   

SAML Configuration

Configure the app to use SAML

1. Click Set up single sign on.
2. Click SAML.
3. In the Basic SAML section, add the links to your Knocknoc instance.
   1. Set the Indentifier (Entity ID) to https://demo.knoc.cloud/api/saml/metadata for Admin SAML integration the URI path is: /api/admin/saml/metadata)
      
   2. Set the Reply URL (Assertion Consumer Service URL) to https://demo.knoc.cloud/api/saml/acs (and /api/admin/saml/acs for Admin)
   3. Leave the Optional Basic SAML Configuration options blank at this stage and click Save.

Configure the Attributes & Claims

1. In the Attributes & Claims section:
2. Update the Required Claim, changing the Name Identifier Format to Persistent
   
   
3. Remove all other Claims (delete).
4. It should look like the below:

1. Click "Add a group claim".
   
   1. Select Security Groups
   2. Select Group ID for the Source Attribute. 
   3. Check "Customize the name of the group claim" Under Advanced Options
   4. Add the Name as, groups.
   5. Click save when done.
      

      Mapping Entra groups can be done in two ways:

      1) Using "Security Groups", which supports 365/Cloud groups plus Hybrid groups. The UUID or Object ID must be used, you cannot simply use a group name (string), you must use the object IDs (e.g. 6a696eec-482f-4b40-97c8-9ea3dba8ac3a) as the group name in your Knocknoc configuration. 

       

      2) Using "Groups assigned to the application", then selecting "Cloud-only group display names", which allows you to use group ID strings, eg: "Developers" or "US-Admin-SSH" instead of UUID Object ID values. These groups must also be specifically assigned to the application in order to use them.

      

      For Admin SAML, you can simply assign users directly to the enterprise-application, and ignore groups entirely.

   6. Click "Add new claim"
      1. Set the Name as "realName".
      2. Leave Source as Attribute.
      3. Set Source Attribute to "user.displayname".

          

         
         
   7. Add another new claim (click "Add new claim")
      1. Set the Name as "sessionDuration"
      2. Leave Source as Attribute.
      3. Set Source Attribute to the default login duration in minutes for users logging in to Knocknoc. You can manually override this with a user attribute later for specific users, or control this per-Knoc within Knocknoc.
      4. This is a whole number, eg: 480. Do not add the quotation marks as Entra displays in the image below!
         
   8. Add a third new claim
      1. Set the Name as "username"
      2. Leave Source as Attribute.
      3. Set Source Attribute "user.userprincipalname"
         
         

Attributes & Claims overview

1. Once the claims are completed, it should look something like this (depending on the 480 minutes value below)

Metadata url

1. Copy the App Federation Metadata Url and save it, you will need it in the next step configuring Knocknoc.

   

2. It is worth testing the SAML configuration using step 4 in Entra:

   

3. Now configure Knocknoc.
   

Knocknoc SAML Config

Knocknoc supports SAML for Users and/or for Administrators. Initially we suggest configuring SAML for Users, and once confirmed as working extending this to the Administrator users, whilst retaining a break-glass local Admin user for emergencies or broken SAML situations.

1. Login In the Knocknoc admin interface.
2. Click on Settings on the left.
   
3. For the "Metadata URL", paste in the "App Federation Metadata Url" you previously saved. It starts with https://login.microsoftonline.com/...
   
4. Click "Generate new keypair"
   1. You are OK to save.
   2. Optionally - If instead of creating keys on the Knocknoc server you want to create keys manually, follow these steps.
5. Click Save.

Final Testing

Assuming you granted your own user permission to one or more Knocknoc groups in EntraID, you should now be able to login to Knocknoc using SSO.

1. Browse to https://demo.knoc.cloud
2. There should now be an "SSO Login" button.
3. Click this, if you are not already authenticated to your IdP you should now be directed to the IdP login page. Note: If you are already authenticated you'll simply be redirected to an authenticated Knocknoc session.
4. If ACLs have already been added you should also see these now say Granted.

You can also test using the Entra testing tool which is in Step 5 of the Entra configuration, shown below. Remember you will need to log in with a User or Group you granted access previously.

If this all works, congratulations! You've successfully run the SAML gauntlet.

Now it is time to create ACLs and assign them to the Entra SAML Groups.

Entra Groups

Entra passes Group information through SAML using the Group GUID.

To obtain this for a particular group, view the Group in the Entra Admin portal.

The relevant GUID is then placed as the Group Name in Knocknoc, which will be matched automatically and assign the Group Users, to the Knocknoc ACL.

Explicitly assigned groups (performance/security)

For additional security or large environments with many groups (end user login performance) - you can explicitly only pass/permit groups that have been a) assigned to the user AND b) assigned to the Enterprise Application.

To do this, adjust the groups to be "groups assigned to the application", as below: