From f8ffd8fb655ec0182a88cfef5ef79a0565193f80 Mon Sep 17 00:00:00 2001 From: ford-at-aws Date: Tue, 13 Feb 2024 16:10:06 -0500 Subject: [PATCH] READMES --- ruby/example_code/cloudtrail/README.md | 8 +- ruby/example_code/iam/README.md | 86 ++++------- ruby/example_code/iam/manage_access_keys.rb | 10 ++ .../iam/{add_user.rb => manage_users.rb} | 146 +++++++++++++----- ruby/example_code/sns/README.md | 2 +- 5 files changed, 157 insertions(+), 95 deletions(-) rename ruby/example_code/iam/{add_user.rb => manage_users.rb} (64%) diff --git a/ruby/example_code/cloudtrail/README.md b/ruby/example_code/cloudtrail/README.md index 0e63bc2f96b..c56645c2829 100644 --- a/ruby/example_code/cloudtrail/README.md +++ b/ruby/example_code/cloudtrail/README.md @@ -33,10 +33,10 @@ For prerequisites, see the [README](../../README.md#Prerequisites) in the `ruby` Code excerpts that show you how to call individual service functions. -- [Delete trail](delete_trail.rb) -- [List trail events](lookup_events.rb) -- [List trails](describe_trails.rb) -- [List trails](create_trail.rb) +- [Create trails](create_trail.rb#L8) (`CreateTrail`) +- [Delete trail](delete_trail.rb#L9) (`DeleteTrail`) +- [List trail events](lookup_events.rb#L8) (`LookupEvents`) +- [List trails](describe_trails.rb#L6) (`ListTrails`) diff --git a/ruby/example_code/iam/README.md b/ruby/example_code/iam/README.md index 7e9fb24386b..60572935deb 100644 --- a/ruby/example_code/iam/README.md +++ b/ruby/example_code/iam/README.md @@ -33,37 +33,40 @@ For prerequisites, see the [README](../../README.md#Prerequisites) in the `ruby` Code excerpts that show you how to call individual service functions. -- [Attach a policy to a role](scenario_iam_basics.rb#L100) (`AttachRolePolicy`) -- [Create a policy](scenario_iam_basics.rb#L99) (`CreatePolicy`) -- [Create a role](scenario_iam_basics.rb#L72) (`CreateRole`) -- [Create a service-linked role](iam_wrapper.rb#L166) (`CreateServiceLinkedRole`) -- [Create a user](scenario_iam_basics.rb#L37) (`CreateUser`) -- [Create an access key](scenario_iam_basics.rb#L55) (`CreateAccessKey`) -- [Create an inline policy for a user](scenario_iam_basics.rb#L130) (`PutUserPolicy`) -- [Delete a policy](scenario_iam_basics.rb#L215) (`DeletePolicy`) -- [Delete a role](scenario_iam_basics.rb#L215) (`DeleteRole`) -- [Delete a service-linked role](iam_wrapper.rb#L186) (`DeleteServiceLinkedRole`) -- [Delete a user](scenario_iam_basics.rb#L237) (`DeleteUser`) -- [Delete an access key](scenario_iam_basics.rb#L237) (`DeleteAccessKey`) -- [Delete an inline policy from a user](scenario_iam_basics.rb#L237) (`DeleteUserPolicy`) -- [Detach a policy from a role](scenario_iam_basics.rb#L215) (`DetachRolePolicy`) -- [Get a policy](iam_wrapper.rb#L101) (`GetPolicy`) -- [Get a role](iam_wrapper.rb#L49) (`GetRole`) -- [Get the account password policy](iam_wrapper.rb#L133) (`GetAccountPasswordPolicy`) -- [List SAML providers](iam_wrapper.rb#L151) (`ListSAMLProviders`) -- [List a user's access keys](scenario_iam_basics.rb#L237) (`ListAccessKeys`) -- [List groups](iam_wrapper.rb#L118) (`ListGroups`) -- [List policies](iam_wrapper.rb#L81) (`ListPolicies`) -- [List policies attached to a role](scenario_iam_basics.rb#L215) (`ListAttachedRolePolicies`) -- [List roles](iam_wrapper.rb#L29) (`ListRoles`) -- [List users](iam_wrapper.rb#L66) (`ListUsers`) - -### Scenarios - -Code examples that show you how to accomplish a specific task by calling multiple -functions within the same service. - -- [Create a user and assume a role](scenario_iam_basics.rb) +- [Attach a policy to a role](attach_role_policy.rb#L6) (`AttachRolePolicy`) +- [Attach a policy to a user](attach_user_policy.rb#L38) (`AttachUserPolicy`) +- [Create a policy](attach_role_policy.rb#L6) (`CreatePolicy`) +- [Create a role](manage_roles.rb#L61) (`CreateRole`) +- [Create a service-linked role](manage_roles.rb#L89) (`CreateServiceLinkedRole`) +- [Create a user](manage_users.rb#L18) (`CreateUser`) +- [Create an access key](manage_access_keys.rb#L6) (`CreateAccessKey`) +- [Create an alias for an account](manage_account_aliases.rb#L6) (`CreateAccountAlias`) +- [Create an inline policy for a user](attach_user_policy.rb#L17) (`PutUserPolicy`) +- [Delete a role](manage_roles.rb#L109) (`DeleteRole`) +- [Delete a server certificate](manage_server_certificates.rb#L6) (`DeleteServerCertificate`) +- [Delete a service-linked role](manage_roles.rb#L138) (`DeleteServiceLinkedRole`) +- [Delete a user](manage_users.rb#L134) (`DeleteUser`) +- [Delete an access key](manage_access_keys.rb#L6) (`DeleteAccessKey`) +- [Delete an account alias](manage_account_aliases.rb#L6) (`DeleteAccountAlias`) +- [Delete an inline policy from a user](manage_users.rb#L134) (`DeleteUserPolicy`) +- [Detach a policy from a role](attach_role_policy.rb#L6) (`DetachRolePolicy`) +- [Detach a policy from a user](attach_user_policy.rb#L56) (`DetachUserPolicy`) +- [Get a policy](attach_role_policy.rb#L34) (`GetPolicy`) +- [Get a role](manage_roles.rb#L44) (`GetRole`) +- [Get a user](manage_users.rb#L43) (`GetUser`) +- [Get the account password policy](get_account_password_policy.rb#L1) (`GetAccountPasswordPolicy`) +- [List SAML providers](list_saml_providers.rb#L7) (`ListSAMLProviders`) +- [List a user's access keys](manage_access_keys.rb#L6) (`ListAccessKeys`) +- [List account aliases](manage_account_aliases.rb#L6) (`ListAccountAliases`) +- [List groups](list_groups.rb#L6) (`ListGroups`) +- [List inline policies for a role](attach_role_policy.rb#L68) (`ListRolePolicies`) +- [List policies](attach_role_policy.rb#L6) (`ListPolicies`) +- [List policies attached to a role](attach_role_policy.rb#L6) (`ListAttachedRolePolicies`) +- [List roles](manage_roles.rb#L18) (`ListRoles`) +- [List server certificates](manage_server_certificates.rb#L6) (`ListServerCertificates`) +- [List users](manage_users.rb#L60) (`ListUsers`) +- [Update a server certificate](manage_server_certificates.rb#L6) (`UpdateServerCertificate`) +- [Update a user](manage_users.rb#L78) (`UpdateUser`) @@ -80,27 +83,6 @@ The quickest way to interact with this example code is to invoke a [Scenario](#S -#### Create a user and assume a role - -This example shows you how to create a user and assume a role. - -- Create a user with no permissions. -- Create a role that grants permission to list Amazon S3 buckets for the account. -- Add a policy to let the user assume the role. -- Assume the role and list S3 buckets using temporary credentials, then clean up resources. - - - - -Start the example by running the following at a command prompt: - -``` -ruby scenario_create_user_assume_role.rb -``` - - - - ### Tests ⚠ Running tests might result in charges to your AWS account. diff --git a/ruby/example_code/iam/manage_access_keys.rb b/ruby/example_code/iam/manage_access_keys.rb index ce0e6dad4a8..1f4e4282bbe 100644 --- a/ruby/example_code/iam/manage_access_keys.rb +++ b/ruby/example_code/iam/manage_access_keys.rb @@ -13,6 +13,8 @@ def initialize(iam_client) end # Lists access keys for a user + # + # @param user_name [String] The name of the user. def list_access_keys(user_name) response = @iam.list_access_keys(user_name: user_name) if response.access_key_metadata.empty? @@ -29,6 +31,8 @@ def list_access_keys(user_name) end # Creates an access key for a user + # + # @param user_name [String] The name of the user. def create_access_key(user_name) response = @iam.create_access_key(user_name: user_name) access_key = response.access_key @@ -43,6 +47,9 @@ def create_access_key(user_name) end # Deactivates an access key + # + # @param user_name [String] The name of the user. + # @param access_key_id [String] The ID for the access key. def deactivate_access_key(user_name, access_key_id) @iam.update_access_key( user_name: user_name, @@ -56,6 +63,9 @@ def deactivate_access_key(user_name, access_key_id) end # Deletes an access key + # + # @param user_name [String] The name of the user. + # @param access_key_id [String] The ID for the access key. def delete_access_key(user_name, access_key_id) @iam.delete_access_key( user_name: user_name, diff --git a/ruby/example_code/iam/add_user.rb b/ruby/example_code/iam/manage_users.rb similarity index 64% rename from ruby/example_code/iam/add_user.rb rename to ruby/example_code/iam/manage_users.rb index 6c9bfca8138..dd7d7975aa7 100644 --- a/ruby/example_code/iam/add_user.rb +++ b/ruby/example_code/iam/manage_users.rb @@ -40,6 +40,41 @@ def create_user(user_name, initial_password) end # snippet-end:[ruby.iam.CreateUser] + # snippet-start:[ruby.iam.GetUser] + # Retrieves a user's details + # + # @param user_name [String] The name of the user to retrieve + # @return [Aws::IAM::Types::User, nil] The user object if found, or nil if an error occurred + def get_user(user_name) + response = @iam_client.get_user(user_name: user_name) + response.user + rescue Aws::IAM::Errors::NoSuchEntity + @logger.error("User '#{user_name}' not found.") + nil + rescue Aws::IAM::Errors::ServiceError => e + @logger.error("Error retrieving user '#{user_name}': #{e.message}") + nil + end + # snippet-end:[ruby.iam.GetUser] + + # snippet-start:[ruby.iam.ListUsers] + # Lists all users in the AWS account + # + # @return [Array] An array of user objects + def list_users + users = [] + @iam_client.list_users.each_page do |page| + page.users.each do |user| + users << user + end + end + users + rescue Aws::IAM::Errors::ServiceError => e + @logger.error("Error listing users: #{e.message}") + [] + end + # snippet-end:[ruby.iam.ListUsers] + # snippet-start:[ruby.iam.UpdateUser] # Updates an IAM user's name # @@ -54,6 +89,48 @@ def update_user_name(current_name, new_name) end # snippet-end:[ruby.iam.UpdateUser] + # List groups associated with a user + # + # @param user_name [String] The name of the user + def display_groups(user_name) + @logger.info("Listing groups for user: #{user_name}") + puts "Groups:" + groups_response = @iam_client.list_groups_for_user(user_name: user_name) + if groups_response.groups.empty? + puts " None" + else + groups_response.groups.each { |group| puts " #{group.group_name}" } + end + end + + # Lists policies attached to a user + # + # @param user_name [String] The name of the user + def display_policies(user_name) + @logger.info("Listing policies for user: #{user_name}") + puts "Inline embedded user policies:" + policies_response = @iam_client.list_user_policies(user_name: user_name) + if policies_response.policy_names.empty? + puts " None" + else + policies_response.policy_names.each { |policy_name| puts " #{policy_name}" } + end + end + + # Lists access keys associated with a user + # + # @param user_name [String] The name of the user + def display_access_keys(user_name) + @logger.info("Listing access keys for user: #{user_name}") + puts "Access keys:" + access_keys_response = @iam_client.list_access_keys(user_name: user_name) + if access_keys_response.access_key_metadata.empty? + puts " None" + else + access_keys_response.access_key_metadata.each { |access_key| puts " #{access_key.access_key_id}" } + end + end + # snippet-start:[ruby.iam.DeleteUser] # Deletes a user and their associated resources # @@ -73,40 +150,39 @@ def delete_user(user_name) # snippet-end:[ruby.iam.DeleteUser] - # snippet-start:[ruby.iam.GetUser] - # Retrieves a user's details - # - # @param user_name [String] The name of the user to retrieve - # @return [Aws::IAM::Types::User, nil] The user object if found, or nil if an error occurred - def get_user(user_name) - response = @iam_client.get_user(user_name: user_name) - response.user - rescue Aws::IAM::Errors::NoSuchEntity - @logger.error("User '#{user_name}' not found.") - nil - rescue Aws::IAM::Errors::ServiceError => e - @logger.error("Error retrieving user '#{user_name}': #{e.message}") - nil - end - # snippet-end:[ruby.iam.GetUser] + # This is a example module that displays information about available users in + # AWS Identity and Access Management (IAM). This includes user names, associated + # group names, inline embedded user policy names, and access key IDs. Logging is + # added for monitoring purposes. + def get_user_details + @logger.info("Requesting list of users") + users_response = list_users + if users_response.users.empty? + @logger.warn("No users found.") + puts "No users found." + return + end - # snippet-start:[ruby.iam.ListUsers] - # Lists all users in the AWS account - # - # @return [Array] An array of user objects - def list_users - users = [] - @iam_client.list_users.each_page do |page| - page.users.each do |user| - users << user - end + message = if users_response.is_truncated + "(Note: not all users are displayed here, only the first #{users_response.users.count}.)" + else + "Found #{users_response.users.count} user(s):" + end + @logger.info(message) + puts message + + users_response.users.each do |user| + @logger.info("Displaying details for user: #{user.user_name}") + puts "-" * 30 + puts "User name: #{user.user_name}" + display_groups(user.user_name) + display_policies(user.user_name) + display_access_keys(user.user_name) end - users - rescue Aws::IAM::Errors::ServiceError => e - @logger.error("Error listing users: #{e.message}") - [] + rescue StandardError => e + @logger.error("Error getting user details: #{e.message}") + puts "Error getting user details: #{e.message}" end - # snippet-end:[ruby.iam.ListUsers] end # snippet-end:[ruby.iam.ManageUsers] @@ -133,13 +209,7 @@ def list_users end # List all IAM users - users = user_manager.list_users - if users.any? - logger.info("Listing all users:") - users.each { |u| logger.info("User: #{u.user_name}") } - else - logger.error("No users found.") - end + user_manager.get_user_details # Delete the created user if user_manager.delete_user(user_name) diff --git a/ruby/example_code/sns/README.md b/ruby/example_code/sns/README.md index 773311bbaf0..6596e411433 100644 --- a/ruby/example_code/sns/README.md +++ b/ruby/example_code/sns/README.md @@ -34,7 +34,7 @@ For prerequisites, see the [README](../../README.md#Prerequisites) in the `ruby` Code excerpts that show you how to call individual service functions. - [Create a topic](create_topic.rb#L3) (`CreateTopic`) -- [List the subscribers of a topic](None) (`ListSubscriptions`) +- [List the subscribers of a topic](show_subscriptions.rb#L4) (`ListSubscriptions`) - [List topics](show_topics.rb#L11) (`ListTopics`) - [Publish to a topic](send_message.rb#L4) (`Publish`) - [Set topic attributes](enable_resource.rb#L4) (`SetTopicAttributes`)