Single sign on with OneLogin
New Tutorial Available
A new tutorial is available here https://docs.pritunl.com/docs/onelogin
Controlling access to Pritunl on large enterprise deployments can be difficult requiring manually adding users or integrating with the api. Single sign-on can be used to simplify access to Pritunl by allowing users to use an existing account with a SAML provider such as Okta or OneLogin to login to Pritunl. For this tutorial OneLogin will be used as the SAML provider, the OneLogin api will also be used to re-verify accounts on each VPN connection. A Pritunl enterprise license is required for single sign-on.
Setup Single Sign-On with OneLogin
Before enabling single sign-on with SAML access parameters will need to be created. This can be done by logging into your OneLogin admin console and navigating to the Add Apps page. On the Add Apps page select SAML Test Connector (IdP w/ attr w/ sign response). For the Display Name enter Pritunl and download the logo here and square logo here and upload it to the application then select Save. Additional logos for other SAML providers can be found in the artwork repository.
On the next page enter the address your users would use to access the Pritunl server such as https://vpn.example.com:9700 for the RelayState. Then enter https://auth.pritunl.com/v1/callback/saml as the Recipient, ACS (Consumer) URL Validator and ACS (Consumer) URL.
Next go to the Parameters page and first add parameters with a Field name of email and username. When adding the parameters select Include in SAML assertion. Then edit the parameters and use Email and Username as the Value. Optionally the attribute org can be included which can be mapped to a value such as Department this will add the user to the specified org by name if it exists. If org is not included the default SSO org will be used.
Once the application has been added select SSO these parameters will be used in the next step.
Enable SAML Single Sign-On
Once you have created the application on OneLogin single sign-on can be enabled in the Pritunl web console. Open the settings dialog in the web console and select OneLogin as the Single Sign-On mode. Then using the parameters on the previous page fill in the SAML Sign-On URL with the SAML 2.0 Endpoint (HTTP) and SAML Issuer URL with the Issuer URL. Then select View Details under the X.509 Certificate and copy the X.509 Certificate text to the SAML Certificate field. After the SAML attributes have been filled in get the OneLogin API Key by selecting API in the OneLogin Settings. Then select New Credential and select Read Users for the permission option. Copy the client ID and secret to the fields in the Pritunl settings. The OneLogin api is used to re-verify accounts on each VPN connection, this will prevent a disabled or deleted user from connecting.
Once SAML single sign-on is enabled a button will appear at the login screen to authenticate with SAML. When a user selects Sign in with SAML they will directed to the SAML provider to authenticate. Once authenticated they will directed to the profile page where they can download their vpn profiles.
SAML + Duo
It is recommended to use Okta for single sign-on with push authentication which is easier to configure and has included support for push verification using Okta Push. The Okta tutorial can be found here. For additional security SAML and Duo can be used for authentication. This will require the user to login with their SAML account and authenticate with Duo when downloading vpn keys. Connections to the vpn server will only require Duo authentication. The SAML username must match the Duo username when using both. If the usernames do not match the SAML attribute should be change to a value that does match such as the users email.
The SAML validation filter can be modified for more detailed control over what users have access and what organization the user will be added to. Additional details and instructions for coding custom filters for SAML can be found on the Pritunl Github Repository.