dellemc.enterprise_sonic.sonic_mfa module – Manage Multi-factor authentication (MFA) configurations on SONiC.

Note

This module is part of the dellemc.enterprise_sonic collection (version 4.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install dellemc.enterprise_sonic.

To use it in a playbook, specify: dellemc.enterprise_sonic.sonic_mfa.

New in dellemc.enterprise_sonic 4.0.0

Synopsis

• This module provides configuration management of MFA parameters for devices running SONiC.

• Pre-configured host cert is required for MFA security profile, and ca-cert for RSA/CAC-PIV security profiles.

Parameters

Parameter	Comments
config dictionary	Specifies MFA configurations.
cac_piv_global dictionary	CAC-PIV Global configuration.
cert_username_field string	SSH user certificate field for matching with SSH login username. Choices: "common-name" "common-name-or-user-principal-name" "user-principal-name"
cert_username_match string	Match option to parse the username from respective certificate field. Choices: "10digit-username" "first-name" "username-as-is" "username-without-domain"
security_profile string	Security profile for SSH access with CAC-PIV.
mfa_global dictionary	MFA Global configuration.
client_secret string	Password used in basic authorization header for MFA REST API. Minimum 32 characters with atleast one symbol, digit, uppercase, and lowercase. Plain text password i.e. client_secret_encrypted=false will be stored in encrypted format in running-config, so idempotency will not be maintained and hence the task output will always be changed=true.
client_secret_encrypted boolean	Indicates whether client_secret is plain text or encrypted. Choices: false true
key_seed string	Seed for generating secure key in MFA service. Plain text seed i.e. key_seed_encrypted=false will be stored in encrypted format in running-config, so idempotency will not be maintained and hence the task output will always be changed=true.
key_seed_encrypted boolean	Indicates whether key_seed is plain text or encrypted. Choices: false true
security_profile string	Security profile contains the certificate for MFA service.
rsa_global dictionary	RSA Global configuration.
security_profile string	Security profile with CA-cert for validating RSA SecurID server.
rsa_servers list / elements=dictionary	RSA Server configuration.
client_id string	Unique identifier of the system as a client of SecurID service, assigned by SecurID service.
client_key string	Key associated with the client-id, assigned by SecurID service. Plain text key i.e. client_key_encrypted=false will be stored in encrypted format in running-config, so idempotency will not be maintained and hence the task output will always be changed=true.
client_key_encrypted boolean	Indicates whether client_key is plain text or encrypted. Choices: false true
connection_timeout integer	Timeout in seconds for connection to the SecurID server. Range 1-30.
hostname string / required	RSA server’s hostname or IP address.
read_timeout integer	Timeout in seconds to read from the SecurID server. Range 1-150.
server_port integer	Port number of the RSA SecurID server. Range 1025-49151.
state string	The state of the configuration after module completion. merged - Merges provided MFA configuration with on-device configuration. replaced - Replaces on-device MFA configuration with provided configuration. overridden - Overrides all on-device MFA configurations with the provided configuration. deleted - Deletes on-device MFA configuration. Choices: "merged" ← (default) "deleted" "replaced" "overridden"

Examples

# Using "deleted" state
#
# Before state:
# -------------
#
# sonic# show running-configuration mfa
# mfa key-seed U2FsdGVkX1/caD7u0ZGRnb981G2DKyML/Gvyfexsurg= encrypted
# mfa client-secret U2FsdGVkX1+WlquxtZRbsgQhfS1lQBFbJKflxGAp6S3u+Ox5Hi+O16NmprjMVb3HQn1pNSgaaa0Cz1MHeTfDWhFR0WqdENbLU2PqkiRDHv0iVfl72xNPzhnGeO01kAu0 encrypted
# mfa security-profile mSecurityProfile
# mfa rsa-server security-profile rSecProfile
# mfa rsa-server host rsaserver.che-lab.it port 1030 client-id sonicdevtest.che-lab.it client-key
# U2FsdGVkX18QFJoB9dp8GJN92eP79FGOZDLgQakBmAasGYX77p6PtiiAfS/nGoOb2uEocUkryc+BLLYsg+Wz0gO+c1QsIbIhXk5Pt+aECoVgoFQ9QpxO9od9cTik+3Ot encrypted
# connection-timeout 29 read-timeout 149
#
# sonic# show running-configuration | grep "cac-piv"
# aaa cac-piv cert-user common-name
# aaa cac-piv cert-user-match 10digit-username
# aaa cac-piv security-profile cSecurityProfile
# sonic#


- name: Delete specified mfa configuration
  dellemc.enterprise_sonic.sonic_mfa:
    config:
      mfa_global:
        key_seed: 'U2FsdGVkX1/caD7u0ZGRnb981G2DKyML/Gvyfexsurg='
        key_seed_encrypted: true
        client_secret: 'U2FsdGVkX1+WlquxtZRbsgQhfS1lQBFbJKflxGAp6S3u+Ox5Hi+O16NmprjMVb3HQn1pNSgaaa0Cz1MHeTfDWhFR0WqdENbLU2PqkiRDHv0iVfl72xNPzhnGeO01kAu0'
        client_secret_encrypted: true
      rsa_global:
        security_profile: 'rSecProfile'
      rsa_servers:
        hostname: 'rsaserver.che-lab.it'
        server_port: 1030
        client_id: 'sonicdevtest.che-lab.it'
        client_key: 'U2FsdGVkX18QFJoB9dp8GJN92eP79FGOZDLgQakBmAasGYX77p6PtiiAfS/nGoOb2uEocUkryc+BLLYsg+Wz0gO+c1QsIbIhXk5Pt+aECoVgoFQ9QpxO9od9cTik+3Ot'
        client_key_encrypted: true
        connection_timeout: 29
        read_timeout: 149
      cac_piv_global:
        security_profile: 'cSecurityProfile'
        cert_username_field: 'common-name'
    state: deleted


# After state:
# ------------
#
# sonic# show running-configuration mfa
# mfa security-profile mSecurityProfile
#
# sonic# show running-configuration | grep "cac-piv"
# aaa cac-piv cert-user-match 10digit-username
# sonic#


# Using "deleted" state
#
# Before state:
# -------------
#
# sonic# show running-configuration mfa
# mfa key-seed U2FsdGVkX1/caD7u0ZGRnb981G2DKyML/Gvyfexsurg= encrypted
# mfa client-secret U2FsdGVkX1+WlquxtZRbsgQhfS1lQBFbJKflxGAp6S3u+Ox5Hi+O16NmprjMVb3HQn1pNSgaaa0Cz1MHeTfDWhFR0WqdENbLU2PqkiRDHv0iVfl72xNPzhnGeO01kAu0 encrypted
# mfa security-profile mSecurityProfile
# mfa rsa-server security-profile rSecProfile
# mfa rsa-server host rsaserver.che-lab.it port 1030 client-id sonicdevtest.che-lab.it client-key
# U2FsdGVkX18QFJoB9dp8GJN92eP79FGOZDLgQakBmAasGYX77p6PtiiAfS/nGoOb2uEocUkryc+BLLYsg+Wz0gO+c1QsIbIhXk5Pt+aECoVgoFQ9QpxO9od9cTik+3Ot encrypted
# connection-timeout 29 read-timeout 149
#
# sonic# show running-configuration | grep "cac-piv"
# aaa cac-piv cert-user common-name
# aaa cac-piv cert-user-match 10digit-username
# aaa cac-piv security-profile cSecurityProfile
# sonic#


- name: Delete all mfa configurations
  dellemc.enterprise_sonic.sonic_mfa:
    config:
    state: deleted


# After state:
# ------------
#
# sonic# show running-configuration mfa
# sonic#
#
# sonic# show running-configuration | grep "cac-piv"
# sonic#


# Using "merged" state
#
# Before State:
# -------------
#
# sonic# show running-configuration mfa
# sonic#
#
# sonic# show running-configuration | grep "cac-piv"
# sonic#


- name: Merge provided MFA configurations
  dellemc.enterprise_sonic.sonic_mfa:
    config:
      mfa_global:
        security_profile: 'mSecurityProfile'
        key_seed: 'sonic'
        key_seed_encrypted: true
        client_secret: 'U2FsdGVkX18mPdwkM1z24i7lxMtqNZR9p2q3aa6YXR16OfDxQXCR9z9I0lQZpVjE!'
        client_secret_encrypted: true
      rsa_global:
        security_profile: 'rSecProfile'
      rsa_servers:
        hostname: 'rsaserver.che-lab.it'
        server_port: 1030
        client_id: 'sonicdevtest.che-lab.it'
        client_key: 'aplr05825jshusp80699scuv62u5l3lu63wxf66b0y883w92677ac0c9m0lwv6o8'
        client_key_encrypted: true
        connection_timeout: 29
        read_timeout: 149
      cac_piv_global:
        security_profile: 'cSecurityProfile'
        cert_username_field: 'user-principal-name'
        cert_username_match: '10digit-username'
    state: merged


# After State:
# ------------
#
# sonic# show running-configuration mfa
# mfa key-seed U2FsdGVkX1/caD7u0ZGRnb981G2DKyML/Gvyfexsurg= encrypted
# mfa client-secret U2FsdGVkX1+WlquxtZRbsgQhfS1lQBFbJKflxGAp6S3u+Ox5Hi+O16NmprjMVb3HQn1pNSgaaa0Cz1MHeTfDWhFR0WqdENbLU2PqkiRDHv0iVfl72xNPzhnGeO01kAu0 encrypted
# mfa security-profile mSecurityProfile
# mfa rsa-server security-profile rSecProfile
# mfa rsa-server host rsaserver.che-lab.it port 1030 client-id sonicdevtest.che-lab.it client-key
# U2FsdGVkX18QFJoB9dp8GJN92eP79FGOZDLgQakBmAasGYX77p6PtiiAfS/nGoOb2uEocUkryc+BLLYsg+Wz0gO+c1QsIbIhXk5Pt+aECoVgoFQ9QpxO9od9cTik+3Ot encrypted
# connection-timeout 29 read-timeout 149
#
# sonic# show running-configuration | grep "cac-piv"
# aaa cac-piv cert-user user-principal-name
# aaa cac-piv cert-user-match 10digit-username
# aaa cac-piv security-profile cSecurityProfile


# Using "replaced" state
#
# Before state:
# -------------
#
# sonic# show running-configuration mfa
# mfa key-seed U2FsdGVkX1/caD7u0ZGRnb981G2DKyML/Gvyfexsurg= encrypted
# mfa rsa-server host rsaserver.che-lab.it port 1030 client-id sonicdevtest.che-lab.it client-key
# U2FsdGVkX1+xnsxfUrqCvBQg0KkPUm11R8Vpn2cXLHCWzL59k3Jm4/OrRiMOemPJccnEa8sMuynOAaySpHkaMOePtpedW0aApp+qicIF2Hz32LR4vB07b7OSx7OaEZBj encrypted
# connection-timeout 16 read-timeout 129


- name: Replace specified mfa rsa-server configuration
  dellemc.enterprise_sonic.sonic_mfa:
    config:
      rsa_servers:
        - hostname: 'rsaserver.che-lab.it'
          server_port: 1050
          client_id: 'sonicdevtest.che-lab.it'
          client_key: 'aplr05825jshusp80699scuv62u5l3lu63wxf66b0y883w92677ac0c9m0lwv6o8'
          client_key_encrypted: true
          connection_timeout: 29
          read_timeout: 149
    state: replaced


# After state:
# ------------
#
# sonic# show running-configuration mfa
# mfa key-seed U2FsdGVkX1/caD7u0ZGRnb981G2DKyML/Gvyfexsurg= encrypted
# mfa rsa-server host rsaserver.che-lab.it port 1050 client-id sonicdevtest.che-lab.it client-key
# U2FsdGVkX1/b1Tjka6pWv1BjwGd1I8cfjXxBIIJ6ZK/JaZpGgPbNAnw6WmdstRWJz49A+bymj6gJfkGjbzlWQhGCGi4VofPStOdNktqDcIyk33AaDkO+awkzyi7HRxcB encrypted
# connection-timeout 29 read-timeout 149


# Using "overridden" state
#
# Before state:
# -------------
#
# sonic# show running-configuration mfa
# mfa key-seed U2FsdGVkX1/caD7u0ZGRnb981G2DKyML/Gvyfexsurg= encrypted
# mfa client-secret U2FsdGVkX1+WlquxtZRbsgQhfS1lQBFbJKflxGAp6S3u+Ox5Hi+O16NmprjMVb3HQn1pNSgaaa0Cz1MHeTfDWhFR0WqdENbLU2PqkiRDHv0iVfl72xNPzhnGeO01kAu0 encrypted
# mfa security-profile mSecurityProfile
# mfa rsa-server security-profile rSecProfile
# mfa rsa-server host sonicrsaserver.che-lab.it port 1030 client-id sonic.che-lab.it client-key
# U2FsdGVkX18QFJoB9dp8GJN92eP79FGOZDLgQakBmAasGYX77p6PtiiAfS/nGoOb2uEocUkryc+BLLYsg+Wz0gO+c1QsIbIhXk5Pt+aECoVgoFQ9QpxO9od9cTik+3Ot encrypted
# connection-timeout 29 read-timeout 149
#
# sonic# show running-configuration | grep "cac-piv"
# aaa cac-piv cert-user user-principal-name
# aaa cac-piv cert-user-match 10digit-username
# aaa cac-piv security-profile cSecurityProfile


- name: Override device configuration of mfa with provided configuration
  dellemc.enterprise_sonic.sonic_mfa:
    config:
      cac_piv_global:
        cert_username_match: 'first-name'
    state: overridden


# After state:
# ------------
#
# sonic# show running-configuration | grep "cac-piv"
# aaa cac-piv cert-user-match first-name

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
after dictionary	The configuration resulting from module invocation. Returned: when changed
before dictionary	The configuration prior to module invocation. Returned: always
commands list / elements=string	The set of commands pushed to the remote device. Returned: always Sample: ["command 1", "command 2", "command 3"]
generated_after dictionary	The generated configuration from module invocation. Returned: when check_mode

Authors

• Divya Narendran (@Divya-N3)

Collection links

• Issue Tracker
• Repository (Sources)