Merge pull request aws#1401 from awsdocs/iam-examples

New IAM examples.

awscli/examples/iam/create-policy-version.rst

@@ -0,0 +1,21 @@
+**To create a new version of a managed policy**
+
+
+This example creates a new ``v2`` version of the IAM policy whose ARN is ``arn:aws:iam::123456789012:policy/MyPolicy`` and makes it the default version::
+
+
+  aws iam create-policy-version --policy-arn arn:aws:iam::123456789012:policy/MyPolicy --policy-document file://NewPolicyVersion.json --set-as-default
+
+Output::
+
+  {
+      "PolicyVersion": {
+          "CreateDate": "2015-06-16T18:56:03.721Z",
+          "VersionId": "v2",
+          "IsDefaultVersion": true
+      }
+  }
+
+For more information, see `Versioning for Managed Policies`_ in the *Using IAM* guide.
+
+.. _`Versioning for Managed Policies`: http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_managed-versioning.html

awscli/examples/iam/create-saml-provider.rst

@@ -0,0 +1,16 @@
+**To create a SAML provider**
+
+This example creates a new SAML provider in IAM named ``MySAMLProvider``. It is described by the SAML metadata document found in the file ``SAMLMetaData.xml``::
+
+  aws iam create-saml-provider --saml-metadata-document file://SAMLMetaData.xml --name MySAMLProvider
+
+
+Output::
+
+  {
+      "SAMLProviderArn": "arn:aws:iam::123456789012:saml-provider/MySAMLProvider"
+  }
+
+For more information, see `Using SAML Providers`_ in the *Using IAM* guide.
+
+.. _`Using SAML Providers`: http://docs.aws.amazon.com/IAM/latest/UserGuide/identity-providers-saml.html

awscli/examples/iam/create-virtual-mfa-device.rst

