Skip to main content

Knocknoc with ADFS

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

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, eg: https://your-knocknoc.cloud. 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. If you wish to optionally encrypt inner SAML assertions, you need to generate a key/cert and upload these to Knocknoc and then ADFS - see Create Certificates below
    1. SAMLCertFile, upload the certificate (.crt) file you created in during the Certificate creation.
    2. SAMLKeyFile, upload the key (.key) file you created in during the Certification creation.
  6. Click Save.
  7. 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 Relying Party Trust

  1. Log in to the Windows Server running ADFS

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

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

  4. Select Claims aware and Start to step through the wizard
  5. Select Import data about the relying party published online
  6. Enter the URL of your server, eg: https://your-knocknoc.cloud/api/saml/metadata
  7. Select Next
  8. 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 see note below
  9. Enter a Display name, eg: Knocknoc and click Next
  10. Select an appropriate access control policy and consider MFA, this can be changed later
  11. Click Next 
  12. A summary is now shown, click Next
  13. Select Configure claims issuance policy for this application, click Close

Define the Claim Issuance Policy

  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: Username 
  5. Incoming claim type should be set to UPN (or Windows account name if you prefer the login to be shown in the Knocknoc portal)
  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

Screenshot 2024-09-17 at 17.50.02.png

Repeat this process and add Name as UPN as realName

Screenshot 2024-09-17 at 17.50.06.png

Groups need to be passed via LDAP attributes, select Add then LDAP attributes

  1. Name the rule, eg: Groups
  2. Select Active Directory for the Attribute Store
  3. Add the attribute Token-Groups - Unqualified Names
  4. In the Outgoing Claim Type, type in groups (all lower case)

Screenshot 2024-09-17 at 18.19.44.png

Screenshot 2024-09-17 at 17.50.14.png

A session duration time (in minutes) is passed through for users - this can be a single value or defined per group

  1. Select Add Rule
  2. Select Send Claims using custom rule
  3. Type the below, noting the default is 420 minutes (7 hours)
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod"]
 => issue(Type = "sessionDuration", Value = "420");

Screenshot 2024-09-17 at 18.19.51.png

Screenshot 2024-09-17 at 17.50.21.png


You are now ready to test the integrated ADFS login!

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://your-knocknoc.cloud/
  2. There should now be an "Single Sign-On" 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 ADFS+SAML gauntlet.

Create certificates (optional)

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. If you wish to encrypt the inner assertions - This will be required for both sides of the connection, Windows AD FS and Knocknoc

TLS versions on Server <=2019

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.

image.png

Registry configuration to enable TLS/1.2:

Screenshot 2024-09-17 at 09.12.16.png Screenshot 2024-09-17 at 09.12.11.png