Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Authenticating Users Executing Ansible Modules on Devices Running Junos OS

 

Ansible and Juniper Networks provide Ansible modules that you can use to manage devices running Junos OS. Starting in Ansible Release 2.1, Ansible natively includes a number of core modules for devices running Junos OS. In addition, Juniper Networks provides a collection of modules in the Juniper.junos role, which is hosted on the Ansible Galaxy website.

The Ansible core and Ansible Galaxy modules for Junos OS enable you to connect to devices running Junos OS using NETCONF over SSH. In addition, the Ansible Galaxy modules enable you to connect to devices using a serial console connection or telnet. The device must be able to authenticate the user using a password or other standard SSH authentication mechanisms, depending on the connection method.

Note

Starting in Ansible for Junos OS Release 2.0.0, the Juniper.junos role includes an enhanced set of modules. Each new module replaces the functionality of one or more existing modules. All modules support a common set of connection and authentication parameters, aliases that enable you to specify the same connection and authentication-related options as the core modules, and the ability to specify the parameters inside a provider dictionary.

The Ansible core and Ansible Galaxy modules for Junos OS support specifying connection and authentication-related options inside a provider dictionary. In addition, the Ansible Galaxy modules for Junos OS enable you to define the parameters as top-level module arguments.

When you use Ansible to manage devices running Junos OS, the most convenient way to access the device is to configure SSH keys. SSH keys enable the device running Junos OS to identify the Ansible user as a trusted user. Alternatively, you can provide username and password authentication credentials when you execute modules and playbooks. By default, Ansible for Junos OS modules first attempt SSH public key-based authentication and then try password-based authentication. To retrieve a password for password-based authentication or password-protected SSH keys, you can prompt for the password from the playbook or on the command-line, or you can create a vault-encrypted data file that includes the password.

The following sections discuss the different aspects of authentication when using Ansible for Junos OS modules to manage devices running Junos OS:

Defining Connection and Authentication Options

Ansible core networking modules use the provider parameter for passing connection details and authentication-related options to the module. Starting in Ansible for Junos OS Release 2.0.0, the Ansible Galaxy modules in the Juniper.junos role also support the provider parameter in addition to supporting individual top-level module arguments for each of the connection and authentication-related parameters. The provider parameter enables you to define the connection and authentication parameters for a number of devices in one place and easily pass those values to a module.

The provider argument accepts a dictionary that contains the connection details required to connect to and authenticate with a device. The host argument is always required for a connection, but it does not have to be specified explicitly if the module uses a default value for host. The dictionary can optionally define additional parameters required for the connection, including username, password, and ssh_keyfile, among others. For more information about the provider argument for networking modules, see https://docs.ansible.com/ansible/latest/intro_networking.html. For information about the arguments accepted for the individual modules, see the individual module documentation.

In the following example, the credentials variable is a dictionary that defines the host, username, and password parameters:

The following sample playbook uses the single provider argument to pass in the connection details to the juniper_junos_facts module instead of defining the individual host, username, and password arguments in the module:

Understanding the Default Values for the Ansible Galaxy Modules for Junos OS

You can explicitly define the connection and authentication parameters for Ansible core and Ansible Galaxy modules for Junos OS. If you do not define a parameter, the module uses a default value in some cases. Table 1 outlines the default values and parameter aliases for common connection parameters for the Juniper.junos Ansible Galaxy modules. For information about the arguments accepted for the individual modules, see the documentation for that module. For information about the default values for Ansible core modules for Junos OS, see https://docs.ansible.com/ansible/latest/list_of_network_modules.html#junos.

Note

Starting in Ansible for Junos OS Release 2.0.0, the Juniper.junos modules support the same parameter names for connection and authentication-related options as the core modules.

Table 1: Connection Argument Defaults for Ansible Galaxy Modules for Junos OS

Parameter Name

Parameter Aliases (Ansible Galaxy Modules)

Description

Default Value for Ansible Galaxy Modules for Junos OS

host

hostname

ip

Hostname or IP address of the managed device with which the connection should be established.

{{ inventory_hostname }}

password

passwd

The user password or SSH key passphrase used to authenticate with the managed device.

  1. ANSIBLE_NET_PASSWORD environment variable

  2. Value specified for -k or --ask-pass command-line option

ssh_keyfile

ssh_private_key_file

Path to the SSH private key file used to authenticate with the managed node.

If you do not explicitly specify the path and no default value is found, then the module uses the SSH private key file specified in the user’s SSH configuration or the operating-system-specific default.

  1. ANSIBLE_NET_SSH_KEYFILE environment variable

  2. Value specified for --private-key or --key-file command-line option

  3. none

username

user

Username used to authenticate with the managed node.

  1. ANSIBLE_NET_USERNAME environment variable

  2. remote_user as defined by Ansible

  3. USER environment variable

When executing modules in the Juniper.junos role, the host argument is always required for a connection, but it does not have to be specified explicitly, because it defaults to {{ inventory_hostname }}.

The Juniper.junos modules first attempt SSH public key-based authentication and then try password-based authentication. When SSH keys are in use, the password argument is used as the passphrase for unlocking the private SSH key. When password-based authentication is used, the password argument is used as the password. If SSH public key-based authentication is being used and the SSH private key has an empty passphrase, then the password argument may be omitted. However, SSH private keys with empty passphrases are not recommended.

