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.

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)

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
```

1. 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. From the left-hand menu, select the "SSO" option (under "User Authentication").

1. Click the "Get Started" button.

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

1. Click Next

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

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

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

1. 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)

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

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

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. 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:

```
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 the permissions on the keys and xml:
```
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*,
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").

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* 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. From the left-hand menu, select the "SSO" option (under "User Authentication").

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

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

1. Click Next

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

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

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

1. 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)

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

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

## Knocknoc Configuration for Admins

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/admin-idp.xml` (Don't forget permissions: `chown knocknoc:knocknoc admin-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
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, 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").

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

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.