Skip to main content

SAML with Jumpcloud - Users and Admins

This document describes the necessary configuration work required to make Knocknoc (optionally) use a JumpCloud SAML Identity Provider ("IdP") as an authentication mechanism for Knocknoc. It assumes that you already have administrative access to an operational JumpCloud tenant, and that Knocknoc is installed, configured, and running on https://access.example.com.

Knocknoc supports having 2 IdPs, one for users, and one for admins. Please see the later section for Admins Click here for Admin setup

First setup users, and then we can setup admins.

Generate SAML Service Provider keypair

SAML uses X.509 certificates and RSA key pairs to authenticate the IdP (JumpCloud) and the Service Provider ("SP", ie Knocknoc) to each other, and make sure that nobody's doing any lying about the whole operation. JumpCloud will sort out the cert/key for its end, so we just need to issue a self-signed certificate for Knocknoc for a key that we generate.

  1. Create a self-signed certificate and RSA private key for Knocknoc, by running the following command:

    cd /opt/knocknoc/etc/
openssl req -new -x509 -days 3650 -nodes -subj /CN=Knocknoc/ -out user-idp.crt -keyout user-idp.key

    For your admin SAML, you need a seperate key

    cd /opt/knocknoc/etc/
openssl req -new -x509 -days 3650 -nodes -subj /CN=Knocknoc/ -out admin-idp.crt -keyout admin-idp.key

  2. Set the permissions to be correct for the knocknoc user to access the key:

   chown knocknoc:knocknoc *.key
   chown knocknoc:knocknoc *.crt
  1. Download a copy of the certificate (just the certificate) to your local workstation, as you'll need to upload it to JumpCloud in the next phase of configuration.

JumpCloud Configuration for User SAML

  1. Login to your JumpCloud tenant as an administrator.

  2. From the left-hand menu, select the "SSO" option (under "User Authentication").

  3. Click the "Get Started" button.

  4. Click Select on Custom Application in the bottom right of the Featured Applications pane

  5. Click Next

  6. Choose Manage Single Sign-On, and then Configure SSO with SAML then Next.

  7. Enter a Name for your application, like Demo Knocknoc, and under Advanced Settings, drop down and enter a URL that sounds unique enough, for the SSO IdP URL: like demoknocknoc

  8. Then choose Configure Application and we are onto the hard bit

  9. In the "Single Sign-On Configuration" section, and start filling out form items. Remember to replace https://access.example.com with the public URL of your Knocknoc service.

    • IdP Entity ID: "Knocknoc" is a good default, but if there's more than one Knocknoc in the JumpCloud tenant, choose something else that sounds good.
    • SP Entity ID: https://access.example.com/api/saml/metadata
    • ACS URL: https://access.example.com/api/saml/acs
    • SP Certificate: Click 'Upload SP Certificate', and choose the certificate you generated in the previous section. If all goes well, you'll get a little pop-up saying "successfully read SP certificate".
    • SAMLSubject NameID: username
    • SAMLSubject NameID Format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    • Signature Algorithm: RSA-SHA256 (should already be set to that)
    • Sign Assertion: tick this box
    • Default RelayState: leave blank
    • Login URL: https://access.example.com/api/login/saml
    • Declare Redirect Endpoint: tick this box
    • IDP URL: https://sso.jumpcloud.com/saml2/knocknoc (can be something else if there's more than one Knocknoc in the JumpCloud tenant)
    • User Attribute Mapping:
      1. Tell JumpCloud to tell Knocknoc the real name of the user:
      • Service Provider Attribute Name: realName
      • JumpCloud Attribute Name: fullname
    • Constant Attributes:
      1. Tell JumpCloud to tell Knocknoc how long to keep sessions open:
      • Service Provider Attribute Name: sessionDuration
      • Value: however many minutes SAML users' sessions should last
    • Group Attributes:
      1. Tell JumpCloud to pass the list of groups to Knocknoc:
      • Include group attribute: tick this box
      • Unlabelled text box: groups (the boilerplate says memberOf, which is naughty)

  10. After that fairly massive effort, you can now click "save". Phew!

  11. If all goes well, you'll get a pleasant "SSO application created" pop-up.

  12. Finally, go back into the newly-created SSO application, scroll down, expand the "SSO" heading, and click "Export Metadata". Save this file locally somewhere, we'll use it shortly. This is an XML file full of the details that Knocknoc needs to use the IdP.

Knocknoc Configuration

  1. Upload the IdP metadata you downloaded in the previous section to the Knocknoc server in a location that Knocknoc can access, You might want to move the keys you made earlier to above location:

  2. Upload the cert and key you created

If all has gone according to plan, the Knocknoc login page should now have a new "SSO Login" link on it. This is the magic button to login with SAML. However, at present it won't work for anyone because they don't have the necessary JumpCloud magicks to work. That'll be sorted out in the next section.

JumpCloud Group / User Configuration

Back into the JumpCloud admin panel now. First off, we'll create some groups for our Knocknoc-capable users to be a part of.

  1. Select "User Groups" from the left-hand menu (under "User Management").

  2. Create zero or more groups to hold Knocknoc-capable JumpCloud users. For the most part, there's nothing special about them, and you can in theory use existing JC groups. However, the caveats are:

    • The name of the group in JumpCloud must match exactly (capitalisation, spaces and all) the name of the corresponding group in Knocknoc, if you want that group to grant access to the ACLs of the corresponding Knocknoc group.

    • The same "strict match" rule applies to the JC group name for the SAMLAdminGroup you configured.

    • The group must be bound to the JumpCloud application you configured previously (it must be ticked in the list under the "Applications" tab of the group) otherwise the group won't be sent to Knocknoc.

