Add aws_mfa_devices module for multi-factor authentication on AWS. (#1987)

lib/ansible/modules/extras/cloud/amazon/aws_mfa_devices.py

@@ -0,0 +1,135 @@
+#!/usr/bin/python
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+DOCUMENTATION = '''
+---
+module: aws_mfa_devices
+short_description: List the MFA (Multi-Factor Authentication) devices registered for a user
+description:
+    - List the MFA (Multi-Factor Authentication) devices registered for a user
+version_added: "2.2"
+author: Victor Costan (@pwnall)
+options:
+  user_name:
+    description:
+      - The name of the user whose MFA devices will be listed
+    required: false
+    default: null
+extends_documentation_fragment:
+    - aws
+    - ec2
+requirements:
+    - boto3
+    - botocore
+'''
+
+RETURN = """
+devices:
+    description: The MFA devices registered for the given user
+    returned: always
+    type: list
+    sample:
+      - enable_date: "2016-03-11T23:25:36+00:00"
+        serial_number: arn:aws:iam::085120003701:mfa/pwnall
+        user_name: pwnall
+      - enable_date: "2016-03-11T23:25:37+00:00"
+        serial_number: arn:aws:iam::085120003702:mfa/pwnall
+        user_name: pwnall
+changed:
+    description: True if listing the devices succeeds
+    type: bool
+    returned: always
+"""
+
+EXAMPLES = '''
+# Note: These examples do not set authentication details, see the AWS Guide for details.
+
+# List MFA devices (more details: http://docs.aws.amazon.com/IAM/latest/APIReference/API_ListMFADevices.html)
+aws_mfa_devices:
+register: mfa_devices
+
+# Assume an existing role (more details: http://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
+sts_assume_role:
+  mfa_serial_number: "{{ mfa_devices.devices[0].serial_number }}"
+  role_arn: "arn:aws:iam::123456789012:role/someRole"
+  role_session_name: "someRoleSession"
+register: assumed_role
+'''
+
+try:
+    import boto3
+    from botocore.exceptions import ClientError
+    HAS_BOTO3 = True
+except ImportError:
+    HAS_BOTO3 = False
+
+
+def normalize_mfa_device(mfa_device):
+    serial_number = mfa_device.get('SerialNumber', None)
+    user_name = mfa_device.get('UserName', None)
+    enable_date = mfa_device.get('EnableDate', None)
+    return {
+        'serial_number': serial_number,
+        'user_name': user_name,
+        'enable_date': enable_date
+    }
+
+def list_mfa_devices(connection, module):
+    user_name = module.params.get('user_name')
+    changed = False
+
+    args = {}
+    if user_name is not None:
+        args['UserName'] = user_name
+    try:
+        response = connection.list_mfa_devices(**args)
+        changed = True
+    except ClientError, e:
+        module.fail_json(msg=e)
+
+    mfa_devices = response.get('MFADevices', [])
+    devices = [normalize_mfa_device(mfa_device) for mfa_device in mfa_devices]
+
+    module.exit_json(changed=changed, devices=devices)
+
+def main():
+    argument_spec = ec2_argument_spec()
+    argument_spec.update(
+        dict(
+            user_name = dict(required=False, default=None)
+        )
+    )
+
+    module = AnsibleModule(argument_spec=argument_spec)
+
+    if not HAS_BOTO3:
+        module.fail_json(msg='boto3 and botocore are required.')
+
+    region, ec2_url, aws_connect_kwargs = get_aws_connection_info(module, boto3=True)
+    if region:
+        connection = boto3_conn(module, conn_type='client', resource='iam', region=region, endpoint=ec2_url, **aws_connect_kwargs)
+    else:
+        module.fail_json(msg="region must be specified")
+
+    list_mfa_devices(connection, module)
+
+
+# import module snippets
+from ansible.module_utils.basic import *
+from ansible.module_utils.ec2 import *
+
+if __name__ == '__main__':
+    main()