docs: add section on mtls (#2849)

Co-authored-by: PProfizi <[email protected]>
Co-authored-by: Paul Profizi <[email protected]>

Author: ansys-akarcher

doc/source/conf.py

@@ -217,6 +217,8 @@
 html_theme = "ansys_sphinx_theme"
 html_favicon = ansys_favicon
 html_theme_options = {
+    "announcement": """Starting with PyDPF-Core 0.15.0, gRPC communication with the DPF server defaults to requiring authentication.
+Refer to <a href='https://dpf.docs.pyansys.com/version/dev/getting_started/dpf_server.html#run-dpf-server-in-secure-mode-with-mtls'>this page</a> for more information.""",
     "logo": {
         "image_dark": pyansys_logo_dark_mode,
         "image_light": pyansys_logo_light_mode,

doc/source/getting_started/dpf_server.rst

@@ -120,3 +120,39 @@ DPF Server can be run in a Docker container.
     docker build . -t dpf-core:v2025.1.pre0 --build-arg DPF_VERSION=251
 
 5. To run the DPF Docker container, license it. For more information, see :ref:`DPF Preview License Agreement<target_to_license_terms>`.
+
+.. _ref_dpf_server_secure_mode:
+
+Run DPF Server in Secure mode wih mTLS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+
+    Starting with Ansys 2026 R1 (DPF 2026.1.0, kernel version 11.0) and PyDPF-Core 0.15.0,
+    DPF Server gRPC connections default to using `authenticated mTLS Transport<https://tools.docs.pyansys.com/version/stable/user_guide/secure_grpc.html>`.
+
+    This change is also brought by service packs for the following older Ansys versions:
+
+    - `Ansys 2025 R2 SP03`
+    - `Ansys 2025 R1 SP04`
+    - `Ansys 2024 R2 SP05`
+
+
+.. note::
+
+    The default client-server communication mode being InProcess,
+    this change only impacts users connecting to a remote DPF Server over gRPC.
+
+
+Both client and server now require mTLS certificates to establish a gRPC connection.
+
+The location to the mTLS certificates can be set using an environment variable ``ANSYS_GRPC_CERTIFICATES``.
+
+More information on the generation of certificates can be read on `Generating certificates for mtls<https://tools.docs.pyansys.com/version/stable/user_guide/secure_grpc.html#generating-certificates-for-mtls>`.
+
+This environment variable must be set both on the server machine and on the client machine when working remotely.
+
+The mTLS Transport mode can be disabled by setting ``DPF_DEFAULT_GRPC_MODE`` to ``insecure`` both client-side and server-side.
+
+This allows to fall back to the previous behavior when using gRPC communication.
+

src/ansys/dpf/core/server.py

@@ -32,6 +32,7 @@
 import functools
 import inspect
 import os
+from pathlib import Path
 import platform
 import socket
 import sys
@@ -43,8 +44,10 @@
 from ansys import dpf
 from ansys.dpf.core import errors, server_context
 from ansys.dpf.core.misc import get_ansys_path, is_ubuntu
+from ansys.dpf.core.server_context import ServerContext
 from ansys.dpf.core.server_factory import (
     CommunicationProtocols,
+    DockerConfig,
     GrpcMode,
     ServerConfig,
     ServerFactory,
@@ -158,63 +161,76 @@ def shutdown_all_session_servers():
 
 
 def start_local_server(
-    ip=LOCALHOST,
-    port=DPF_DEFAULT_PORT,
-    ansys_path=None,
-    as_global=True,
-    load_operators=True,
-    use_docker_by_default=True,
-    docker_config=RUNNING_DOCKER,
-    timeout=20.0,
-    config=None,
-    use_pypim_by_default=True,
-    context=None,
+    ip: str = LOCALHOST,
+    port: int = DPF_DEFAULT_PORT,
+    ansys_path: Path | str = None,
+    as_global: bool = True,
+    load_operators: bool = True,
+    use_docker_by_default: bool = True,
+    docker_config: DockerConfig = RUNNING_DOCKER,
+    timeout: float = 20.0,
+    config: ServerConfig = None,
+    use_pypim_by_default: bool = True,
+    context: ServerContext = None,
 ) -> AnyServerType:
     """Start a new local DPF server at a given port and IP address.
 
     This method requires Windows and ANSYS 2021 R1 or later. If ``as_global=True``, which is
     the default) the server is stored globally, replacing the one stored previously.
     Otherwise, a user must keep a handle on their server.
 
+    .. warning::
+        Starting with DPF 2026 R1 and PyDPF 0.15.0, the default gRPC server uses mTLS authentication.
+        Please refer to :ref:`ref_dpf_server_secure_mode` for more information on how to set up the
+        certificates and configure the server and client accordingly.
+        See the ``config`` parameter for more details.
+
     Parameters
     ----------
-    ip : str, optional
+    ip:
         IP address of the remote or local instance to connect to. The
         default is ``"LOCALHOST"``.
-    port : int, optional
+    port:
         Port to connect to the remote instance on. The default is
         ``"DPF_DEFAULT_PORT"``, which is 50054.
-    ansys_path : str or os.PathLike, optional
+    ansys_path:
         Root path for the Ansys installation directory. For example, ``"/ansys_inc/v212/"``.
         The default is the latest Ansys installation.
-    as_global : bool, optional
+    as_global:
         Global variable that stores the IP address and port for the DPF
         module. All DPF objects created in this Python session will
         use this IP and port. The default is ``True``.
-    load_operators : bool, optional
+    load_operators:
         Whether to automatically load the math operators. The default is ``True``.
-    use_docker_by_default : bool, optional
+    use_docker_by_default:
         If the environment variable DPF_DOCKER is set to a docker name and use_docker_by_default
         is True, the server is ran as a docker (default is True).
-    docker_config : server_factory.DockerConfig, optional
+    docker_config:
         To start DPF server as a docker, specify the docker configuration options here.
-    timeout : float, optional
+    timeout:
         Maximum number of seconds for the initialization attempt.
         The default is ``10``. Once the specified number of seconds
         passes, the connection fails.
-    config: ServerConfig, optional
-        Manages the type of server connection to use.
-    use_pypim_by_default: bool, optional
+    config:
+        Manages the type of server connection to use. Forced to LegacyGrpc on macOS.
+        Defaults to mTLS authenticated gRPC connection.
+        Define the path to the mTLS authentication certificates here if needed.
+        Define the default server authentication configuration with environment variables:
+        - ANSYS_GRPC_CERTIFICATES: path to the certificates directory
+        - DPF_GRPC_MODE: gRPC authentication mode, options are 'mtls' and 'insecure'.
+        More information available at :ref:`ref_dpf_server_secure_mode`.
+    use_pypim_by_default:
         Whether to use PyPIM functionalities by default when a PyPIM environment is detected.
         Defaults to True.
-    context: ServerContext, optional
+    context:
         Defines the settings that will be used to load DPF's plugins.
         A DPF xml file can be used to list the plugins and set up variables. Default is
         `server_context.SERVER_CONTEXT`.
 
     Returns
     -------
-    server : server.ServerBase
+    server:
+        The newly created server.
     """
     from ansys.dpf.core.misc import is_pypim_configured
 
@@ -266,6 +282,8 @@ def start_local_server(
                 if config is not None:
                     grpc_mode = config.grpc_mode
                     certs_dir = config.certificates_dir
+                else:
+                    config = ServerConfig()
                 server = server_type(
                     ansys_path,
                     ip,
@@ -315,37 +333,49 @@ def start_local_server(
 
 
 def connect_to_server(
-    ip=LOCALHOST,
-    port=DPF_DEFAULT_PORT,
-    as_global=True,
-    timeout=10.0,
-    config=None,
-    context=None,
+    ip: str = LOCALHOST,
+    port: int = DPF_DEFAULT_PORT,
+    as_global: bool = True,
+    timeout: float = 10.0,
+    config: ServerConfig = None,
+    context: ServerContext = None,
 ):
     """Connect to an existing DPF server.
 
     This method sets the global default channel that is then used for the
     duration of the DPF session.
 
+    .. warning::
+        Starting with DPF 2026 R1 and PyDPF 0.15.0, the default gRPC server uses mTLS authentication.
+        Please refer to :ref:`ref_dpf_server_secure_mode` for more information on how to set up the
+        certificates and configure the server and client accordingly.
+        See the ``config`` parameter for more details.
+
     Parameters
     ----------
-    ip : str
+    ip:
         IP address of the remote or local instance to connect to. The
         default is ``"LOCALHOST"``.
-    port : int
+    port:
         Port to connect to the remote instance on. The default is
         ``"DPF_DEFAULT_PORT"``, which is 50054.
-    as_global : bool, optional
+    as_global:
         Global variable that stores the IP address and port for the DPF
         module. All DPF objects created in this Python session will
         use this IP and port. The default is ``True``.
-    timeout : float, optional
+    timeout:
         Maximum number of seconds for the initialization attempt.
         The default is ``10``. Once the specified number of seconds
         passes, the connection fails.
-    config: ServerConfig, optional
+    config:
         Manages the type of server connection to use. Forced to LegacyGrpc on macOS.
-    context: ServerContext, optional
+        Defaults to mTLS authenticated gRPC connection.
+        Define the path to the mTLS authentication certificates here if needed.
+        Define the default server authentication configuration with environment variables:
+        - ANSYS_GRPC_CERTIFICATES: path to the certificates directory
+        - DPF_GRPC_MODE: gRPC authentication mode, options are 'mtls' and 'insecure'.
+        More information available at :ref:`ref_dpf_server_secure_mode`.
+    context:
         Defines the settings that will be used to load DPF's plugins.
         A DPF xml file can be used to list the plugins and set up variables. Default is
         `server_context.SERVER_CONTEXT`.

src/ansys/dpf/core/server_factory.py

@@ -66,6 +66,7 @@ class GrpcMode:
 DEFAULT_COMMUNICATION_PROTOCOL = CommunicationProtocols.InProcess
 DEFAULT_LEGACY = False
 DEFAULT_GRPC_MODE = GrpcMode.mTLS
+DEFAULT_CERTIFICATES_DIR = None
 
 
 class DockerConfig:
@@ -265,18 +266,33 @@ def find_port_available_for_docker_bind(port: int) -> int:
 class ServerConfig:
     """Provides an instance of ServerConfig object to manage the server type used.
 
+    .. warning::
+        Starting with DPF 2026 R1 and PyDPF 0.15.0, the default gRPC server uses mTLS authentication.
+        Please refer to :ref:`ref_dpf_server_secure_mode` for more information on how to set up the
+        certificates and configure the server and client accordingly.
+        See the ``config`` parameter for more details.
+
     The default parameters can be overwritten using the DPF_SERVER_TYPE environment
     variable. DPF_SERVER_TYPE=INPROCESS, DPF_SERVER_TYPE=GRPC,
     DPF_SERVER_TYPE=LEGACYGRPC can be used.
 
     Parameters
     ----------
-    protocol : CommunicationProtocols, optional
+    protocol:
         Communication protocol for DPF server (e.g. InProcess, gRPC)
-    legacy : bool, optional
+    legacy:
         If legacy is set to True, the server will be using ansys-grpc-dpf
         Python module. If not, it will communicate with DPF binaries using ctypes
         and DPF CLayer calls.
+    grpc_mode:
+        Grpc mode to use when launching DPF server.
+        Can be one of the members of :class:`ansys.dpf.core.server_factory.GrpcMode`.
+        Defaults to mTLS authenticated mode.
+        More information available at :ref:`ref_dpf_server_secure_mode`.
+    certificates_dir:
+        Path to a directory containing the certificates to use for mTLS authentication.
+        More information available at :ref:`ref_dpf_server_secure_mode`.
+
 
     Examples
     --------
@@ -307,7 +323,7 @@ def __init__(
         protocol: str = DEFAULT_COMMUNICATION_PROTOCOL,
         legacy: bool = DEFAULT_LEGACY,
         grpc_mode: str = DEFAULT_GRPC_MODE,
-        certificates_dir: Path = None,
+        certificates_dir: Path = DEFAULT_CERTIFICATES_DIR,
     ):
         self.legacy = legacy
         if not protocol:
@@ -319,7 +335,11 @@ def __init__(
             self.grpc_mode = DEFAULT_GRPC_MODE
         else:
             self.grpc_mode = grpc_mode
-        self.certificates_dir = certificates_dir
+        self.certificates_dir = (
+            certificates_dir
+            if certificates_dir
+            else os.environ.get("ANSYS_GRPC_CERTIFICATES", None)
+        )
 
     def __str__(self):
         """Return a string representation of the ServerConfig instance.