SAML with ADFS

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.

 

Create certificates

Create a key/certificate pair on your local machine

1. 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. Enter a password and note it down.
3. This will be required for both sides of the connection, Windows AD FS and Knocknoc

Knocknoc SAML Config

1. Login In the Knocknoc admin interface (eg: https://your-knocknoc.cloud/admin/)
2. Click on Settings on the left.
   
3. Under Public URL enter you knocknoc url. Note: do not add a / at the end of the URL.
4. For the SamlMetadataUrl enter your ADFS host, adding /FederationMetadata/2007-06/federationmetadata.xml
   1. eg: https://your-adfs-site/FederationMetadata/2007-06/federationmetadata.xml
5. For the SAMLCertFile, upload the certificate (.crt) file you created in during the Certificate creation.
6. For the SAMLKeyFile, upload the key (.key) file you created in during the Certification creation.
   
7. Click Save.
8. You can verify this worked correctly by visiting https://your-knocknoc.cloud/api/saml/metadata and observing the downloaded metadata file.

Setting Up the IdP (ADFS)

Define the Claim Description

1. Log in to the Windows Server running ADFS

2. In Server Manager, select Tools, and then select AD FS Management.

3. Expand Service and select Claim Descriptions
4. Select Add Claim Description on the right hand panel
   
5. Set Display name to something meaningful, eg: Knocknoc Persistent Identifier
6. Set Short Name to Knocknoc
7. Set the Claim type to: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
8. Tick both boxes underneath, Publish this claim ...
9. Once saved it should look like the below:

Define the Relying Party Trust

1. Navigate to Relying Party Trusts underneath the AD FS section (within the AD FS Management MMC)

2. Select Add Relying Party Trust from the right hand panel

3. Select Claims aware and Start to step through the wizard
4. Select Import data about the relying party published online
5. Enter the URL of your server, eg: https://demo.knocknoc.io/api/saml/metadata
6. Select Next
7. If you receive a TLS error, you must enable TLS/1.2 via the registry (see https://learn.microsoft.com/en-us/mem/configmgr/core/plan-design/security/enable-tls-1-2-client#configure-for-strong-cryptography) and note below [1] 
8. Enter a Display name, eg: Knocknoc and click Next
9. Select an appropriate access control policy and consider MFA, this can be changed later
10. Click Next 
11. A summary is now shown, click Next
12. Select Configure claims issuance policy for this application, click Close

Define the RelyingClaim PartyIssuance TrustPolicy

1. Once on the Edit Claim Issuance Policy section

2. Click Add Rule
3. Select Transform and Incoming Claim, click Next
4. Name the rule, eg: Knocknoc
5. Incoming claim type should be set to Windows account name
6. Outgoing claim type: Name ID
7. Outgoing name ID format: Persistent Identifer
8. Click Finish and Apply
9. It should appear similar to the below

 

TLS errors and enabling TLS/1.2

If you receive TLS/SSL errors trying to validate the metadata file, you may need to enable TLS/1.2 via your registry.

Registry configuration to enable TLS/1.2:

 

 

 

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: Knocknoc and EntraID group names need to match for automatic user assignment. 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
      
      
   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.
         
         
   4. Add in a New Claim
      1. Set the Name as "realName".
      2. Leave Source as Attribute.
      3. Set Source Attribute to "user.displayname".

          

         
         
   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.
         
   6. Add a third New Claim
      1. Set the Name as "username"
      2. Leave Source as Attribute.
      3. Set Source Attribute "user.userprincipalname"
         
         
         
5. Go to SAML Certificates section
   
   1. 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. Then make the new certificate Active by clicking the dots on the right and choosing Make Certificate Active.
      
      
   6. Download the federation Metadata XML.
      
6. Set Up Knocknoc
   1. Copy the Login URL, this will be required for the Knocknoc SAML config.

Knocknoc SAML Config

1. Login In the Knocknoc admin interface.
2. Click on Settings on the left.
   
3. Under Public URL enter you knocknoc url. Note: do not add a / at the end of the URL.
4. For the SAMLMetaDataFile, upload the xml file you downloaded from EntraID.
5. For the SAMLCertFile, upload the certificate (.crt) file you created in during the SAML Configuration.
6. For the SAMLKeyFile, upload the key (.key) file you created in during the SAML Configuration.
7. For the SAMLMetadataUrl, paste the Login URL copied in Step 6 of the previous section.
   
8. 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.

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