Podman

Prerequisites

• Podman and podman-compose: Must be installed on the host machine.
• Hostname: For a production-ready installation, you need a machine with an IP or hostname that can be used to contact Authentication Service.
• Firewall requirements: Ensure that the port on which AuthenticationService is hosted is open. Ex: 9443
• TLS certificate and associated keys: For securing HTTPS traffic.
• Realm Public Key: For validating access token issued by SAE.

Deployment

1: Access the AuthenticationService Package

Download the AuthenticationService package to your Linux machine. It is provided as a separate zip file and contains the container image, compose.yaml, and configuration files.

Extract the AuthenticationService.zip package:

unzip AuthenticationService.zip

2: Extract the Package

After extracting the ZIP package, navigate to the AuthenticationService folder, and run the following command to unzip the AuthenticationService.tar.gz file:

gunzip <FileName>.tar.gz

3: Load the Container Image

Load the image using your container runtime:

podman load -i <FileName>.tar

Verify the image was loaded successfully:

podman images

Note the Image ID of the loaded AuthenticationService image — you will need it in Step 6.

4: Place the Required Files

In the AuthenticationService folder inside the installation package:

1. Navigate to the certs/ directory and place your valid certificate and key:

• Replace certs/cert.pem with the certificate you use for securing the HTTPS traffic for AuthenticationService.
• Replace certs/privateKey.pem with the corresponding key of the certificate you are using.

2. Navigate to the jwtPublic/ directory and replace publicKey.pem with your realm public key file.

"Path": "/thales/authenticationservice/API/certs/cert.pem",
"KeyPath": "/thales/authenticationservice/API/certs/privateKey.pem"

To obtain the Realm Public Key:

a. Open the SAE console, navigate to your realm, and go to Realm Settings > Keys.

b. Select the RS256 active key and click the Public Key button.

c. Copy the public key obtained and save it as a .pem file with the standard -----BEGIN PUBLIC KEY----- / -----END PUBLIC KEY----- headers.

5: Set File Permissions

Ensure the configuration files and directories are readable by the AuthenticationService container. Run the following commands from the AuthenticationService folder:

chmod 755 certs
chmod 755 config
chmod 755 jwtPublic

chmod 644 certs/cert.pem
chmod 644 certs/privateKey.pem
chmod 644 config/appsettings.json
chmod 644 jwtPublic/publicKey.pem

6: Configure the Compose File

Open the compose.yaml and make the following changes:

6.1 Update the Compose Version

Replace the placeholder <version> with your installed compose tool version. To check:

podman-compose --version

6.2 Update the Host Port

Update only the host port under the ports section to the port on which we want to host AuthenticationService. Ensure this port is open in your firewall. <host-port>:9443

6.3 Update the Image Reference

Replace the image ID in the compose.yaml with the actual image ID of the SafeNet Access Exchange image that you just loaded. It can be found by using the following command:

podman images

7: Configure appsettings.json

Update appsettings.json, located in the config/ folder of the AuthenticationService directory, with values specific to your environment. Update only the certificate and private key file names — do not modify the directory path.

HTTPS

Configure the certificate path and key path in appsettings.json as follows:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://*:9000"
      },
      "Https": {
        "Url": "https://*:9443",
        "Certificate": {
          "Path": "/thales/authenticationservice/API/certs/<certificate.pem>",
          "KeyPath": "/thales/authenticationservice/API/certs/<privateKey.pem>"
        }
      }
    }
  }
}

Replace only:

• <certificate.pem>
• <privateKey.pem>

Keep the remainder of the path unchanged.

JWT Authentication

{
  "JwtAuthentication": {
    "Issuer": "<SAE-realm-issuer-URL>"
  }
}

To find the Issuer URL:

1. Open the SAE console, navigate to your realm, and go to Realm Settings > General.

2. Go to Endpoints and click on the OpenID Endpoint Configuration link.

3. The line marked in red provides the issuer URL information.

4. Copy the issuer URL and add it in the configuration.

FIDO Server Connection

{
  "FidoServerConnection": {
    "BaseUrl": "http://<Internal-Ip>:9080"
  }
}

SAS Core API Connection

{
  "SasCoreApiBaseUrl": "<sas-core-api-base-url>",
  "SasCoreApiConnection": {
    "AccessToken": "<access-token>"
  }
}

To retrieve the Access Token:

