Skip to main content

SAML with Jumpcloud

#

Configuring Knocknoc to use JumpCloud SAML for Users

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.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](#jumpcloud-configuration-for-admin-saml)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. 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. ```


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

   chown knocknoc:knocknoc *.key
 
   chown knocknoc:knocknoc *.crt
```

1.

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


    2. ##

JumpCloud Configuration for User SAML

  1. 1. Login to your JumpCloud tenant as an administrator.

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

  3. 1. Click the "Get Started" button.

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

  5. 1. Click Next

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

  7. 1. 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. 1. Then choose Configure Application and we are onto the hard bit


  9. 1. In the "Single Sign-On Configuration" section, and start filling out
      form items. Remember to replace `https://access.example.com`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`
      metadata
      •  *
    • ACS URL: `https://access.example.com/api/saml/acs`
      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`
      username
      •  *
    • SAMLSubject NameID Format: `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
      persistent
      •  *
    • Signature Algorithm: `RSA-SHA256`SHA256 (should already be set to that)
      •  *
    • Sign Assertion: *tick this box*
      box
      •  *
    • Default RelayState: *leave blank*
      blank
      •  *
    • Login URL: `https://access.example.com/api/login/saml`
      saml
      •  *
    • Declare Redirect Endpoint: *tick this box*
      box
      •  *
    • IDP URL: `https://sso.jumpcloud.com/saml2/knocknoc`knocknoc (can be something else if there's more than
        one Knocknoc in the JumpCloud tenant)
      •  *
    • User Attribute Mapping:
        1.
      1. Tell JumpCloud to tell Knocknoc the real name of the user:
      *
      • Service Provider Attribute Name: `realName`
        realName
        •      *
      • JumpCloud Attribute Name: `fullname`
        fullname
      *
    • Constant Attributes:
        1.
      1. Tell JumpCloud to tell Knocknoc how long to keep sessions open:
      *
      • Service Provider Attribute Name: `sessionDuration`
        sessionDuration
        •      *
      • Value: *however many minutes SAML users' sessions should last*
        last
      *
    • Group Attributes:
        1.
      1. Tell JumpCloud to pass the list of groups to Knocknoc:
      *
      • Include group attribute: *tick this box*
        box
        •      *
      • Unlabelled text box: `groups`groups (the boilerplate says `memberOf`memberOf, which is naughty)

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

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

  12. 1. 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. 1. Upload the IdP metadata you downloaded in the previous section to the Knocknoc server in a location that Knocknoc can access, eg `/opt/knocknoc/etc/user-idp.xml`
      
    1. Edit the `/opt/knocknoc/etc/knocknoc.conf` configuration file, and add the following settings:

       ```
       # Remember to replace this with your actual URL
       PublicURL = "https://access.example.com"

       # This is the IdP metadata file you downloaded from JumpCloud
       SAMLMetadataFile = "/opt/knocknoc/etc/user-idp.xml"

       # Cert+key you generated in section 1
       SAMLKeyFile = "/opt/knocknoc/etc/user-idp-key.pem"
       SAMLCertFile = "/opt/knocknoc/etc/user-idp-cert.pem"

       ```

    1. You might want to move the keys you made earlier to above location:

  2. ```
       mv /tmp/knocknoc.crt /opt/knocknoc/etc/user-idp-cert.pem
       mv /tmp/knocknoc.key /opt/knocknoc/etc/user-idp-key.pem
       ```

    1. You may also need to fix

    Upload the permissions on the keyscert and xml:
    key you ```
    created
    3. chown knocknoc:knocknoc /opt/knocknoc/etc/*
       ```

1. Restart Knocknoc, to pick up the new config.

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*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. 1. Select "User Groups" from the left-hand menu (under "User Management").

  2. 1. 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*theory use existing JC groups. However, the caveats are:

    •    * The name of the group in JumpCloud must match *exactly*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`
       SAMLAdminGroup you configured.

    •    * The group *must*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. 1. Login to your JumpCloud tenant as an administrator. Note this can be a seperate Jumpcloud to your User tenant.

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

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

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

  5. 1. Click Next

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

  7. 1. 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. 1. Then choose Configure Application and we are onto the hard bit


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

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

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

  12. 1. 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. 1. Upload the IdP metadata you downloaded in the previous section to the Knocknoc server

    in
    2. a
  2. location that Knocknoc can access, eg `/opt/knocknoc/etc/admin-idp.xml` (Don't forget permissions: `chown knocknoc:knocknoc admin-idp.xml`)
      
    1. Edit

    Upload the `/opt/knocknoc/etc/knocknoc.conf`admin configuration file, and add the following settings:certs

    3.  ```
       # Remember to replace this with your actual URL
       PublicURL = "https://access.example.com"

       # This is the IdP metadata file you downloaded from JumpCloud
       AdminSAMLMetadataFile = "/opt/knocknoc/etc/admin-idp.xml"

       # Cert+key you generated in section 1
       AdminSAMLKeyFile = "/opt/knocknoc/etc/admin-idp.key"
       AdminSAMLCertFile = "/opt/knocknoc/etc/admin-idp.crt"

       ```

    1. Restart Knocknoc, to pick up the new config.

Your knocknoc admin section is at https://access.example.com/admin,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*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. 1. Select "User Groups" from the left-hand menu (under "User Management").

  2. 1. 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*theory use existing JC groups. However, the caveats are:

    •    * The name of the group in JumpCloud must match *exactly*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*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*should just be
 dropped into a logged-in Knocknoc session, either as a Knocknoc admin (if your JC user is in
 the `SAMLAdminGroup`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