Using User-Defined TIBCO FTL Certificates

ActiveSpaces grid processes and client applications can use the security capabilities of TIBCO FTL, which include user-defined certificates and OAuth2 or mTLS authentication providers.

User-Defined Certificates

Configure a grid using your own user-defined certificates instead of TIBCO FTL-generated certificates. For more information, see Enabling TLS for FTL Server. If you are using these certificates, TIBCO FTL server, all ActiveSpaces grid processes, and all ActiveSpaces client applications must be updated and properly configured with the correct command-line parameters and connection properties to communicate successfully.

If you want, you can load the required trust file for each process to the system trust store rather than configuring the trust file by using command line or connection properties. For specific information about loading certificates into the system trust store, consult your operating system documentation.

You must configure an authentication provider when you enable TLS connections in TIBCO FTL.

ActiveSpaces includes a TLS sample directory with configuration and a README file to highlight additional parameters needed for this setup. Additionally, in the samples/scripts directory, the as-certs script is provided to demonstrate how to generate the certificates correctly.

Note the following key differences in ActiveSpaces grid processes when you configure them with user-defined certificates:

  • After generating the certificates, the TIBCO FTL server must set the following additional properties in the ftl.yaml file:

    • tls.server.cert

    • tls.server.private.key

    • tls.server.private.key.password

    • tls.client.trust.file

  • You must configure tibdgadminsvc as service in the TIBCO FTL server and not as a standalone process. Although you can configure state keepers as a standalone process, TIBCO recommends you to configure the state keeper in the same way (as a service). When you run processes as services, you do not need security-related command-line parameters because the TIBCO FTL server provides the local, secure connections. Every TIBCO FTL server must host a tibdgadminsvc service.

  • To connect to the TIBCO FTL server, the tibdg admin tool needs the following files:

    • a trust file (--trust-file)

    • a user password file (--user-password-file)

  • The tibdgnode and tibdgproxy grid processes connecting to the TIBCO FTL server must use the following command-line parameters:

    • --trust-file

    • --user-password-file

  • As tibdgnode and tibdgproxy grid processes act as servers for other processes, they must use the following command-line parameters:

    • --server-cert-file

    • --server-private-key

    • --server-private-key-pwd

    • --server-host

  • The tibdgnode and tibdgproxy grid processes must specify a --server-host parameter that matches their certificate and the host on which they are running.

  • ActiveSpaces client applications must set the connection property TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE to TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE and set the TIBDG_CONNECTION_PROPERTY_STRING_TRUST_FILE property value to the location of the user-generated trust file. For more information, see the samples directory.

Authentication Providers

You can configure the following authentication providers with user-defined certificates:

  • File-based authentication provider

  • OAuth2 authentication provider

  • mTLS authentication provider

File-based Authentication Provider

The file-based authentication provider in the FTL server is supported for both FTL-generated and user-defined certificates. Client applications use the TIBDG_CONNECTION_PROPERTY_STRING_USERNAME and TIBDG_CONNECTION_PROPERTY_STRING_USERPASSWORD properties to set the authentication values that must match the values provided in the authentication file provided to the TIBCO FTL server.

OAuth2 Authentication Provider

Configure the TIBCO FTL server with an OAuth2 authentication provider, which is then used by ActiveSpaces grid processes and client applications. Grid connections are authenticated by obtaining and using a signed JWT token issued by a separate OAuth2 server. For more information, see Using the Built-In OAuth 2.0 Based Authentication Service in TIBCO FTL® Security.

ActiveSpaces includes an oauth2 sample directory that includes configuration and a README to provide you with the parameters that are needed with this setup. Additionally, the as-certs script is provided that helps you generate the certificates correctly.