Finally, assign users to the groups you've bound to the Knocknoc application -- probably by going to the "Users" tab of the group and ticking away like a dog running through the bush.

JumpCloud Configuration for Admin SAML

  1. Login to your JumpCloud tenant as an administrator. Note this can be a seperate Jumpcloud to your User tenant.

  2. From the left-hand menu, select the "SSO" option (under "User Authentication").

  3. Click the "Get Started" button or Add Application if you already have some.

  4. Click Select on Custom Application in the bottom right of the Featured Applications pane

  5. Click Next

  6. Choose Manage Single Sign-On, and then Configure SSO with SAML then Next.

  7. Enter a Name for your application, like Demo Knocknoc, and under Advanced Settings, drop down and enter a URL that sounds unique enough, for the SSO IdP URL: like demoknocknoc

  8. Then choose Configure Application and we are onto the hard bit

  9. In the "Single Sign-On Configuration" section, and start filling out form items. Remember to replace https://access.example.com with the public URL of your Knocknoc service.

    • IdP Entity ID: "Knocknoc" is a good default, but if there's more than one Knocknoc in the JumpCloud tenant, choose something else that sounds good.
    • SP Entity ID: https://access.example.com/api/admin/saml/metadata
    • ACS URL: https://access.example.com/api/admin/saml/acs
    • SP Certificate: Click 'Upload SP Certificate', and choose the certificate you generated for admin in the previous section. If all goes well, you'll get a little pop-up saying "successfully read SP certificate".
    • SAMLSubject NameID: username
    • SAMLSubject NameID Format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    • Signature Algorithm: RSA-SHA256 (should already be set to that)
    • Sign Assertion: tick this box
    • Default RelayState: leave blank
    • Login URL: https://access.example.com/api/admin/login/saml
    • Declare Redirect Endpoint: tick this box
    • IDP URL: https://sso.jumpcloud.com/saml2/knocknocadmin (can be something else if there's more than one Knocknoc in the JumpCloud tenant)
    • User Attribute Mapping:
      1. Tell JumpCloud to tell Knocknoc the real name of the user:
      • Service Provider Attribute Name: realName
      • JumpCloud Attribute Name: fullname
    • Constant Attributes:
      1. Tell JumpCloud to tell Knocknoc how long to keep sessions open:
      • Service Provider Attribute Name: sessionDuration
      • Value: however many minutes SAML users' sessions should last
    • Group Attributes:
      1. Tell JumpCloud to pass the list of groups to Knocknoc:
      • Include group attribute: tick this box
      • Unlabelled text box: groups (the boilerplate says memberOf, which is naughty)

  10. After that fairly massive effort, you can now click "save". Phew!

  11. If all goes well, you'll get a pleasant "SSO application created" pop-up.

  12. Finally, go back into the newly-created SSO application, scroll down, expand the "SSO" heading, and click "Export Metadata". Save this file locally somewhere, we'll use it shortly. This is an XML file full of the details that Knocknoc needs to use the IdP.

Knocknoc Configuration for Admins

  1. Upload the IdP metadata you downloaded in the previous section to the Knocknoc server

  2. Upload the admin certs

Your knocknoc admin section is at https://access.example.com/admin, or whatever you called your site. If all has gone according to plan, the Knocknoc login page should now have a new "SSO Login" link on it. This is the magic button to login with SAML. However, at present it won't work for anyone because they don't have the necessary JumpCloud magicks to work. That'll be sorted out in the next section.

JumpCloud Group / User Configuration

Back into the JumpCloud admin panel now. First off, we'll create some groups for our Knocknoc-capable users to be a part of. Admins can't be part of groups, and hence can't have ACLs assigned to them. I suppose you could make your /admin URL be only accessible after a user auths to knocknoc, which we will cover later.

  1. Select "User Groups" from the left-hand menu (under "User Management").

  2. Create zero or more groups to hold Knocknoc-capable JumpCloud admins. For the most part, there's nothing special about them, and you can in theory use existing JC groups. However, the caveats are:

    • The name of the group in JumpCloud must match exactly (capitalisation, spaces and all) the name of the corresponding group in Knocknoc, if you want that group to grant access to the ACLs of the corresponding Knocknoc group.

    • The group must be bound to the JumpCloud application you configured previously (it must be ticked in the list under the "Applications" tab of the group) otherwise the group won't be sent to Knocknoc.

Finally, assign users to the groups you've bound to the Knocknoc application -- probably by going to the "Users" tab of the group and ticking away like a dog running through the bush.

Final Testing

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

To ensure you're up and running, pop over to your Knocknoc server in a browser and click on the "SSO Login" button. You may be prompted to login to JumpCloud (your user account, not an admin account), but if you logged into JumpCloud recently, you should just be dropped into a logged-in Knocknoc session, either as a Knocknoc admin (if your JC user is in the SAMLAdminGroup group) or otherwise as an ordinary user. In either event, you should have all the ACLs associated with the Knocknoc groups you're a member of in JC.

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

Back to top