Skip to main content

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 Applications than Enterprise Applications
    Enterprise Application Menu.png
  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.

Create Application.png

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.

Note: for automatic user assignment, you must add groups into Knocknoc admin using matching Entra object IDs (e.g. 6a696eec-482f-4b40-97c8-9ea3dba8ac3a) as their names. We recommend you add a friendly name in the description field. Best practice is to have at least one group per Knocknoc protected service.

SAML Configuration

  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
    2. Set the Reply URL (Assertion Consumer Service URL) to https://demo.knoc.cloud/api/saml/acs
    3. Leave the Optional Basic SAML Configuration options blank at this stage and click Save.
  4. In the Attributes & Claims section
    1. Update the Required Claim, changing the Name Identifier Format to Persistent
      image.png
    2. Remove all other Claims.
    3. 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.
        Group Claim.png
    4. Add in a New Claim
      1. Set the Name as "realName".
      2. Leave Source as Attribute.
      3. Set Source Attribute to "user.displayname".

         

        3Crimage.png
    5. Add another New Claim
      1. Set the Name as "sessionDuration"
      2. Leave Source as Attribute.
      3. Set Source Attribute to the default login duration in seconds for users logging in to Knocknoc. You can manually override this with a user attribute later for specific users.image.png
    6. Add a third New Claim
      1. Set the Name as "username"
      2. Leave Source as Attribute.
      3. Set Source Attribute "user.userprincipalname"
        image.png

  5. Go to SAML Certificates section
    1. On your local machine: generate a new certificate and key, this can be done on a Linux host using the below command.
      openssl req -new -x509 -days 3650 -nodes -subj /CN=Knocknoc/ -out user-demo-knoc-cloud.crt -keyout user-demo-knoc-cloud.key
    2. Convert the certificate to pfx using the following command.
      openssl pkcs12 -export -out user-demo-knoc-cloud.pfx -inkey user-demo-knoc-cloud.key -in user-demo-knoc-cloud.crt
    3. Enter a password and note it down.
    4. Import Certificate, select the pfx certificate you just created and enter the password.
    5. It should automatically be set as Active. If it is not, click the dots on the right and choosing Make Certificate Active.
      image.png
  6. Copy the App Federation Metadata Url and save it, you will need it in the next step configuring Knocknoc.

    Screenshot 2025-03-13 at 17.32.58.png

  7. 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. For the SAMLKeyFile, upload the key (.key) file you created in during the SAML Configuration.
  5. For the SAMLCertFile, upload the certificate (.crt) file you created in during the SAML Configuration.
  6. 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.

Screenshot 2025-03-13 at 17.33.30.png

 

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

Back to top