Skip to content

Installation and Set Up

Prerequisites

Opus

Firstly, you’ll need to deploy Opus and configure your active directory in Opus. (Please refer to the Opus Installation guide).

Opus comes with a copy of HashiCorp Vault running on port 8200, this will need to be configured prior to setting up PEM, see Opus HashiCorp Vault Cofiguration.

PEM Server Deployment

The PEM Server can be set up by simply deploying the PEM Server OVA. Once the installation is complete run sudo netconf to set up a static IP address and configure DNS settings for the PEM Server.

Download the PEM Server OVA

Domain Controllor and End User Machines

On the Domain Controller, we need DNS to resolve the future hostname of the PEM Server. Add a Forward Look Up Zone by opening DNS Manager and navigate to your domain folder (not msdcs). Right click in the list and select New Host (A or AAAA).

Forward Lookup Zone

Hint

Your Windows Domain Controller needs to have LDAPS enabled, see here for more detail on enabling LDAPS.

PEM can be set up on the following domain controllers:

  • Windows Server 2012 R2
  • Windows Server 2016

Currently, the PEM Client is supported on:

  • Windows 10

Upload PEM Opus Tasks

The tasks can then be compiled and uploaded to Opus by browsing to the Opus tasks dashboard and selecting Upload Task, then simply drag and drop the tasks.

Download the PEM Opus Tasks

Upload Task 1

Upload Task 2

Alternatively, this can be done using the Opus command line tool like so:

$ opus --insecure ./opus/tasks https://admin:password@opus.pem.internal

OpenSSL and unix2dos

Some OpenSSL tools are used in generating TLS certificates, the binaries can be downloaded here. unix2dos is used to convert the line endings and can be downloaded here.

If you're using MacOS simply run:

brew install openssl
brew install unix2dos

Or on Ubuntu:

sudo apt-get install openssl
sudo apt-get install dos2unix

Hint

Many of the secrets you'll put in the HashiCorp vault need to be base64 encoded. OpenSSL can base64 encode files by running openssl base64 -in <infile> -out <outfile>.

PEM Setup Wizard

To begin with the setup, browse to your Opus address and locate the PEM Setup Wizard task. There’s a search bar located in the top right hand corner of the tasks dashboard to help you find the task. Click Start.

Setup Task

Throughout the task, you’ll need to add secrets to the HashiCorp vault, so ensure your vault is unsealed before continuing with the task.

At each step, the task will validate the setup has progressed correctly, because of this the task can be used to test the configuration post setup. Additionally, the task can be cancelled at any point, saving your progress, so the setup can be returned to from the same point. Upon returning to the task, all previous stages will be revalidated. This task can also be used to make changes to the configuration after the initial setup.

Setting Up SSH Details

In order to connect to the server over SSH, we need a private key to be stored in the vault which will be used when connecting to the PEM server. You’ll need to add a secret with the path pem_server_ssh and the following keys:

  • hostname This is the hostname of the server, without any protocol, for example: pem.domain.com
  • private_key The base64 encoded private key to be used by this task to connect to the PEM Server. This will be the only private key authorised to connect to the PEM server. A private key will be provided in the Setup Wizard. Decode and save this key so that the PEM Server for direct SSH access to the PEM Server.

Once the keys have been added to the vault with the correct path, click Confirm.

At this point the task will connect to the server in order to remotely configure it, you’ll be given the option to change the hostname or IP at this stage.

Joining the PEM Server to the Domain

For users to authenticate against the PEM Server, it must be part of the domain. For this we need to configure the kerberos client and keytab file.

You’ll need to add a secret with the path pem_server_kerberos to the vault and the following keys:

  • domain_controller_address The fully qualified domain name of the domain controller without protocol, for example: dc.pem.internal
  • domain_controller_hostname The hostname of the domain controller without protocol.
  • krb5.conf The base64 encoded krb5.conf file. Modify our basic Kerberos template file.
  • smb.conf The base64 encoded smb.conf file. Modify our basic Samba template file.
  • pem.keytab The base64 encoded contents of the kerberos keytab file, this is generated on the domain controller for this server.

On the domain controller, a keytab file can be generated using the command line with a command like:

ktpass -out c:\pem.keytab -princ HTTP/pemserver.example.com@EXAMPLE.COM -mapUser admin@example.com -pass password -mapOp set -crypto all -pType KRB5_NT_PRINCIPAL

Warning

This command will change the password of the mapped user!

Once the keys have been added to the vault with the correct path, click Confirm.

Setup Active Directory Connection

To retrieve user and group details from the Active Directory, we need details of an LDAPS bind account to be available.

You’ll need to add a secret with the path pem_ad_bind and the following keys:

  • address The hostname or IP address of the domain controller to connect to.
  • port The listening LDAPS port (usually 636).
  • username The bind account username.
  • password The bind account password.
  • domain The domain FQDN.

Once the keys have been added to the vault with the correct path, click Confirm.

Setup PEM Server Authorisation

At this stage you'll need to identify a sysadmin group or groups who will be able to read data from the API, this is required for all users who intend to run PEM tasks in Opus. Following this, we’ll need to identify a main user group or groups authorised to use PEM, otherwise they will not be able to submit requests to the API, this is required for all PEM end users.

