Added AWS SAML Federation Module (#55821)

* Added AWS SAML Federation Module

* iam_saml_federation: (integration tests) initial integration tests
This commit is contained in:
Tony 2019-09-11 18:00:05 +01:00 committed by Jill R
parent a999f07010
commit 2064fc3fc5
7 changed files with 387 additions and 0 deletions

View file

@ -406,6 +406,8 @@ groupings:
- aws
iam_server_certificate_facts:
- aws
iam_saml_federation:
- aws
iam_server_certificate_info:
- aws
iam_user:

View file

@ -0,0 +1,249 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# 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/>.
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = '''
---
module: iam_saml_federation
version_added: "2.10"
short_description: Maintain IAM SAML federation configuration.
requirements:
- boto3
description:
- Provides a mechanism to manage AWS IAM SAML Identity Federation providers (create/update/delete metadata).
options:
name:
description:
- The name of the provider to create.
required: true
type: str
saml_metadata_document:
description:
- The XML document generated by an identity provider (IdP) that supports SAML 2.0.
type: str
state:
description:
- Whether to create or delete identity provider. If 'present' is specified it will attempt to update the identity provider matching the name field.
default: present
choices: [ "present", "absent" ]
type: str
extends_documentation_fragment:
- aws
- ec2
author:
- Tony (@axc450)
- Aidan Rowe (@aidan-)
'''
EXAMPLES = '''
# Note: These examples do not set authentication details, see the AWS Guide for details.
# It is assumed that their matching environment variables are set.
# Creates a new iam saml identity provider if not present
- name: saml provider
iam_saml_federation:
name: example1
# the > below opens an indented block, so no escaping/quoting is needed when in the indentation level under this key
saml_metadata_document: >
<?xml version="1.0"?>...
<md:EntityDescriptor
# Creates a new iam saml identity provider if not present
- name: saml provider
iam_saml_federation:
name: example2
saml_metadata_document: "{{ item }}"
with_file: /path/to/idp/metdata.xml
# Removes iam saml identity provider
- name: remove saml provider
iam_saml_federation:
name: example3
state: absent
'''
RETURN = '''
saml_provider:
description: Details of the SAML Identity Provider that was created/modified.
type: complex
returned: present
contains:
arn:
description: The ARN of the identity provider.
type: str
returned: present
sample: "arn:aws:iam::123456789012:saml-provider/my_saml_provider"
metadata_document:
description: The XML metadata document that includes information about an identity provider.
type: str
returned: present
create_date:
description: The date and time when the SAML provider was created in ISO 8601 date-time format.
type: str
returned: present
sample: "2017-02-08T04:36:28+00:00"
expire_date:
description: The expiration date and time for the SAML provider in ISO 8601 date-time format.
type: str
returned: present
sample: "2017-02-08T04:36:28+00:00"
'''
try:
import botocore.exceptions
except ImportError:
pass
from ansible.module_utils.aws.core import AnsibleAWSModule
from ansible.module_utils.ec2 import AWSRetry
class SAMLProviderManager:
"""Handles SAML Identity Provider configuration"""
def __init__(self, module):
self.module = module
try:
self.conn = module.client('iam')
except botocore.exceptions.ClientError as e:
self.module.fail_json_aws(e, msg="Unknown boto error")
# use retry decorator for boto3 calls
@AWSRetry.backoff(tries=3, delay=5)
def _list_saml_providers(self):
return self.conn.list_saml_providers()
@AWSRetry.backoff(tries=3, delay=5)
def _get_saml_provider(self, arn):
return self.conn.get_saml_provider(SAMLProviderArn=arn)
@AWSRetry.backoff(tries=3, delay=5)
def _update_saml_provider(self, arn, metadata):
return self.conn.update_saml_provider(SAMLProviderArn=arn, SAMLMetadataDocument=metadata)
@AWSRetry.backoff(tries=3, delay=5)
def _create_saml_provider(self, metadata, name):
return self.conn.create_saml_provider(SAMLMetadataDocument=metadata, Name=name)
@AWSRetry.backoff(tries=3, delay=5)
def _delete_saml_provider(self, arn):
return self.conn.delete_saml_provider(SAMLProviderArn=arn)
def _get_provider_arn(self, name):
providers = self._list_saml_providers()
for p in providers['SAMLProviderList']:
provider_name = p['Arn'].split('/', 1)[1]
if name == provider_name:
return p['Arn']
return None
def create_or_update_saml_provider(self, name, metadata):
if not metadata:
self.module.fail_json(msg="saml_metadata_document must be defined for present state")
res = {'changed': False}
try:
arn = self._get_provider_arn(name)
except (botocore.exceptions.ValidationError, botocore.exceptions.ClientError) as e:
self.module.fail_json_aws(e, msg="Could not get the ARN of the identity provider '{0}'".format(name))
if arn: # see if metadata needs updating
try:
resp = self._get_saml_provider(arn)
except (botocore.exceptions.ValidationError, botocore.exceptions.ClientError) as e:
self.module.fail_json_aws(e, msg="Could not retrieve the identity provider '{0}'".format(name))
if metadata.strip() != resp['SAMLMetadataDocument'].strip():
# provider needs updating
res['changed'] = True
if not self.module.check_mode:
try:
resp = self._update_saml_provider(arn, metadata)
res['saml_provider'] = self._build_res(resp['SAMLProviderArn'])
except botocore.exceptions.ClientError as e:
self.module.fail_json_aws(e, msg="Could not update the identity provider '{0}'".format(name))
else: # create
res['changed'] = True
if not self.module.check_mode:
try:
resp = self._create_saml_provider(metadata, name)
res['saml_provider'] = self._build_res(resp['SAMLProviderArn'])
except botocore.exceptions.ClientError as e:
self.module.fail_json_aws(e, msg="Could not create the identity provider '{0}'".format(name))
self.module.exit_json(**res)
def delete_saml_provider(self, name):
res = {'changed': False}
try:
arn = self._get_provider_arn(name)
except (botocore.exceptions.ValidationError, botocore.exceptions.ClientError) as e:
self.module.fail_json_aws(e, msg="Could not get the ARN of the identity provider '{0}'".format(name))
if arn: # delete
res['changed'] = True
if not self.module.check_mode:
try:
self._delete_saml_provider(arn)
except botocore.exceptions.ClientError as e:
self.module.fail_json_aws(e, msg="Could not delete the identity provider '{0}'".format(name))
self.module.exit_json(**res)
def _build_res(self, arn):
saml_provider = self._get_saml_provider(arn)
return {
"arn": arn,
"metadata_document": saml_provider["SAMLMetadataDocument"],
"create_date": saml_provider["CreateDate"].isoformat(),
"expire_date": saml_provider["ValidUntil"].isoformat()
}
def main():
argument_spec = dict(
name=dict(required=True),
saml_metadata_document=dict(default=None, required=False),
state=dict(default='present', required=False, choices=['present', 'absent']),
)
module = AnsibleAWSModule(
argument_spec=argument_spec,
supports_check_mode=True,
required_if=[('state', 'present', ['saml_metadata_document'])]
)
name = module.params['name']
state = module.params.get('state')
saml_metadata_document = module.params.get('saml_metadata_document')
sp_man = SAMLProviderManager(module)
if state == 'present':
sp_man.create_or_update_saml_provider(name, saml_metadata_document)
elif state == 'absent':
sp_man.delete_saml_provider(name)
if __name__ == '__main__':
main()

View file

@ -0,0 +1,2 @@
cloud/aws
unsupported

View file

@ -0,0 +1,22 @@
<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2019-08-24T20:37:21Z" cacheDuration="PT1567111041S" entityID="AnsibleSAMLTest1">
<md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>MIIDJjCCAg4CCQCiwst2XYH7fTANBgkqhkiG9w0BAQsFADBVMQswCQYDVQQGEwJYWDEVMBMGA1UEBwwMRGVmYXVsdCBDaXR5MRwwGgYDVQQKDBNEZWZhdWx0IENvbXBhbnkgTHRkMREwDwYDVQQDDAhleGFtcGxlMTAeFw0xOTA4MjIyMDM2NTFaFw0yMDA4MjEyMDM2NTFaMFUxCzAJBgNVBAYTAlhYMRUwEwYDVQQHDAxEZWZhdWx0IENpdHkxHDAaBgNVBAoME0RlZmF1bHQgQ29tcGFueSBMdGQxETAPBgNVBAMMCGV4YW1wbGUxMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArLbBVE6E28bfvB/gUGjOmY2lxxxLZ9Fls4fOH9js/MhGG+hh4diyj/Kb7Coo6HehXMp93TXkYYbiKGAoykT6ULEACZnYi1V9XdUs619ibumi9pRSFygBrbyN+n9peMJxf4jvM1QS/DTPWxdkgeMkqb2SARJChd3azCHd0cdGwcsx1pTkYp34SL0gP79m6W8N3TIxyJmqi0Kc7mntPQUCVH/wFSyg59JXo8SUQDQNap/yd9UwLzxP9MhH8G3DBatwQj3ijYOPnAeUPbsw7GYiKQBh/SIH5DGzW4TNHo0PiQJqzymNp0mI0eKjRO98vfnsXkeQwotzeKVbkmJ63h3PHQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBvm+zYchto1NESDxCVDK96QKObklWrfiAgKDLb49Loox+pyWTvs2mu5DOgDe0rrgEDfxngbbupo9eSu5w7OPVfip8W9rsB8k6ak+P4G8MltqkYv5A0aXbka1da1NenbIXAC3/YbMjLnsidDWQiKYZ0i0HxjuhguW3lvOFd3Dzp2rNDydzA6ilSmBXFrAcKm0RHAfP4NGy3ECdU6SQ5OBSUcJprKADMODIykuds1qh0Gz8a0ukKKmp2yJvz9bIuC4+TRXKKZtgDZKPcN0MgtqYZJ2rttoFqkCWrNBCZSUgJEASUJ78NSC3Wy8WQr3NjZvQ86KG2/mcVQ3Lm1ci82Uue</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:KeyDescriptor use="encryption">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>MIIDJjCCAg4CCQCiwst2XYH7fTANBgkqhkiG9w0BAQsFADBVMQswCQYDVQQGEwJYWDEVMBMGA1UEBwwMRGVmYXVsdCBDaXR5MRwwGgYDVQQKDBNEZWZhdWx0IENvbXBhbnkgTHRkMREwDwYDVQQDDAhleGFtcGxlMTAeFw0xOTA4MjIyMDM2NTFaFw0yMDA4MjEyMDM2NTFaMFUxCzAJBgNVBAYTAlhYMRUwEwYDVQQHDAxEZWZhdWx0IENpdHkxHDAaBgNVBAoME0RlZmF1bHQgQ29tcGFueSBMdGQxETAPBgNVBAMMCGV4YW1wbGUxMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArLbBVE6E28bfvB/gUGjOmY2lxxxLZ9Fls4fOH9js/MhGG+hh4diyj/Kb7Coo6HehXMp93TXkYYbiKGAoykT6ULEACZnYi1V9XdUs619ibumi9pRSFygBrbyN+n9peMJxf4jvM1QS/DTPWxdkgeMkqb2SARJChd3azCHd0cdGwcsx1pTkYp34SL0gP79m6W8N3TIxyJmqi0Kc7mntPQUCVH/wFSyg59JXo8SUQDQNap/yd9UwLzxP9MhH8G3DBatwQj3ijYOPnAeUPbsw7GYiKQBh/SIH5DGzW4TNHo0PiQJqzymNp0mI0eKjRO98vfnsXkeQwotzeKVbkmJ63h3PHQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBvm+zYchto1NESDxCVDK96QKObklWrfiAgKDLb49Loox+pyWTvs2mu5DOgDe0rrgEDfxngbbupo9eSu5w7OPVfip8W9rsB8k6ak+P4G8MltqkYv5A0aXbka1da1NenbIXAC3/YbMjLnsidDWQiKYZ0i0HxjuhguW3lvOFd3Dzp2rNDydzA6ilSmBXFrAcKm0RHAfP4NGy3ECdU6SQ5OBSUcJprKADMODIykuds1qh0Gz8a0ukKKmp2yJvz9bIuC4+TRXKKZtgDZKPcN0MgtqYZJ2rttoFqkCWrNBCZSUgJEASUJ78NSC3Wy8WQr3NjZvQ86KG2/mcVQ3Lm1ci82Uue</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://example.com/saml/logout"/>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://example.com/saml/"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>

View file

@ -0,0 +1,22 @@
<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2019-08-24T20:38:34Z" cacheDuration="PT1567111114S" entityID="AnsibleSAMLTest2">
<md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>MIIDADCCAegCCQCgxBiDM2muazANBgkqhkiG9w0BAQsFADBCMQswCQYDVQQGEwJYWDEVMBMGA1UEBwwMRGVmYXVsdCBDaXR5MRwwGgYDVQQKDBNEZWZhdWx0IENvbXBhbnkgTHRkMB4XDTE5MDgyMjIwMzY1OFoXDTIwMDgyMTIwMzY1OFowQjELMAkGA1UEBhMCWFgxFTATBgNVBAcMDERlZmF1bHQgQ2l0eTEcMBoGA1UECgwTRGVmYXVsdCBDb21wYW55IEx0ZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMUJ3J1tzqoAgQwaJHx/MGl5yVTNpJLPfx8YCS0Z+RQWXIazZrssy/tpZcfgnek4+xvqrzRXR4nell31VTojIGItqR70lPhrsPES70SrN8egi+MLTZ4iddG5hjK4bn4wss88/3johi8/J85wc26/bkRz66lOvTaJ8k1pncQ3NekT9zZzWlW1LQk3uMbaPrVVocjFBEZyTsYUE9wZG+ggRBJlOMGEdhGsgPuR8Aj7OXO7X8/RolV8lB3GTzellX2GxiWnOhjnabSPBUUv5iVKcDOb2lIqxr5DScIvX1PcJSUCAGGLcd8wYK/lh3k+PFH9QNDLY6F5WHkoZq9LS46+8lkCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAWjX7E/BYAHaOKOXc5RAD9zwAaMxLMTSK5Cnq32TGIh1P4ap8jTNVaiCs9UJXHJpKwXUN+3DdVBIGMT17DzFwAeruZOzNBN0VJVl0yZ6dARgss4gpOBGvBD8blLidnVxEd5VRGldx5R5+I441ms6ASkohcHhGlF4WGbnabEZ/MtxhDIWUX2w4naOfFg6vOiPsE1C/ZXJeLDNP+dnjfueTN5DD38d+ND2mHweB7u0Qjpkd2K0TuCp0z4kXRuTgPzlfkPORNkgyU1hA3YClpT57aeUsHgO23sr/4d04jzI+hYeleGqjNM+3vDQYsOQyXx61/nANeF0Sp9ZIv3eJSTMXNw==</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:KeyDescriptor use="encryption">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>MIIDADCCAegCCQCgxBiDM2muazANBgkqhkiG9w0BAQsFADBCMQswCQYDVQQGEwJYWDEVMBMGA1UEBwwMRGVmYXVsdCBDaXR5MRwwGgYDVQQKDBNEZWZhdWx0IENvbXBhbnkgTHRkMB4XDTE5MDgyMjIwMzY1OFoXDTIwMDgyMTIwMzY1OFowQjELMAkGA1UEBhMCWFgxFTATBgNVBAcMDERlZmF1bHQgQ2l0eTEcMBoGA1UECgwTRGVmYXVsdCBDb21wYW55IEx0ZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMUJ3J1tzqoAgQwaJHx/MGl5yVTNpJLPfx8YCS0Z+RQWXIazZrssy/tpZcfgnek4+xvqrzRXR4nell31VTojIGItqR70lPhrsPES70SrN8egi+MLTZ4iddG5hjK4bn4wss88/3johi8/J85wc26/bkRz66lOvTaJ8k1pncQ3NekT9zZzWlW1LQk3uMbaPrVVocjFBEZyTsYUE9wZG+ggRBJlOMGEdhGsgPuR8Aj7OXO7X8/RolV8lB3GTzellX2GxiWnOhjnabSPBUUv5iVKcDOb2lIqxr5DScIvX1PcJSUCAGGLcd8wYK/lh3k+PFH9QNDLY6F5WHkoZq9LS46+8lkCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAWjX7E/BYAHaOKOXc5RAD9zwAaMxLMTSK5Cnq32TGIh1P4ap8jTNVaiCs9UJXHJpKwXUN+3DdVBIGMT17DzFwAeruZOzNBN0VJVl0yZ6dARgss4gpOBGvBD8blLidnVxEd5VRGldx5R5+I441ms6ASkohcHhGlF4WGbnabEZ/MtxhDIWUX2w4naOfFg6vOiPsE1C/ZXJeLDNP+dnjfueTN5DD38d+ND2mHweB7u0Qjpkd2K0TuCp0z4kXRuTgPzlfkPORNkgyU1hA3YClpT57aeUsHgO23sr/4d04jzI+hYeleGqjNM+3vDQYsOQyXx61/nANeF0Sp9ZIv3eJSTMXNw==</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://example.com/saml/logout"/>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://example.com/saml/"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>

View file

@ -0,0 +1,3 @@
dependencies:
- prepare_tests
- setup_ec2

View file

@ -0,0 +1,87 @@
- module_defaults:
group/aws:
region: "{{ aws_region }}"
aws_access_key: "{{ aws_access_key }}"
aws_secret_key: "{{ aws_secret_key }}"
security_token: "{{ security_token | default(omit) }}"
block:
# ============================================================
# TESTS
- name: Create the identity provider
iam_saml_federation:
name: '{{ resource_prefix }}-saml'
state: present
saml_metadata_document: '{{ lookup("file", "example1.xml") }}'
register: create_result
- name: assert idp created
assert:
that:
- create_result is changed
- name: Test that nothing changes when we retry
iam_saml_federation:
name: '{{ resource_prefix }}-saml'
state: present
saml_metadata_document: '{{ lookup("file", "example1.xml") }}'
register: create_result
- name: assert the idp doesn't change when we retry
assert:
that:
- create_result is not changed
- name: Change the identity provider
iam_saml_federation:
name: '{{ resource_prefix }}-saml'
state: present
saml_metadata_document: '{{ lookup("file", "example2.xml") }}'
register: change_result
- name: assert idp created
assert:
that:
- change_result is changed
- name: Test that nothing changes when we retry
iam_saml_federation:
name: '{{ resource_prefix }}-saml'
state: present
saml_metadata_document: '{{ lookup("file", "example2.xml") }}'
register: change_result
- name: assert the idp doesn't change when we retry
assert:
that:
- change_result is not changed
- name: Delete the identity provider
iam_saml_federation:
name: '{{ resource_prefix }}-saml'
state: absent
register: destroy_result
- name: assert deleted
assert:
that:
- destroy_result is changed
- name: Attempt to re-delete the identity provider
iam_saml_federation:
name: '{{ resource_prefix }}-saml'
state: absent
register: destroy_result
- name: assert deleted
assert:
that:
- destroy_result is not changed
always:
# ============================================================
# CLEAN-UP
- name: finish off by deleting the identity provider
iam_saml_federation:
name: '{{ resource_prefix }}-saml'
state: absent
register: destroy_result