Single sign on with Okta
New Tutorial Available
A new tutorial is available here https://docs.pritunl.com/docs/okta
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 Okta will be used as the SAML provider, the Okta api will also be used to re-verify accounts on each vpn connection and optionally Okta Push will be used to send a push verification to a mobile device for each vpn connection. A Pritunl enterprise license is required for single sign-on.
Setup Single Sign-On with Okta
Before enabling single sign-on with SAML access parameters will need to be created. This can be done by logging into your Okta admin console and navigating to the Applications page. On the Applications page select Create New App. For the App name enter Pritunl and download the logo here and upload it to the application. Additional logos for other SAML providers can be found in the artwork repository.
On the next page enter https://auth.pritunl.com/v1/callback/saml as the Single sign on URL. For the Default RelayState enter the address your users would use to access the Pritunl server such as https://vpn.example.com:9700. For the Audience URI enter pritunl. In the attribute section add username with a value of user.login then email with a value of user.email. Optionally the attribute org can be included which can be mapped to a value such as user.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 View Setup Instructions these parameters will be used in the next step.
Enable SAML Single Sign-On
Once you have created the application on Okta single sign-on can be enabled in the Pritunl web console. Open the settings dialog in the web console and select Okta as the Single Sign-On mode. Then using the parameters on the previous page fill in the SAML Sign-On URL with the Identity Provider Single Sign-On URL then SAML Issuer URL with the Identity Provider Issuer and SAML Certificate with the X.509 Certificate.
To get the Okta API Token go to the API section in the Security tab and click Create Token. Name the token Pritunl and copy the Token value. The Okta 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.
Okta Push (Optional)
For additional security Okta Push can be used to send a push verification to a users mobile device when they connect to the vpn server. This will require the user to login with their Okta account and authenticate with Okta Push when downloading vpn keys. Connections to the vpn server will only require Okta Push authentication. To enable Okta push go to the Authentication section in the Security tab and select Multifactor. Then click Edit and select Okta Verify as well as the two options below. This will prompt users on the next login to install and configure Okta Push. No administrative actions are needed to get each user enrolled in Okta Push.
Then in the section below click Edit and set Require MFA when signing into Okta to Enabled. The Ask for additional factor option will only apply when users are logging into the Okta web console. When a user connects to the vpn server a push request will always be sent.
Once Okta Push is enabled go to the Sign On settings of the Pritunl application added earlier and select Add Rule at the bottom. Name the rule Okta Push and in the Access section enable Prompt for factor then select Every sign on. The frequency option will only apply when users are logging into the Pritunl web console to download vpn profiles. When a user connects to the vpn server a push request will always be sent.
Once configured Okta Push will be used as an additional authentication factor for vpn connections.
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.