@@ -0,0 +1,18 @@
+**To create a virtual MFA device**
+
+This example creates a new virtual MFA device called ``BobsMFADevice``. It creates a file that contains bootstrap information called ``QRCode.png`` 
+and places it in the ``C:/`` directory. The bootstrap method used in this example is ``QRCodePNG``::
+
+
+  aws iam create-virtual-mfa-device --virtual-mfa-device-name BobsMFADevice --outfile C:/QRCode.png --bootstrap-method QRCodePNG
+
+Output::
+
+  {
+      "VirtualMFADevice": {
+          "SerialNumber": "arn:aws:iam::210987654321:mfa/BobsMFADevice"
+  }
+
+For more information, see `Using Multi-Factor Authentication (MFA) Devices with AWS`_ in the *Using IAM* guide.
+
+.. _`Using Multi-Factor Authentication (MFA) Devices with AWS`: http://docs.aws.amazon.com/IAM/latest/UserGuide/Using_ManagingMFA.html

awscli/examples/iam/deactivate-mfa-device.rst

@@ -0,0 +1,10 @@
+**To deactivate an MFA device**
+
+This command deactivates the virtual MFA device with the ARN ``arn:aws:iam::210987654321:mfa/BobsMFADevice`` that is associated with the user ``Bob``::
+
+  aws iam deactivate-mfa-device --user-name Bob --serial-number arn:aws:iam::210987654321:mfa/BobsMFADevice
+
+
+For more information, see `Using Multi-Factor Authentication (MFA) Devices with AWS`_ in the *Using IAM* guide.
+
+.. _`Using Multi-Factor Authentication (MFA) Devices with AWS`: http://docs.aws.amazon.com/IAM/latest/UserGuide/Using_ManagingMFA.html

awscli/examples/iam/delete-group.rst

@@ -0,0 +1,10 @@
+**To delete an IAM group**
+
+The following ``delete-group`` command deletes an IAM group named ``MyTestGroup``::
+
+  aws iam delete-group --group-name MyTestGroup
+
+
+For more information, see `Deleting an IAM Group`_ in the *Using IAM* guide.
+
+.. _`Deleting an IAM Group`: http://docs.aws.amazon.com/IAM/latest/UserGuide/Using_DeleteGroup.html

awscli/examples/iam/delete-open-id-connect-provider.rst

@@ -0,0 +1,10 @@
+**To delete an IAM OpenID Connect identity provider**
+
+This example deletes the IAM OIDC provider that connects to the provider ``example.oidcprovider.com``::
+
+  aws aim delete-open-id-connect-provider --open-id-connect-provider-arn arn:aws:iam::123456789012:oidc-provider/example.oidcprovider.com
+
+
+For more information, see `Using OpenID Connect Identity Providers`_ in the *Using IAM* guide.
+
+.. _`Using OpenID Connect Identity Providers`: http://docs.aws.amazon.com/IAM/latest/UserGuide/Using_CreatingAndListingGroups.html

awscli/examples/iam/delete-policy-version.rst

@@ -0,0 +1,10 @@
+**To delete a version of a managed policy**
+
+This example deletes the version identified as ``v2`` from the policy whose ARN is ``arn:aws:iam::123456789012:policy/MySamplePolicy``::
+
+  aws iam delete-policy-version --policy-arn arn:aws:iam::123456789012:policy/MyPolicy --version-id v2
+
+
+For more information, see `Overview of IAM Policies`_ in the *Using IAM* guide.
+
+.. _`Overview of IAM Policies`: http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html

awscli/examples/iam/delete-policy.rst

@@ -0,0 +1,10 @@
+**To delete an IAM policy**
+
+This example deletes the policy whose ARN is ``arn:aws:iam::123456789012:policy/MySamplePolicy``::
+
+  aws iam delete-policy --policy-arn arn:aws:iam::123456789012:policy/MySamplePolicy
+
+
+For more information, see `Overview of IAM Policies`_ in the *Using IAM* guide.
+
+.. _`Overview of IAM Policies`: http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html

awscli/examples/iam/delete-saml-provider.rst

@@ -0,0 +1,10 @@
+**To delete a SAML provider**
+
+This example deletes the IAM SAML 2.0 provider whose ARN is ``arn:aws:iam::123456789012:saml-provider/SAMLADFSProvider``::
+
+  aws iam delete-saml-provider --saml-provider-arn arn:aws:iam::123456789012:saml-provider/SAMLADFSProvider
+
+
+For more information, see `Using SAML Providers`_ in the *Using IAM* guide.
+
+.. _`Using SAML Providers`: http://docs.aws.amazon.com/IAM/latest/UserGuide/identity-providers-saml.html

awscli/examples/iam/detach-group-policy.rst

@@ -0,0 +1,10 @@
+**To detach a policy from a group**
+
+This example removes the managed policy with the ARN ``arn:aws:iam::123456789012:policy/TesterAccessPolicy`` from the group called ``Testers``::
+
+  aws iam detach-group-policy --group-name Testers --policy-arn arn:aws:iam::123456789012:policy/TesterAccessPolicy
+
+
+For more information, see `Overview of IAM Policies`_ in the *Using IAM* guide.
+
+.. _`Overview of IAM Policies`: http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html

awscli/examples/iam/detach-role-policy.rst

@@ -0,0 +1,10 @@
+**To detach a policy from a role**
+
+This example removes the managed policy with the ARN ``arn:aws:iam::123456789012:policy/FederatedTesterAccessPolicy`` from the role called ``FedTesterRole``::
+
+  aws iam detach-role-policy --role-name FedTesterRole --policy-arn arn:aws:iam::123456789012:policy/FederatedTesterAccessPolicy 
+
+
+For more information, see `Overview of IAM Policies`_ in the *Using IAM* guide.
+
+.. _`Overview of IAM Policies`: http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html

awscli/examples/iam/detach-user-policy.rst

@@ -0,0 +1,10 @@
+**To detach a policy from a user**
+
+This example removes the managed policy with the ARN ``arn:aws:iam::123456789012:policy/TesterPolicy`` from the user ``Bob``::
+
+  aws iam detach-user-policy --user-name Bob --policy-arn arn:aws:iam::123456789012:policy/TesterPolicy 
+
+
+For more information, see `Overview of IAM Policies`_ in the *Using IAM* guide.
+
+.. _`Overview of IAM Policies`: http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html

awscli/examples/iam/enable-mfa-device.rst

@@ -0,0 +1,12 @@
+**To enable an MFA device**
+
+After you ran the ``create-virtual-mfa-device`` command to create a new virtual MFA device, you can then assign this MFA device to a user.
+The following example assigns the MFA device with the serial number ``arn:aws:iam::210987654321:mfa/BobsMFADevice`` to the user ``Bob``.
+The command also synchronizes the device with AWS by including the first two codes in sequence from the virtual MFA device::
+
+  aws iam enable-mfa-device --user-name Bob --serial-number arn:aws:iam::210987654321:mfa/BobsMFADevice --authentication-code-1 123456 --authentication-code-2 789012
+
+
+For more information, see `Using a Virtual MFA Device with AWS`_ in the *Using IAM* guide.
+
+.. _`Using a Virtual MFA Device with AWS`: http://docs.aws.amazon.com/IAM/latest/UserGuide/Using_VirtualMFA.html

awscli/examples/iam/generate-credential-report.rst

@@ -0,0 +1,16 @@
+**To generate a credential report**
+
+The following example attempts to generate a credential report for the AWS account::
+
+  aws iam generate-credential-report
+
+Output::
+
+  {
+      "State":  "STARTED",
+	  "Description": "No report exists. Starting a new report generation task"
+  }
+
+For more information, see `Getting Credential Reports for Your AWS Account`_ in the *Using IAM* guide.
+
+.. _`Getting Credential Reports for Your AWS Account`: http://docs.aws.amazon.com/IAM/latest/UserGuide/credential-reports.html

awscli/examples/iam/get-access-key-last-used.rst

@@ -0,0 +1,21 @@
+**To retrieve information about when the specified access key was last used**
+
+The following example retrieves information about when the access key ``ABCDEXAMPLE`` was last used:: 
+
+  aws iam get-access-key-last-used --access-key-id ABCDEXAMPLE
+
+
+Output::
+
+  {
+      "UserName":  "Bob", {
+	  "AccessKeyLastUsed": 
+		"Region": "us-east-1",
+		"ServiceName": "iam",
+		"LastUsedDate": "2015-06-16T22:45:00Z"
+		}
+  }
+
+For more information, see `Managing Access Keys for IAM Users`_ in the *Using IAM* guide.
+
+.. _`Managing Access Keys for IAM Users`: http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html

awscli/examples/iam/get-credential-report.rst

@@ -0,0 +1,16 @@
+**To get a credential report**
+
+This example opens the returned report and outputs it to the pipeline as an array of text lines::
+
+  aws iam get-credential-report
+
+Output::
+
+  {
+      "GeneratedTime":  "2015-06-17T19:11:50Z",
+	  "ReportFormat": "text/csv"
+  }
+
+For more information, see `Getting Credential Reports for Your AWS Account`_ in the *Using IAM* guide.
+
+.. _`Getting Credential Reports for Your AWS Account`: http://docs.aws.amazon.com/IAM/latest/UserGuide/credential-reports.html

awscli/examples/iam/get-group.rst

@@ -0,0 +1,22 @@
+**To get an IAM group**
+
+This example returns details about the IAM group ``Admins``::
+
+  aws iam get-group --group-name Admins
+
+Output::
+
+  {
+      "Group": {
+          "Path": "/",
+          "CreateDate": "2015-06-16T19:41:48Z",
+          "GroupId": "AIDGPMS9RO4H3FEXAMPLE",
+          "Arn": "arn:aws:iam::123456789012:group/Admins",
+          "GroupName": "Admins"
+      },
+	  "Users": []
+  }
+
+For more information, see `IAM Users and Groups`_ in the *Using IAM* guide.
+
+.. _`IAM Users and Groups`: http://docs.aws.amazon.com/IAM/latest/UserGuide/Using_WorkingWithGroupsAndUsers.html

awscli/examples/iam/get-open-id-connect-provider.rst

@@ -0,0 +1,22 @@
+**To return information about the specified OpenID Connect provider**
+
+This example returns details about the OpenID Connect provider whose ARN is ``arn:aws:iam::123456789012:oidc-provider/server.example.com``::
+
+  aws iam get-open-id-connect-provider --open-id-connect-provider-arn arn:aws:iam::123456789012:oidc-provider/server.example.com
+
+Output::
+
+  {
+      "Url": "server.example.com"
+          "CreateDate": "2015-06-16T19:41:48Z",
+          "ThumbprintList": [
+			"12345abcdefghijk67890lmnopqrst987example"
+		  ],
+          "ClientIDList": [
+			"example-application-ID"
+		  ]
+  }
+
+For more information, see `Using OpenID Connect Identity Providers`_ in the *Using IAM* guide.
+
+.. _`Using OpenID Connect Identity Providers`: http://docs.aws.amazon.com/IAM/latest/UserGuide/identity-providers-oidc.html

awscli/examples/iam/get-policy-version.rst

@@ -0,0 +1,30 @@
+**To retrieve information about the specified version of the specified managed policy**
+
+This example returns the policy document for the v2 version of the policy whose ARN is ``arn:aws:iam::123456789012:policy/MyManagedPolicy``::
+
+  aws iam get-policy-version --policy-arn arn:aws:iam::123456789012:policy/MyPolicy --version-id v2
+
+
+Output::
+
+  {
+      "PolicyVersion": {
+          "CreateDate": "2015-06-17T19:23;32Z",
+          "VersionId": "v2",
+          "Document": {
+			"Version": "2012-10-17",
+			"Statement": [
+				{
+					"Action": "iam:*",
+					"Resource": "*",
+					"Effect": "Allow"
+				}
+			]
+		  }
+          "IsDefaultVersion": "false"
+      }
+  }
+
+For more information, see `Overview of IAM Policies`_ in the *Using IAM* guide.
+
+.. _`Overview of IAM Policies`: http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html

awscli/examples/iam/get-policy.rst

@@ -0,0 +1,25 @@
+**To retrieve information about the specified managed policy**
+
+This example returns details about the managed policy whose ARN is ``arn:aws:iam::123456789012:policy/MySamplePolicy``::
+
+  aws iam get-policy --policy-arn arn:aws:iam::123456789012:policy/MySamplePolicy
+
+Output::
+
+  {
+      "Policy": {
+          "PolicyName": "MySamplePolicy",
+          "CreateDate": "2015-06-17T19:23;32Z",
+          "AttachmentCount": "0",
+          "IsAttachable": "true",
+		  "PolicyId": "Z27SI6FQMGNQ2EXAMPLE1",
+          "DefaultVersionId": "v1",
+		  "Path": "/",
+		  "Arn": "arn:aws:iam::123456789012:policy/MySamplePolicy",
+		  "UpdateDate": "2015-06-17T19:23:32Z"
+      }
+  }
+
+For more information, see `Overview of IAM Policies`_ in the *Using IAM* guide.
+
+.. _`Overview of IAM Policies`: http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html

awscli/examples/iam/get-saml-provider.rst

@@ -0,0 +1,12 @@
+**To retrieve the SAML provider metadocument**
+
+This example retrieves the details about the SAML 2.0 provider whose ARM is ``arn:aws:iam::123456789012:saml-provider/SAMLADFS``. 
+The response includes the metadata document that you got from the identity provider to create the AWS SAML provider entity as well 
+as the creation and expiration dates::
+
+  aws iam get-saml-provider --saml-provider-arn arn:aws:iam::123456789012:saml-provider/SAMLADFS 
+
+
+For more information, see `Using SAML Providers`_ in the *Using IAM* guide.
+
+.. _`Using SAML Providers`: http://docs.aws.amazon.com/IAM/latest/UserGuide/identity-providers-saml.html

awscli/examples/iam/list-attached-group-policies.rst

@@ -0,0 +1,25 @@
+**To list all managed policies that are attached to the specified group**
+
+This example returns the names and ARNs of the managed policies that are attached to the IAM group named ``Admins`` in the AWS account::
+
+  aws iam list-attached-group-policies --group-name Admins
+
+Output::
+
+  {
+    "AttachedPolicies": [
+      {
+        "PolicyName": "AdministratorAccess",
+        "PolicyArn": "arn:aws:iam::aws:policy/AdministratorAccess"
+      },
+      {
+        "PolicyName": "SecurityAudit",
+        "PolicyArn": "arn:aws:iam::aws:policy/SecurityAudit"
+      }
+    ],
+    "IsTruncated": false
+  }
+
+For more information, see `Overview of IAM Policies`_ in the *Using IAM* guide.
+
+.. _`Overview of IAM Policies`: http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html