Prerequisites

ProAuth is distributed as OCI compliant container images and can be deployed on any Kubernetes cluster. For Kubernetes deployments, Helm charts are provided to simplify the installation process.

Resource Access

Please make sure that you are able to access all ProAuth artifacts. Together with your license, you will be provided with the necessary login credentials.

Container / Helm Resources

Container artifacts as well as helm charts are hosted on the following registry: 4tectureregistry.azurecr.io

In order to run the helm chart deployment, please make sure that the machine performing the deployment is authenticated to the registry. This can be done by running the following command:
shell
```
docker login 4tectureregistry.azurecr.io
```
In order to download the images in Kubernetes, please make sure that there is a corresponding secret in the namespace where the images are pulled. This can be done by running the following command:
shell
```
kubectl create secret docker-registry 4tectureregistry.azurecr.io --docker-server=4tectureregistry.azurecr.io --docker-username=<username> --docker-password=<password> -n <namespace>
```

NuGet Feed for CLI and .NET SDK

NuGet packages as well as the CLI are hosted on the following NuGet feed: https://packages.proauth.net/v3/index.json

To authenticate the nuget feed, you have the following options:

Add the private feed to your nuget config and install the tool

shell

dotnet nuget add source https://packages.proauth.net/v3/index.json \
--name ProAuthFeed \
--username your-username \
--password your-password \
--store-password-in-clear-text

Install the tool

shell

dotnet tool update ProAuth.Cli --version <ProAuth Version> --global

Create a custom nuget.config file with the following content:

xml

<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
    <add key="ProAuthFeed" value="https://nuget.yourcompany.com/v3/index.json" />
</packageSources>
<packageSourceCredentials>
    <ProAuthFeed>
    <add key="Username" value="your-username" />
    <add key="ClearTextPassword" value="your-password" />
    </ProAuthFeed>
</packageSourceCredentials>
</configuration>

Install the tool

shell

dotnet tool update ProAuth.Cli --configfile "$path/nuget.config" --version <ProAuth Version> --global

Run the installation within a short script with credentials temporarily stored in environment variables

bash scriptPowerShell script

bash

#!/bin/bash

# Prompt for username and password
read -p "Enter NuGet Username: " NUGET_USER
read -s -p "Enter NuGet Password: " NUGET_PASS
echo # Print a new line

# Run the dotnet tool install command using environment variables without exposing credentials in history
dotnet tool install ProAuth.Cli \
    --add-source "https://$NUGET_USER:$NUGET_PASS@nuget.yourcompany.com/v3/index.json" \
    --version <cli-version> --global --ignore-failed-sources

# Unset the environment variables after use (optional)
unset NUGET_USER
unset NUGET_PASS

powershell

# Prompt for username and password securely
$credentials = Get-Credential

# Extract username and password from the credentials object
$NUGET_USER = $credentials.UserName
$NUGET_PASS = $credentials.GetNetworkCredential().Password

# Install the tool using the provided credentials
dotnet tool install ProAuth.Cli `
    --add-source "https://$NUGET_USER:$NUGET_PASS@nuget.yourcompany.com/v3/index.json" `
    --version <cli-version> --global --ignore-failed-sources

# Clear the credentials (optional)
$NUGET_USER = $null
$NUGET_PASS = $null

Domains and TLS

ProAuth requires a domain to be accessible via HTTPS. Please make sure that you have a domain available and that you have a valid TLS certificate for this domain. For Kubernetes deployments ProAuth is registering a ingress resource for ProAuth and the Admin UI. The TLS setup is completely configurable and using Let's Encrypt certificates together with cert-manager is fully supported.

Required Domains

ProAuth Domain
- This domain is used for all authentication and token issuing endpoints.
- Examples: auth.yourcompany.com or idp.yourcompany.com
ProAuth Admin UI Domain
- This domain is used for the ProAuth Admin UI.
- The admin UI is not required, your ProAuth environment can be run without admin UI just from CLI or API.
- Examples: auth-admin.yourcompany.com or idp-admin.yourcompany.com

Certificates

In addition to the TLS certificates which are usually deployed to the reverse proxy, ProAuth requires to certificates which need to be provided during the installation process / helm chart deployment. ProAuth has a certificate management API to manage the certificates for multiple purposes and renewal workflows. However, the following set of initial certificates are required to start ProAuth and perform the provisioning of the configuration.

ProAuth Default Certificate
- X509 Certificate
- Used for Token Signing if no other certificate is provided or matches the purpose.
ProAuth Data Protection Key Encryption Certificate
- X509 Certificate
- Used for encrypting the data protection keys in the database.

Do not lose the data protection key encryption certificate!

The data protection key encryption certificate is used to encrypt the data protection keys in the database. If you lose this certificate, you will not be able to decrypt the data protection keys and your data will be lost. Data protection is used to encrypt sensitive data in the database. Without the data protection key encryption certificate, you will not be able to decrypt the data and your data will be lost.

