describe how to assume an iam role within aws organizations [BCD-194] (#59)

* describe how to assume an iam role within aws organizations [BCD-194]

* add notes about roles creation

md/aws_organizations.md

+# Assume IAM role within AWS Organizations
+
+[AWS Organizations](https://aws.amazon.com/organizations) offers policy-based management for multiple AWS accounts.
+If you use an Organization with IAM users (for SSO, see [Single Sign-On to AWS Using G Suite](aws_sso.md)), you will have to assume a specific role on the target account. To do so you will still put your `aws_access_key_id` and `aws_secret_access_key` into the `.boto` or `.aws/credentials` file.
+Then you will just have to modify the scenario in order to set the corresponding role arn, for example :
+
+```
+aws_assumed_iam_role: arn:aws:iam::123456789012:role/BCD
+```
+
+Note:
+- `123456789012` represents here the target account
+- `BCD` represents here the role on this account
+
+It implies that you should have created the corresponding role with proper rights. To do so you just have to follow the [How to configure Amazon Web Services (AWS) for BCD](aws_prerequisites.md) and in `AWS Setup for BCD` section replace the point 5 `Create an IAM Group` by a [creation of the corresponding role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) attached to the IAM Policies created previously.

md/aws_prerequisites.md

@@ -91,6 +91,9 @@ Further configuration instructions for **AWS single sign-on** can be found [on t
 1. [Create an IAM Group](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups_create.html)
     - **Group name**: bonita-provisioning
     - Select the IAM Policies created previously
+
+    *For some usage you may be interested to create a role and attach to it the corresponding policies, see [Configure AWS single sign-on](aws_sso.md) or [Assume IAM role within AWS Organizations](aws_organizations.md).*
+
 1. Create an IAM Policy to allow ec2 instances of a cluster to autodiscover themselves on a specific region (eg. us-west-2).
     - **Policy name**: ClusterBCD_us-west-2
     - **Policy document**:

md/aws_sso.md

@@ -18,7 +18,8 @@ Single Sign-On to AWS Using G Suite <!--{.h2}-->
 
 In this step we will provide you an example using G Suite from Google.
 
-First, set up a Single Sign-On to AWS using G Suite as described in [AWS website](https://aws.amazon.com/es/blogs/security/how-to-set-up-federated-single-sign-on-to-aws-using-google-apps/).
+First, set up a Single Sign-On to AWS using G Suite as described in [AWS website](https://aws.amazon.com/es/blogs/security/how-to-set-up-federated-single-sign-on-to-aws-using-google-apps/).  
+In this previous documentation you have seen how to create an IAM role in your AWS account. It implies that for BCD usage you should have created the corresponding role with proper rights. To do so you just have to follow the [How to configure Amazon Web Services (AWS) for BCD](aws_prerequisites.md) and in `AWS Setup for BCD` section replace the point 5 `Create an IAM Group` by a [creation of the corresponding role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp.html) attached to the IAM Policies created previously.
 
 The BCD Controller already embeds [aws-google-auth](https://github.com/cevoaustralia/aws-google-auth) to manage the authentication.
 

md/scenarios.md

@@ -42,6 +42,8 @@ The following variables are specific to AWS deployments ie. when `bcd_provider`
 | aws_database_instance_type      | Y         | -       | EC2 instance type for the database instance.                                                                                                                                                                                                                                                                                                                      | t2.micro                  |
 | aws_bonita_instance_type        | Y         | -       | EC2 instance type for the Bonita instances.                                                                                                                                                                                                                                                                                                                       | t2.micro                  |
 | aws_load_balancer_instance_type | Y         | -       | EC2 instance type for the load balancer instance.                                                                                                                                                                                                                                                                                                                 | t2.micro                  |
+| aws_assumed_iam_role            | N         | -       |An IAM role can be assumed, so all requests are run as that role. This can be useful for connecting across different accounts, or to limit user access. Set this parameter if you want to assume an IAM role while deploying on AWS. It is useful in an AWS organization with IAM users and multiple AWS accounts. See [AWS Organizations](aws_organizations.md)   |arn:aws:iam::123456789012:role/BCD|
+
 
 
 ## Bonita variables

md/taxonomy.md

@@ -8,6 +8,7 @@
     * [Manage Bonita stacks](_manage_stack.md)
         * [Configure Amazon Web Services (AWS) for BCD](aws_prerequisites.md)
         * [Configure AWS single sign-on](aws_sso.md)
+        * [Assume IAM role within AWS Organizations](aws_organizations.md)
         * [Customize the Bonita container](_custom_init.md)
             * [Using initialization scripts](custom_init.md)
             * [Configuring REST API authorization](how_to_configure_rest_api_authorization.md)