Axidian CertiFlow Agent

With Axidian CertiFlow Client Agent you can manage cards on user workstations remotely.

After configuring the Axidian CertiFlow server components, install the agents on user workstations alongside the Axidian CertiFlow Middleware component.

The agent performs the following operations:

• Add and assign cards
• Issue empty or pre-assigned cards
• Continue issue and update operations for cards in a Pending state.
• Request a user PIN change after a specified time period
• Block and reset user PIN
• Update card contents
• Clear and initialize cards within revocation
• Change administrator PIN
• Control card usage and block user sessions and cards
• Detect cards with blocked user or administrator PINs, incorrect PIN entry attempts, and connections of unregistered cards

Configure agent environment

Follow the instructions for the operating system of the workstation where the Axidian CertiFlow server is installed.

Windows

1. Create certificates for agent services.
2. Configure a secure connection to the agent services website.
3. Configure Axidian CertiFlow to work with agents.
4. Install and configure agents on user workstations.

Create agent certificates

The agent requires the following certificates:

• CertiFlow Agent CA – the root certificate for the agent services. CertiFlow Agent CA certificate is used to issue certificates to user workstations with agents.
• CertiFlow Agent SSL – an authentication certificate signed by the root certificate. CertiFlow Agent SSL certificate is required to establish a secure TLS connection between the server and a workstation with an agent. The certificate is issued for the workstation hosting the Axidian CertiFlow server.
• Workstation certificate – a certificate that is issued automatically when an agent is registered. When connecting to the Axidian CertiFlow server, the client workstation uses this certificate to authenticate. Once the server verifies the connection, the workstation is added to the trusted list and can receive tasks from the server.

Use the CertiFlow.Agent.Cert.Generator tool to create the agent certificates.

CertiFlow.Agent.Cert.Generator tool parameters

Parameters for generating root and SSL certificates

Parameter	Description
/root	Generates the root certificate for agent services.
/rootKeySize	(Optional) Specifies the private key size (in bits) for the root certificate. Default: 4096. Valid range: 512 to 8192.
/sn <server_DNS_name>	Generates the SSL certificate for the specified server DNS name.
/csn	Generates the SSL certificate for the server where the tool is running.
/sslKeySize	(Optional) Specifies the private key size (in bits) for the SSL certificate. Default: 2048. Valid range: 512 to 4096.
/pwd	(Optional) Specifies the password for the SSL certificate.
/installToStore	(Optional) Publishes the certificates generated by the tool to the server's certificate stores: - The CertiFlow Agent CA certificate to the Trusted Root Certification Authorities store. - The CertiFlow Agent SSL certificate to the Personal certificate store of the workstation hosting the Axidian CertiFlow server.

Parameters for generating only an SSL Certificate using an existing CertiFlow Agent CA root certificate

Parameter	Description
/rootKey	The file path to the existing root certificate.
/ssl	Generates the SSL certificate for agent services.
/sn <server_DNS_name>	Generates the SSL certificate for the specified server DNS name.
/csn	Generates the SSL certificate for the server where the tool is running.
/pwd	(Optional) Specifies the password for the SSL certificate.
/sslKeySize	(Optional) Specifies the private key size (in bits) for the SSL certificate. Default: 2048. Valid range: 512 to 4096.
/installToStore	(Optional) Publishes the SSL certificate generated by the tool to the Personal certificate store of the workstation hosting the Axidian CertiFlow server.

Follow these steps to create agent certificates:

1. Navigate to the AxidianCertiFlow.WindowsServer\Misc\AgentCertGenerator catalog on the Axidian CertiFlow server.
2. Launch the command prompt as administrator and run the CertiFlow.Agent.Cert.Generator tool with the required parameters.

   CertiFlow.Agent.Cert.Generator.exe /root /csn /installToStore

The tool creates the following files AxidianCertiFlow.WindowsServer\Misc\AgentCertGenerator catalog:

• agent_root_ca.json – the agent root certificate with its private key in JSON format
• agent_root_ca.cer – the agent root certificate
• agent_root_ca.key – the private key for the agent root certificate
• agent_ssl_cert.cer – the SSL certificate for the agent website
• agent_ssl_cert.key – the private key for the SSL certificate
• agent_ssl_cert.pfx – the agent SSL certificate with its private key in PFX format

info

Install the CertiFlow Agent CA certificate (agent_root_ca.cer) into the Trusted Root Certification Authorities store on the Axidian CertiFlow server.

Multi-server deployments

For deployments with multiple Axidian CertiFlow servers using agents, issue a unique SSL certificate for each server. Use a shared CertiFlow Agent CA root certificate for all servers in your environment.

Follow these steps to create an SSL certificate for an additional server or to renew an expired certificate.

1. Copy the Cm.Agent.Cert.Generator tool catalog and the agent root certificate with the private key (agent_root_ca.json) to the target server.
2. Run the following command.

   Cm.Agent.Cert.Generator.exe /rootKey <path_to_agent_root_ca.json> /ssl /sn <server_DNS_name> /installToStore
   Example

   Cm.Agent.Cert.Generator.exe /rootKey "C:\AgentCertGenerator\agent_root_ca.json" /ssl /sn server.domain.loc /installToStore