Note the following key differences in ActiveSpaces grid processes when you configure them with an OAuth2 authentication provider:

  • After the certificates are generated, the TIBCO FTL server sets several additional properties in the ftl.yaml file including:

    • tls.server.cert

    • tls.server.private.key

    • tls.server.private.key.password

    • tls.client.trust.file

    • oauth2.validation.key

    • oauth2.svr.client.id

    • oauth2.svr.client.secret

    • oauth2.svr.endpoint.token

    • oauth2.provider.trust.file (required only if the OAuth2 server uses https)

  • You must configure tibdgadminsvc as service in the TIBCO FTL server and not as a standalone process. Although you can configure state keepers as a standalone process, TIBCO recommends you to configure the state keeper in the same way (as a service). When you run them as service, you do not need the security-related command-line parameters because the TIBCO FTL server provides the local, secure connections. Every TIBCO FTL server must host a tibdgadminsvc service.

  • To connect to the TIBCO FTL server, the tibdg admin tool needs the following files:

    • a trust file (--trust-file)

    • oauth2 token (--oauth2-token)

  • To connect to the TIBCO FTL server, the tibdgnode and tibdgproxy grid processes must use the following command-line parameters:

    • --trust-file

    • --oauth2-server-url

    • --oauth2-client-id

    • --oauth2-client-secret

    • --oauth2-server-trust-file (when connecting via https to the OAuth2 server)

  • As tibdgnode and tibdgproxy grid processes act as servers for other processes, they must use the following command-line parameters:

    • --server-cert-file

    • --server-private-key

    • --server-private-key-pwd

    • --server-host

  • ActiveSpaces client applications must set the following connection properties:

    • TIBDG_CONNECTION_PROPERTY_STRING_OAUTH2_SERVER_URL

    • TIBDG_CONNECTION_PROPERTY_STRING_OAUTH2_CLIENT_ID

    • TIBDG_CONNECTION_PROPERTY_STRING_OAUTH2_CLIENT_SECRET

    • TIBDG_CONNECTION_PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE (needed to connect to an https-based OAuth2 server URL)

mTLS Authentication Provider

Configure the TIBCO FTL server with an mTLS authentication provider, which is then used by ActiveSpaces grid processes and client applications. Clients can authenticate with the TIBCO FTL server with specifically formatted certificates. For more information, see the Using the Built-In mTLS Based Authentication Service section in TIBCO FTL® Security.

ActiveSpaces includes the mtls sample directory that includes configuration and a README to highlight the parameters that are needed with this setup. Additionally, the as-certs script is provided that helps you generate the certificates correctly.

Note the following key differences in ActiveSpaces grid processes when you configure them with user-defined certificates and an mTLS authentication provider:

  • After the certificates are generated, the TIBCO FTL server sets several additional properties in the ftl.yaml file including:

    • tls.server.cert

    • tls.server.private.key

    • tls.server.private.key.password

    • tls.client.trust.file

  • You must configure tibdgadminsvc as service in the TIBCO FTL server and not as a standalone process. Although you can configure state keepers as a standalone process, TIBCO recommends you to configure the state keeper in the same way (as a service). When you run them as service, you do not need the security-related command-line parameters because the TIBCO FTL server provides the local, secure connections. Every TIBCO FTL server must host a tibdgadminsvc service.

  • To connect to the TIBCO FTL server, the tibdg admin tool must use a trust file and client certificates:

    • --trust-file

    • --client-cert-file

    • --client-private-key

    • --client-private-key-pwd

  • To connect to the TIBCO FTL server, the tibdgnode and tibdgproxy grid processes must use the following command-line parameters:

    • --trust-file

    • --client-cert-file

    • --client-private-key

    • --client-private-key-pwd

  • As tibdgnode and tibdgproxy grid processes act as servers for other processes, they must use the following command-line parameters:

    • --server-cert-file

    • --server-private-key

    • --server-private-key-pwd

    • --server-host

    • --server-trust-file

  • The tibdgnode and tibdgproxy grid processes must specify a --server-host parameter that matches their certificate and the host on which they are running.

  • ActiveSpaces client applications must set the following connection properties:

    • TIBDG_CONNECTION_PROPERTY_STRING_CLIENT_CERT

    • TIBDG_CONNECTION_PROPERTY_STRING_CLIENT_PRIVATE_KEY

    • TIBDG_CONNECTION_PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD

Samples

In the installation directory of ActiveSpaces, in the samples/security directory, security configurations and README files are provided to explain how to configure and use the TIBCO FTL 7.0.0 security capabilities. Refer to these samples to understand how to configure grid processes and client applications.

In the sample/scripts directory, the as-certs script is provided that you can use as an example to understand how to generate properly formatted user-defined certificates.