Plugin

This external source type allows the integration of third-party external source implementations. Plugins are added by installing plugin packages that will be visible during the configuration.

Plugin package

Plugin packages are Python packages that uses metadata for plugins through entrypoints. The plugin package needs to register classes as a entrypoints for radkit_service.external_sources.plugins group.

Examples:

  • pyproject.toml

[project.entry-points."radkit_service.external_sources.plugins"]
"My Custom Plugin" = "my_package.my_module:MyClass"

  • setup.py

from setuptools import setup

setup(
    ...,
    entry_points={
        "radkit_service.external_sources.plugins": [
            "My Custom Plugin = my_package.my_module:MyClass",
        ],
    },
)

  • config.cfg

[options.entry_points]
radkit_service.external_sources.plugins =
    My Custom Plugin = my_package.my_module:MyClass

Protocol

To fulfill the protocol’s needs, the configured implementation must follow the defined protocol:

class radkit_service.external_sources.ExternalSource

Bases: Protocol

External Source Protocol definition.

There are four methods for utilizing external sources:

  • Generating terminal/netconf/snmp/swagger/http connection parameters:

    In this method, within the YAML protocol definitions, the external source is cited in the protocol section, for example:

    terminal: !external
    name: <name of referenced external source>
    values: <additional parameters for external source>

    Here, the external source is tasked with constructing the TerminalConnectionParameters data structure, triggering the invocation of create_terminal_connection_parameters.

  • Retrieving secret attributes:

    In this method, within the YAML protocol definitions, the external source is mentioned in the attribute definition, for instance:

    terminal:
    password: !external
        name: <name of referenced external source>
        values:
            path: <secret path>

    This indicates that the external source is accountable for procuring the specific secret, and compute_device_parameters will be executed as below:

    await external_source.compute_device_parameters(query=...)

  • Authenticating users:

    In this method external source will be used for authenticating admins for login or authentication remote users for RPC calls. Passed username and password will be passed like this:

    await external_source.authenticate_user(
    username=<username>,
    password=<password>,
)

  • Authorizing users

    In this method external source will be used for authorizing remote user for RPC calls.

    Passed username will be passed like this:

    await external_source.authorize_user(username=<username>)

    Returned authorized user data structure is used downstream to accept or reject specific connection. If None is returned, it means that user is not authorized.

    Note

    As for now, we are unable to do direct SSO connections if external source is used for remote user authentication and authorization.

Should a particular external source implementation be incapable of generating connection parameters or retrieving secrets, it ought to return a NotImplementedError.

Warning

Implementing a cache mechanism might provide some performance improvements, but long TTLs can reduce reactivity for changes. For example, caching authentication results can lead to a situation where a non-authorized user might be authenticated due to the cache.

async compute_device_parameters(
query: ExternalSourceQuery,
) → None | bool | str | float | int | Sequence[Tree] | Mapping[str, Tree] | Callable[[...], Any] | CustomSecretStr
async authenticate_user(
username: str,
password: str,
) → AuthenticatedUser | None

Authenticates user by given credentials.

async authorize_user(
username: str,
) → AuthorizedUser | None

Authorizes user.

async authorize_admin(
username: str,
) → AuthorizedAdmin | None

Authorizes admin.

Data types

class radkit_service.external_sources.types.AuthenticatedUser

Bases: TypedDict

Data structure used to describe authenticated user. Used in webserver session middleware.

username: str
email: str
fullname: str
description: str
class radkit_service.external_sources.types.AuthorizedUser

Bases: TypedDict

Data structure used to describe authorized user. Used in database device backend.

connection_mode_cloud_active: bool
connection_mode_direct_active: bool
connection_mode_direct_sso_active: bool
class radkit_common.types.ConnectionMethod

Bases: str, Enum

SSH = 'SSH'
SSHPUBKEY = 'SSHPUBKEY'
TELNET = 'TELNET'
TELNET_NO_AUTH = 'TELNET_NO_AUTH'
NETCONF = 'NETCONF'
class radkit_common.types.TerminalCapabilities

Bases: str, Enum

INTERACTIVE = 'INTERACTIVE'
EXEC = 'EXEC'
UPLOAD = 'UPLOAD'
DOWNLOAD = 'DOWNLOAD'
class radkit_common.terminal_interaction.provisioning_variants.ProvisioningVariant

Bases: str, Enum

DEFAULT = 'DEFAULT'
NCS_2000_LF1 = 'LF1'