Configure a secure connection to the agent website

1. Open the Internet Information Services (IIS) Manager.
2. Select the Axidian CertiFlow Agent Site and go to Bindings....
3. Select the binding for port 3003.
   info

   Port 3003 is set by default. If you use another port, create and configure a new binding for this port. The port must be open to incoming connections in the firewall.

4. Click Edit....
5. In the SSL certificate field, select the CertiFlow Agent SSL certificate or another SSL/TLS certificate issued by a trusted Certificate Authority (CA) in your environment for the Axidian CertiFlow server's hostname, and click OK.

SSL certificate requirements

The SSL/TLS certificate can be an RSA certificate issued by any trusted Certificate Authority (CA) for the Axidian CertiFlow server.

• Subject must include the Common Name attribute (the Axidian CertiFlow server FQDN).
• Subject Alternative Name (SAN) must include a DNS Name attribute (the Axidian CertiFlow server FQDN).
  For example: server.domain.loc or a wildcard entry *.domain.loc.
• Enhanced Key Usage (EKU) must include the Server Authentication value.

Linux

1. Create certificates for agent services.
2. Configure a secure connection to the agent services website.
3. Configure Axidian CertiFlow to work with agents.
4. Install and configure agents on user workstations.

Create agent certificates

The agent requires the following certificates:

• CertiFlow Agent CA – the root certificate for the agent services. CertiFlow Agent CA certificate is used to issue certificates to user workstations with agents.
• CertiFlow Agent SSL – an authentication certificate signed by the root certificate. CertiFlow Agent SSL certificate is required to establish a secure TLS connection between the server and a workstation with an agent. The certificate is issued for the workstation hosting the Axidian CertiFlow server.
• Workstation certificate – a certificate that is issued automatically when an agent is registered. When connecting to the Axidian CertiFlow server, the client workstation uses this certificate to authenticate. Once the server verifies the connection, the workstation is added to the trusted list and can receive tasks from the server.

Use the CertiFlow.Agent.Cert.Generator tool to create the agent certificates.

CertiFlow.Agent.Cert.Generator tool parameters

Parameters for generating root and SSL certificates

Parameter	Description
/root	Generates the root certificate for agent services.
/rootKeySize	(Optional) Specifies the private key size (in bits) for the root certificate. Default: 4096. Valid range: 512 to 8192.
/sn <server_DNS_name>	Generates the SSL certificate for the specified server DNS name.
/csn	Generates the SSL certificate for the server where the tool is running.
/sslKeySize	(Optional) Specifies the private key size (in bits) for the SSL certificate. Default: 2048. Valid range: 512 to 4096.
/pwd	(Optional) Specifies the password for the SSL certificate.
/installToStore	(Optional) Publishes the certificates generated by the tool to the server's certificate stores: - The CertiFlow Agent CA certificate to the Trusted Root Certification Authorities store. - The CertiFlow Agent SSL certificate to the Personal certificate store of the workstation hosting the Axidian CertiFlow server.

Parameters for generating only an SSL Certificate using an existing CertiFlow Agent CA root certificate

Parameter	Description
/rootKey	The file path to the existing root certificate.
/ssl	Generates the SSL certificate for agent services.
/sn <server_DNS_name>	Generates the SSL certificate for the specified server DNS name.
/csn	Generates the SSL certificate for the server where the tool is running.
/pwd	(Optional) Specifies the password for the SSL certificate.
/sslKeySize	(Optional) Specifies the private key size (in bits) for the SSL certificate. Default: 2048. Valid range: 512 to 4096.
/installToStore	(Optional) Publishes the SSL certificate generated by the tool to the Personal certificate store of the workstation hosting the Axidian CertiFlow server.

Follow these steps to create agent certificates:

1. Open a terminal on the Axidian CertiFlow server, navigate to the AxidianCertiFlow.LinuxServer/Misc/AgentCertGenerator catalog, and grant execute permission to the Cm.Agent.Cert.Generator file:

   sudo chmod +x CertiFlow.Agent.Cert.Generator.dll
2. Run the tool with the /root /csn parameters.

   dotnet CertiFlow.Agent.Cert.Generator.dll /root /csn

The tool creates the following files AxidianCertiFlow.WindowsServer\Misc\AgentCertGenerator catalog:

• agent_root_ca.json – the agent root certificate with its private key in JSON format
• agent_root_ca.cer – the agent root certificate
• agent_root_ca.key – the private key for the agent root certificate
• agent_ssl_cert.cer – the SSL certificate for the agent website
• agent_ssl_cert.key – the private key for the SSL certificate
• agent_ssl_cert.pfx – the agent SSL certificate with its private key in PFX format

info

Install the CertiFlow Agent CA certificate (agent_root_ca.cer) into the Trusted Root Certification Authorities store on the Axidian CertiFlow server.