1. In SAS PCE, go to System > Setup > Agent Communication with JWT Token.

2. Under Generate the JSON Web Token (JWT), select Generate.

3. Copy the entire generated JWT, paste it in a text editor, and update it in the accessToken key.

8: Start the Container

From the directory containing the compose.yaml, bring up the container in detached mode:

podman-compose up -d

9: Verify the Deployment

Check that the container is running with a status of Up:

podman ps -a

To inspect the container logs:

podman logs <containerID>

Replace <containerID> with the container ID shown in the output of the status command above.

Configure Vault (Optional)

This section applies only if you are using Vault to securely store the SAS Core API access token.

1: Install Vault

RHEL/CentOS/Fedora:

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo yum -y install vault

Ubuntu/Debian:

wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install vault

2: Start Vault

Choose one of the following options, depending on how you want to run Vault.

Option A: Development Mode (Testing Only)

Dev mode runs Vault in memory and does not require any configuration — use it for quick testing:

vault server -dev -dev-listen-address="0.0.0.0:8200"

The terminal prints output similar to:

Root Token: hvs.XXXXXXXXXXXXXXXXXXXXXXXX

Option B: Persistent Mode (Recommended)

Unlike Dev Mode, this option saves Vault's data to disk so it survives a restart. These steps assume no prior Vault experience.

1. Edit the /etc/vault.d/vault.hcl configuration file. If you installed Vault using the package manager commands in Step 1, this file already exists with a default configuration — replace its contents with the following, and create the /opt/vault/data folder if it doesn't already exist:

storage "file" {
  path = "/opt/vault/data"
}

#HTTP listener
listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

api_addr = "http://127.0.0.1:8200"

• The storage block tells Vault to save its (encrypted) data to disk at /opt/vault/data, so it survives a restart instead of only living in memory like Dev Mode.
• The listener block tells Vault which network port to accept connections on. tls_disable = true keeps this plain HTTP, matching Dev Mode, since Vault and AuthenticationService run on the same trusted host.

2. Start the Vault server using this configuration file:

vault server -config=/etc/vault.d/vault.hcl

This starts Vault as a real (non-dev) server that keeps running and persists its data.

3. In a second terminal, initialize Vault. This is a one-time step, only required the first time you start a fresh Vault server. First, set the Vault address, then initialize:

export VAULT_ADDR='http://127.0.0.1:8200'
vault operator init

Vault prints 5 "unseal keys" and one initial root token.

4. Unseal Vault. Vault starts in a "sealed" state (encrypted and unusable) every time it starts, and needs any 3 of the 5 unseal keys from the previous step before it will serve requests. Run the following command 3 times, each time with a different unseal key:

vault operator unseal <unseal-key>

5. Point the vault CLI at your running server and log in using the initial root token from step 3:

export VAULT_ADDR='http://127.0.0.1:8200'
vault login <initial-root-token>

6. Enable the key-value secrets engine at the secret/ path used later in this guide. Dev Mode turns this on automatically, but a persistent server does not, so this is a one-time manual step:

vault secrets enable -path=secret kv-v2

3: Create the Secret

export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN='hvs.XXXXXXXX'   # root token from Step 2 (Option A) or the initial root token from Step 2 (Option B)

# Store the access token
vault kv put secret/authenticationservice \
  sasCoreApiAccessToken=<actual-access-token>

# Verify
vault kv get secret/authenticationservice

4: Create the Vault Token File

Create a vault-token file containing the root token generated in Step 2, and place it under the vault/ directory within the AuthenticationService folder. Run the following command from the vault directory located inside the AuthenticationService directory:

echo -n '<root-token-from-step-2>' > ./vault/vault-token

5: Set File Permissions

Set the correct permissions for the Vault token file:

chmod 755 ./vault/vault-token

6: Uncomment the Vault Token Volume Mount

In compose.yaml, uncomment the vault-token volume mount and update the host-side path to point to your vault-token file.

7: Configure vaultappsettings.json

Update vaultappsettings.json, located in the config/ folder of the AuthenticationService directory, with the following configuration:

{
  "vaultUrl": "<vault-url>",
  "vaultAuthMethod": "<vault-auth-method>",
  "vaultTokenFile": "/thales/authenticationservice/vault-token",
  "vaultRole": "<vault-role>",
  "SasCoreApiConnection:AccessToken": "secret/data/authenticationservice/sasCoreApiAccessToken"
}