A BOSH deployment to get started using ssoca for OpenVPN servers or SSH bastion hosts. Consider the caveats before using these configurations in production.
The deployment.yml will get you started with a basic ssoca server. It is simply the ssoca server itself and does not yet know how to authenticate users or provide access to any services. Subsequent sections provide additional, default ways of customizing these behaviors.
Variables
ssoca_env_name- a slug-like alias which will be recommended to users when configuring this environment locallyssoca_env_title- a human-friendly name which briefly describes this environment to usersssoca_public_hostname- the domain or IP address where this server should be accessedssoca_public_ip- the public IP which should be assigned as a VIP network to the VM
Example
bosh deploy deployment.yml \
--var ssoca_env_name=acme-prod-gcp \
--var ssoca_env_title="ACME Production Primary Environment (Google Cloud)" \
--var ssoca_public_hostname=jump.prod1-gcp.acme-internal.com \
--var ssoca_public_ip=203.0.113.87
To add a custom banner which is shown to users when connecting to ssoca, use with-env-banner.yml (learn more).
Variables
ssoca_env_banner- a brief, custom banner message
Example
bosh deploy deployment.yml \
--ops-file with-env-banner.yml \
--var ssoca_env_banner='Unauthorized use is strictly prohibited.'
To add arbitrary, custom metadata about the environment, use with-env-metadata.yml. This can be used to customize the default ssoca frontend (learn more).
Variables
ssoca_env_metadata- a hash of metadata
Example
bosh deploy deployment.yml \
--ops-file with-env-metadata.yml \
--var ssoca_env_metadata={ui.usage:"ssoca -e acme-prod-gcp openvpn exec --sudo"}
To automatically provision an SSL certificate from Let's Encrypt and have ssoca run on standard HTTP/HTTPS ports, use with-letsencrypt-ssl.yml (learn more).
Variables
admin_email- an email which will be used to register for certificates
Example
bosh deploy deployment.yml ... \
--ops-file with-letsencrypt-ssl.yml \
--var admin_email=john.doe@example.com
To forward logs to Papertrail, use with-logging/to-papertrail.yml.
Variables
logging_papertrail_address- the Papertrail-provided hostname for your systemlogging_papertrail_port- the Papertrail-provided port for your system
Example
bosh deploy deployment.yml ... \
--ops-file with-logging/to-papertrail.yml \
--var logging_papertrail_address=logs0.papertrailapp.com \
--var logging_papertrail_port=65536 \
The ssoca server must be configured with an authentication provider.
The with-google-authn directory provides options around authenticating users via Google accounts (learn more). To enable this authentication, use enabled.yml.
Variables
ssoca_authn_google_client_id- the client ID of a registered applicationssoca_authn_google_client_secret- the client secret of a registered application
Example
bosh deploy deployment.yml ... \
--ops-file with-google-authn/enabled.yml \
--var ssoca_authn_google_client_id=1234567890-a1b2c3....apps.googleusercontent.com \
--var ssoca_authn_google_client_secret=a1b2c3d4...
If you wish to restrict access based on users having access to specific Cloud projects or roles in those projects, use cloud-project-scopes.yml.
Variables
ssoca_authn_google_cloud_project- the configuration to load project and role information
Example
bosh deploy deployment.yml ... --ops-file with-google-authn/enabled.yml \
--ops-file with-google-authn/cloud-project-scopes.yml \
--var ssoca_authn_google_cloud_project={projects:[prod1],roles:[role/editor]}
The with-uaa-authn directory provides options around authenticating users via Cloud Foundry UAA (learn more). To enable this authentication, use enabled.yml.
Variables
ssoca_authn_uaa_url- the URL where clients will communicate with the UAA serverssoca_authn_uaa_client_id- the client ID which will be used while authenticating usersssoca_authn_uaa_public_key- the public key used to verify a user's JWT as trusted
Example
bosh deploy deployment.yml ... \
--ops-file with-uaa-authn/enabled.yml \
--var ssoca_authn_uaa_url=https://uaa.prod1-gcp.acme-internal.com \
--var ssoca_authn_uaa_client_id=ssoca \
--var-file ssoca_authn_uaa_public_key=uaa-rsa.pub
If UAA supports both password-based and single sign on, users will additionally be prompted for a one-time while logging in. If your users are one or the other, you may explicitly configure which prompts are required to improve UX by using custom-prompts.yml.
Variables
ssoca_authn_uaa_prompts- a list of prompts to limit what users enter during authentication
Example
bosh deploy deployment.yml ... --ops-file with-uaa-authn/enabled.yml ... \
--ops-file with-uaa-authn/custom-prompts.yml \
--var ssoca_authn_uaa_prompts=[username,password]
The ssoca server must be configured with services that it will be signing certificates for.
The with-openvpn directory provides options for using ssoca to authenticate to OpenVPN servers which use certificate-based authentication (learn more). To get started by running a VPN server alongside ssoca, use colocated.yml.
Variables
ssoca_openvpn_authz- the authorization rules required for users accessing OpenVPNopenvpn_vpn_network- the base address for the network managed by the VPN serveropenvpn_vpn_network_mask- the IP mask for the network managed by the VPN server
Example
bosh deploy deployment.yml ... \
--ops-file with-openvpn/colocated.yml \
--var ssoca_openvpn_authz=[{authenticated:~}] \
--var openvpn_vpn_network=172.123.45.0 \
--var openvpn_vpn_network_mask=255.255.255.0 \
--var openvpn_vpn_network_mask_bits=24
This deployment includes a default Diffie-Hellman key for the OpenVPN server, but use custom-dh-pem.yml for a local key.
Variables
openvpn_dh_pem- pre-generated, PEM-formatted Diffie-Hellman key (e.g.openssl dhparam -out dhparams.pem 2048)
Example
bosh deploy deployment.yml ... --os-file with-openvpn/colocated.yml \
--ops-file with-openvpn/custom-dh-pem.yml \
--var-file openvpn_dh_pem=dhparams.pem
Typically a purpose of the VPN server is to allow clients to connect to resources on the private network. To allow the VPN server to masquerade traffic on behalf of clients, configure and use private-network-masquerade.yml.
Variables
openvpn_private_network- the base address for the private network to expose to clientsopenvpn_private_network_mask- the IP mask for the private network to expose to clientsopenvpn_private_network_mask_bits- the IP mask bits for the private network to expose to clients
Example
bosh deploy deployment.yml ... --ops-file with-openvpn/colocated.yml \
--ops-file with-openvpn/private-network-masquerade.yml \
--var openvpn_private_network=10.123.0.0 \
--var openvpn_private_network_mask=255.255.0.0 \
--var openvpn_private_network_mask_bits=16
The with-ssh directory provides options for using ssoca to authenticate to SSH servers which use certificate-based authentication (learn more). To get started by allowing SSH login alongside ssoca, use colocated.yml.
Variables
ssoca_ssh_authz- the authorization rules required for users accessing SSHssh_username- the account name to provision for SSH logins
Example
bosh deploy deployment.yml ... \
--ops-file with-ssh/colocated.yml \
--var ssoca_ssh_authz=[{authenticated:~}] \
--var ssh_username=ssh
If you would like to provision an additional user for SSH login, use additional-user.yml.
Variables
ssh_additional_username- the additional account name to provision for SSH logins
Example
bosh deploy deployment.yml ... --ops-file with-ssh/colocated.yml \
--ops-file with-ssh/additional-user.yml \
--var ssh_additional_username=dberger
bosh deploy deployment.yml ... --ops-file with-ssh/colocated.yml \
--ops-file <( bosh int with-ssh/additional-user.yml --var ssh_additional_username=john ) \
--ops-file <( bosh int with-ssh/additional-user.yml --var ssh_additional_username=jane ) \
Some caveats about this deployment that you should be aware of.
- This deployment currently colocates all services on a single VM. This makes it easy to get started, but is not recommended for production security.
- This repository is not versioned and tagged. If you are relying on this, you should track commits and changes on your own.
- This is a first iteration of a shared deployment for this and the interfaces may change. Consider it alpha quality.
- This assumes the default
cloud-confignaming conventions which are used bybosh-deployment.