Multi-server deployments

For deployments with multiple Axidian CertiFlow servers using agents, issue a unique SSL certificate for each server. Use a shared CertiFlow Agent CA root certificate for all servers in your environment.

Follow these steps to create an SSL certificate for an additional server or to renew an expired certificate.

1. Copy the Cm.Agent.Cert.Generator tool catalog and the agent root certificate with the private key (agent_root_ca.json) to the target server.
2. Run the following command.

   dotnet CertiFlow.Agent.Cert.Generator.dll /rootKey <path_to_agent_root_ca.json> /ssl /sn <server_DNS_name> /installToStore
   Example

   dotnet CertiFlow.Agent.Cert.Generator.dll /rootKey ./agent_root_ca.json /ssl /sn domain.loc1

Configure a secure connection to the agent website

Follow the instructions for the operating system of the workstation where the Axidian CertiFlow server is installed.

RHEL-based

1. Copy the agent website SSL certificate and its private key to the /etc/ssl/ catalog on the Axidian CertiFlow server, and the agent root certificate – to the trusted root certificates store.

   sudo cp ./agent_ssl_cert.cer /etc/ssl/
   sudo cp ./agent_ssl_cert.key /etc/ssl/
   sudo cp ./agent_root_ca.cer /etc/pki/ca-trust/source/anchors/

2. Run the following command to update the trusted root certificates store.

   sudo update-ca-trust extract

3. Specify the paths to the certificate and the private key in the configuration file of your web server, in the section that defines the agent website.

Debian-based

1. Copy the agent website SSL certificate and its private key to the corresponding catalogs on the Axidian CertiFlow server, and the agent root certificate – to the trusted root certificates store.
   Convert the agent's root certificate format from CER to CRT.

   sudo cp ./agent_ssl_cert.cer /etc/ssl/certs/
   sudo cp ./agent_ssl_cert.key /etc/ssl/private/
   sudo cp ./agent_root_ca.cer /usr/local/share/ca-certificates/agent_root_ca.crt

2. Run the following command to update the trusted root certificates store.

   sudo update-ca-certificates -f

3. Specify the paths to the certificate and the private key in the configuration file of your web server, in the section that defines the agent website.

Port 3003 is set by default. If you use another port, create and configure a new binding for this port. The port must be open to incoming connections in the firewall.

Nginx configuration example

server {
        listen              3003 ssl;
        server_name         server.domain.loc;

        ssl_certificate     "/etc/ssl/certs/agent_ssl_cert.cer"; 
        ssl_certificate_key "/etc/ssl/private/agent_ssl_cert.key";
        ssl_verify_client   optional_no_ca;

        location /agentregistrationapi 
             {   include /etc/nginx/conf.d/proxy.conf;  
                proxy_pass http://localhost:5006/agentregistrationapi;  }
        location /agentserviceapi      
         {   include /etc/nginx/conf.d/proxy.conf;  
                proxy_pass http://localhost:5007/agentserviceapi;  
                proxy_set_header x-ssl-client-cert $ssl_client_escaped_cert;  }
    }

Apache configuration example

<VirtualHost *:3003>
    protocols h2 http/1.1

    SSLCertificateFile /etc/apache2/ssl/agent_ssl_cert.cer
    SSLCertificateKeyFile /etc/apache2/ssl/agent_ssl_cert.key
    SSLCipherSuite @SECLEVEL=1:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384                

    ErrorLog logs/error.log
    CustomLog logs/access.log combined

    SSLEngine on
    SSLProtocol -all +TLSv1.2
    SSLHonorCipherOrder off
    SSLCompression off
    SSLSessionTickets on
    SSLUseStapling off
    SSLProxyEngine on
    RequestHeader set X-Forwarded-Proto https
    Header always set Strict-Transport-Security "max-age=63072000"

        ProxyPass /agentregistrationapi http://localhost:5006/agentregistrationapi
        ProxyPassReverse /agentregistrationapi http://localhost:5006/agentregistrationapi

    <Location "/agentserviceapi">
        SSLVerifyClient optional_no_ca
        SSLOptions +ExportCertData
        RequestHeader unset x-ssl-client-cert
        RequestHeader set x-ssl-client-cert "expr=%{escape:%{SSL_CLIENT_CERT}}"
        #RequestHeader set x-ssl-client-cert "expr=%{escape:%{SSL_CLIENT_S_DN}}"

        ProxyPass http://localhost:5007/agentserviceapi
        ProxyPassReverse http://localhost:5007/agentserviceapi 
    </Location>
</VirtualHost>

info

The SSL/TLS certificate can be an RSA certificate issued by any trusted Certificate Authority (CA) for the Axidian CertiFlow server.

• Subject must include the Common Name attribute (the Axidian CertiFlow server FQDN).
• Subject Alternative Name (SAN) must include a DNS Name attribute (the Axidian CertiFlow server FQDN).
  For example: server.domain.loc or a wildcard entry *.domain.loc.
• Enhanced Key Usage (EKU) must include the Server Authentication value.