Setup TLS Certificates

In order to enable TLS we need to store the Domain Certificate Authority certificate in the vault which will be used when connecting to the PEM Server.

You’ll need to add a secret with the path pem_server_tls and the following keys:

  • domain_ca_cert The base64 encoded public key of the certificate authority, which will be on your Domain Controller.

    • Open Microsoft Management Console -> File -> Certificates -> Select Computer Account -> Select Local Computer.

      Snap Ins

    • Navigate to Console Root -> Certificates (Local Computer) -> Personal -> Certificates.

      Certificates

    • Right click the *-CA certificate and select All Tasks -> Export
    • Select No to the private key and finally select Base-64 x509 encoding.

      Certificate Export

    • Base 64 encode the certificate.
  • pemserver_key The base64 encoded private key for the PEM Server to use for TLS Encryption.

  • pemserver_crt The base64 encoded signed certificate for the PEM Server to use for TLS Encryption.

    • The following steps detail how to generate pemserver_key and pemserver_crt
    • Copy pemserver.cnf and edit the DNS.1 entry to be your PEM Server address.
    • At this stage we'll generate a key file using OpenSSL and a Certificate Signing Request with pemserver.cnf as the config file.

    openssl genrsa -out pemserver.key 2048

    openssl req -new -key pemserver.key -out pemserver.csr -config pemserver.cnf

    • Convert line-ending on .csr to Windows

    unix2dos pemserver.csr

    • Copy the converted CSR file to your domain controller. On the DC in the commmand prompt run:

    certreq -attrib “CertificateTemplate:WebServer"

    • Select the CSR file in the file browser and copy back the resultant .cer file from the DC. Convert to an OpenSSL .crt file:

    openssl x509 -inform PEM -in pemserver.cer -out pemserver.crt

Once the keys have been added to the vault with the correct path, click Confirm.

Configure GPO Management

In order to create and modify policies for users, we need to connect to the Domain Controller over WinRM.

You’ll need to add a secret with the path pem_ad_creds and the following keys:

  • username A username for the domain controller that is able to modify GPOs.
  • password The corresponding password for the domain controller.
  • address The hostname or IP address of the domain controller to connect to.
  • domain The domain Distinguished Name (such as ‘dc=example, dc=com).

Once the keys have been added to the vault with the correct path, click Confirm.

Configure Opus Requests

Opus will receive requests made by users via the PEM Server. For this, it needs to know the Opus URL as well as the account in which Opus tasks will be created.

You’ll need to add a secret with the path pem_server_opus with the following keys:

  • opus_url The URL, including protocol which will be used for the PEM Server to communicate with Opus.

Once the keys have been added to the vault with the correct path, click Confirm.

You’ll then be asked to enter a username for the Opus account which will record requests, enter a valid username and click Submit.

Enter the corresponding account password and click Submit.

You’ve now completed the PEM Setup Wizard!

Kerberos Configuration Template

# Documentation on parameters available here:
#  https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html

[libdefaults]
    default_realm = domain.suffix
    ignore_acceptor_hostname = true
    forwardable = true
    proxiable = true
    dns_lookup_realm = false
    dns_lookup_kdc = true
    canonicalize = true
    fcc-mit-ticketflags = true

[appdefaults]
    pam = {
        debug = false
        ticket_lifetime = 36000
        renew_lifetime = 36000
        forwardable = true
        krb4_convert = false
    }

[logging]
    default = FILE:/var/log/krb5libs.log
    kdc = FILE:/var/log/krb5kdc.log
    admin_server = FILE:/var/log/kadmind.log

[realms]
    domain.suffix = {
        kdc = dc-hostname.domain.suffix
        admin_server = dc-hostname.domain.suffix
        default_domain = domain.suffix
    }

[domain_realm]
    .domain.suffix = domain.suffix

Samba Configuration Template

# Documentation on parameters available here:
#  https://www.samba.org/samba/docs/current/man-html/smb.conf.5.html
[global]
  # Modify these parameters
  workgroup = workgroup
  NetBIOS name = pemserver
  server string = pemserver
  realm = domain.suffix

  # Modify these if required
  security = ADS
  winbind enum users = Yes
  winbind enum groups = Yes
  winbind use default domain = Yes
  template shell = /bin/bash
  client min protocol = SMB2
  client ipc min protocol = SMB2
  lm announce = no
  local master = no
  log file = /var/log/samba/log.%m
  max log size = 1000
  logging = file
  panic action = /usr/share/samba/panic-action %d
  server role = standalone server
  obey pam restrictions = yes
  unix password sync = yes
  passwd program = /usr/bin/passwd %u
  passwd chat = *Enter\snew\s*\spassword:* %n\n *Retype\snew\s*\spassword:* %n\n *password\supdated\ssuccessfully* .
  pam password change = yes
  map to guest = bad user
  usershare allow guests = yes

TLS Configuration Template

[req]
default_bits       = 2048
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
countryName = GB
organizationName = PEM

[v3_req]
subjectAltName = @alt_names
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth

[alt_names]
DNS.1   = server.pem.internal