The default certificate can be exchanged any time. The worst case that could happen is that you need to re-authenticate all users since the currently valid and issued tokens cannot be validated anymore.

INFO

The x509 certificate used to encrypt the data protection keys is not checked for expiration. However, there is a renewal process implemented in ProAuth. If you renew the data protection key encryption certificate, you need to provide the new one as certificate and move the old one to the keyrotationdecryptioncertificates section. For rotating the data protection key encryption certificates, the new and old one need to be configured in order to perform the key rotation.

For testing purposes or to get an idea on how to create self-signed certificates, the following script can be used and adjusted to your needs:

bash

#!/bin/bash

# Define common variables for all certificates
DAYS_VALID=7300
COUNTRY="CH"
STATE="ZH"
LOCALITY="Volketswil"
ORGANIZATION="4tecture GmbH"
ORG_UNIT="QA"

# Prompt the user for the PKCS#12 password
read -s -p "Enter the PKCS#12 password: " P12_PASSWORD
echo

# Define an array of certificates with their unique CERT_NAME, COMMON_NAME, and ALGORITHM
# Supported algorithms: "rsa", "ec"
certificates=(
  "data_protection_cert:proauthdataencryption:rsa"
  "default_cert:proauthdefaultcert:rsa"
)

# Function to generate a certificate
generate_certificate() {
  local CERT_NAME=$1
  local COMMON_NAME=$2
  local ALGORITHM=$3
  local KEY_FILE="$CERT_NAME.key"
  local CERT_FILE="$CERT_NAME.crt"
  local P12_FILE="$CERT_NAME.p12"
  local BASE64_FILE="$CERT_NAME.base64"
  
  if [ "$ALGORITHM" == "rsa" ]; then
    # Generate an RSA private key with 4096 bits
    openssl genpkey -algorithm RSA -out $KEY_FILE -pkeyopt rsa_keygen_bits:4096
    if [ $? -ne 0 ]; then
        echo "Error generating RSA private key for $CERT_NAME"
        return 1
    fi
  elif [ "$ALGORITHM" == "ec" ]; then
    # Generate an elliptic curve private key using the P-384 curve
    openssl ecparam -genkey -name secp384r1 -out $KEY_FILE
    if [ $? -ne 0 ]; then
        echo "Error generating EC private key for $CERT_NAME"
        return 1
    fi
  else
    echo "Unsupported algorithm: $ALGORITHM for $CERT_NAME"
    return 1
  fi

  # Generate a self-signed certificate
  local SUBJ="/C=$COUNTRY/ST=$STATE/L=$LOCALITY/O=$ORGANIZATION/OU=$ORG_UNIT/CN=$COMMON_NAME"
  openssl req -new -x509 -key $KEY_FILE -out $CERT_FILE -days $DAYS_VALID -subj "$SUBJ"
  if [ $? -ne 0 ]; then
      echo "Error generating self-signed certificate for $CERT_NAME"
      return 1
  fi

  # Export the private key and certificate to a PKCS#12 file
  openssl pkcs12 -export -out $P12_FILE -inkey $KEY_FILE -in $CERT_FILE -password pass:"$P12_PASSWORD"
  if [ $? -ne 0 ]; then
      echo "Error exporting to PKCS#12 file for $CERT_NAME"
      return 1
  fi

  # Encode the PKCS#12 file to base64 and remove newlines
  BASE64_CONTENT=$(base64 $P12_FILE | tr -d '\n')
  if [ $? -ne 0 ]; then
      echo "Error encoding PKCS#12 file to base64 for $CERT_NAME"
      return 1
  fi

  # Save the base64 content to a file
  echo $BASE64_CONTENT > $BASE64_FILE

  # Display the generated files
  echo "Generated files for $CERT_NAME:"
  echo "Private Key: $KEY_FILE"
  echo "Certificate: $CERT_FILE"
  echo "PKCS#12 File: $P12_FILE"
  echo "Base64 Encoded PKCS#12 File: $BASE64_FILE"

  # Display the base64 encoded string (you can copy this directly into your config file)
  echo "Base64 Encoded PKCS#12 Content (Single Line) for $CERT_NAME:"
  echo $BASE64_CONTENT

  return 0
}

# Loop through the certificates array and generate each certificate
for cert in "${certificates[@]}"; do
  IFS=":" read -r CERT_NAME COMMON_NAME ALGORITHM <<< "$cert"
  generate_certificate $CERT_NAME $COMMON_NAME $ALGORITHM
done

Prerequisites ​

Resource Access ​

Container / Helm Resources ​

NuGet Feed for CLI and .NET SDK ​

Domains and TLS ​

Certificates ​

Prerequisites

Resource Access

Container / Helm Resources

NuGet Feed for CLI and .NET SDK

Domains and TLS

Certificates