You can execute Juniper.junos modules using any user account that has access to the managed device running Junos OS. When you execute the modules, Junos OS user account access privileges are enforced, and the class configured for the Junos OS user account determines the permissions. If you do not specify a user, the user is set according to the algorithm described for username in Table 1. See the Ansible documentation for the precedence used to define remote_user, which can be defined in a number of ways, including:

  • -u or --user command line option

  • ANSIBLE_REMOTE_USER environment variable

  • remote_user configuration setting

Authenticating the User Using SSH Keys

To authenticate a user executing Ansible for Junos OS modules using SSH keys, generate the keys on the Ansible server and configure the keys on each managed device running Junos OS.

To generate SSH keys on the Ansible control machine and configure the public key on devices running Junos OS:

  1. On the Ansible control machine, generate the public and private SSH key pair for the desired user, and provide any required options, for example:

  2. (Optional) Load the key into the native SSH key agent. For example:

  3. Configure the public key under the appropriate user account on all devices running Junos OS that will be managed using this key.

    The easiest method is to create a file that contains the public key and then load the file into the configuration.

  4. Verify that the key works by logging in to the device using the key.

After generating the SSH key pair and configuring the public key on the managed device, you can connect to the device using the key by including the appropriate arguments in the Ansible playbook. The module arguments are determined by the location of the key, whether the key is actively loaded into an SSH key agent, and whether the key is password-protected. If you do not explicitly define the module arguments, the modules use the defaults defined in Understanding the Default Values for the Ansible Galaxy Modules for Junos OS.

  • To connect to the managed device using SSH keys that are actively loaded into the native SSH key agent or that are in the default location and do not have password protection, you do not need to define any connection or authentication-related module arguments, unless they differ from the default.

  • To connect to a device running Junos OS using SSH keys that are not in the default location and do not have password protection, set the ssh_keyfile module argument to the path of the SSH private key file. For example:

    Where:

    Alternatively, you can specify the path of the SSH private key by setting the ANSIBLE_NET_SSH_KEYFILE environment variable or by defining the --private-key or --key-file command-line option when you execute the playbook.

    Note

    Juniper.junos modules also accept the ssh_private_key_file parameter in place of ssh_keyfile.

  • To connect to a device running Junos OS using a password-protected SSH key file, which is the recommended method, provide the SSH key file passphrase in the password argument.

    It is the user's responsibility to obtain the SSH key file passphrase in a secure manner appropriate for their environment. It is best practice to either prompt for these authentication credentials during each invocation of the playbook or store the variables using an encrypted vault rather than storing the credentials in an unencrypted format. For example, you can execute the playbook with the --ask-pass command-line option and provide the SSH key file passphrase when prompted.

    Where:

    [user@localhost]$ ansible-playbook playbook.yaml --ask-pass

    For more information about using a prompt or encrypted vault for the SSH key passphrase, see Authenticating the User Using a Playbook or Command-Line Password Prompt and Authenticating the User Using an Ansible Vault-Encrypted File.

Authenticating the User Using a Playbook or Command-Line Password Prompt

To authenticate a user executing Ansible for Junos OS modules, you can obtain the authentication credentials by including an interactive prompt in the playbook or by executing the playbook with the -k or --ask-pass command-line option. When SSH keys are in use, the password argument is used as the passphrase for unlocking the private SSH key. When password-based authentication is used, the password argument is used as the password.

The following example shows one method for interactively obtaining the user’s password or SSH key passphrase:

  1. Include code under vars_prompt: that prompts for the user’s password or SSH key passphrase (and optionally the username) and stores the value in a variable.

  2. Define a provider dictionary, and set the username and password parameters to reference its respective variable.

  3. In the module’s parameter list, set the provider argument to the credentials variable containing the authentication credentials.

  4. Execute the playbook, which prompts for the username and password and does not echo the password on the command line, because the variable is set to private: yes.

    [user@localhost]$ ansible-playbook playbook.yaml

Alternatively, you can execute a playbook with the -k or --ask-pass command-line option to prompt for the password or passphrase. Consider the following playbook, which uses the default username:

Execute the playbook, and include the -k or --ask-pass command-line option, which prompts for the password and does not echo the password on the command line.

[user@localhost]$ ansible-playbook playbook.yaml --ask-pass

Authenticating the User Using an Ansible Vault-Encrypted File

To authenticate a user executing Ansible for Junos OS modules using a saved password, you can create an Ansible vault that stores the password in an vault-encrypted data file. When SSH keys are in use, the password argument is used as the passphrase for unlocking the private SSH key. When password-based authentication is used, the password argument is used as the password.

To create and use an Ansible vault file containing required variables including passwords:

  1. Create a vault-encrypted data file, and specify the password required to encrypt, decrypt, edit, and use the data file.

  2. Include any desired variables in the file, and save the file.

  3. Verify that the file is encrypted.

    [root@localhost]# cat vault-vars.yaml
  4. In the playbook, include the vault-encrypted variable file, and reference the appropriate variables where required.

  5. Execute the playbook with the --ask-vault-pass option, which prompts for the vault password.

    [root@localhost]# ansible-playbook playbook-name.yaml --ask-vault-pass
Release History Table
Release
Description
Starting in Ansible for Junos OS Release 2.0.0, the Juniper.junos role includes an enhanced set of modules.