2018/12/07 - AWS Identity and Access Management - 4 new api methods
Changes We are making it easier for you to manage your AWS Identity and Access Management (IAM) policy permissions by enabling you to retrieve the last timestamp when an IAM entity (e.g., user, role, or a group) accessed an AWS service. This feature also allows you to audit service access for your entities.
Generates a request for a report that includes details about when an IAM resource (user, group, role, or policy) was last used in an attempt to access AWS services. Recent activity usually appears within four hours. IAM reports activity for the last 365 days, or less if your region began supporting this feature within the last year. For more information, see Regions Where Data Is Tracked .
Warning
The service last accessed data includes all attempts to access an AWS API, not just the successful ones. This includes all attempts that were made using the AWS Management Console, the AWS API through any of the SDKs, or any of the command line tools. An unexpected entry in the service last accessed data does not mean that your account has been compromised, because the request might have been denied. Refer to your CloudTrail logs as the authoritative source for information about all API calls and whether they were successful or denied access. For more information, see Logging IAM Events with CloudTrail in the IAM User Guide .
The GenerateServiceLastAccessedDetails operation returns a JobId . Use this parameter in the following operations to retrieve the following details from your report:
GetServiceLastAccessedDetails – Use this operation for users, groups, roles, or policies to list every AWS service that the resource could access using permissions policies. For each service, the response includes information about the most recent access attempt.
GetServiceLastAccessedDetailsWithEntities – Use this operation for groups and policies to list information about the associated entities (users or roles) that attempted to access a specific AWS service.
To check the status of the GenerateServiceLastAccessedDetails request, use the JobId parameter in the same operations and test the JobStatus response parameter.
For additional information about the permissions policies that allow an identity (user, group, or role) to access specific services, use the ListPoliciesGrantingServiceAccess operation.
Note
Service last accessed data does not use other policy types when determining whether a resource could access a service. These other policy types include resource-based policies, access control lists, AWS Organizations policies, IAM permissions boundaries, and AWS STS assume role policies. It only applies permissions policy logic. For more about the evaluation of policy types, see Evaluating Policies in the IAM User Guide .
For more information about service last accessed data, see Reducing Policy Scope by Viewing User Activity in the IAM User Guide .
See also: AWS API Documentation
Request Syntax
client.generate_service_last_accessed_details(
Arn='string'
)
string
[REQUIRED]
The ARN of the IAM resource (user, group, role, or managed policy) used to generate information about when the resource was last used in an attempt to access an AWS service.
dict
Response Syntax
{
'JobId': 'string'
}
Response Structure
(dict) --
JobId (string) --
The job ID that you can use in the GetServiceLastAccessedDetails or GetServiceLastAccessedDetailsWithEntities operations.
After you generate a group or policy report using the GenerateServiceLastAccessedDetails operation, you can use the JobId parameter in GetServiceLastAccessedDetailsWithEntities . This operation retrieves the status of your report job and a list of entities that could have used group or policy permissions to access the specified service.
Group – For a group report, this operation returns a list of users in the group that could have used the group’s policies in an attempt to access the service.
Policy – For a policy report, this operation returns a list of entities (users or roles) that could have used the policy in an attempt to access the service.
You can also use this operation for user or role reports to retrieve details about those entities.
If the operation fails, the GetServiceLastAccessedDetailsWithEntities operation returns the reason that it failed.
By default, the list of associated entities is sorted by date, with the most recent access listed first.
See also: AWS API Documentation
Request Syntax
client.get_service_last_accessed_details_with_entities(
JobId='string',
ServiceNamespace='string',
MaxItems=123,
Marker='string'
)
string
[REQUIRED]
The ID of the request generated by the GenerateServiceLastAccessedDetails operation.
string
[REQUIRED]
The service namespace for an AWS service. Provide the service namespace to learn when the IAM entity last attempted to access the specified service.
To learn the service namespace for a service, go to Actions, Resources, and Condition Keys for AWS Services in the IAM User Guide and choose the name of the service to view details for that service. In the first paragraph, find the service prefix. For example, (service prefix: a4b) . For more information about service namespaces, see AWS Service Namespaces in the AWS General Reference .
integer
Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true .
If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true , and Marker contains a value to include in the subsequent call that tells the service where to continue from.
string
Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.
dict
Response Syntax
{
'JobStatus': 'IN_PROGRESS'|'COMPLETED'|'FAILED',
'JobCreationDate': datetime(2015, 1, 1),
'JobCompletionDate': datetime(2015, 1, 1),
'EntityDetailsList': [
{
'EntityInfo': {
'Arn': 'string',
'Name': 'string',
'Type': 'USER'|'ROLE'|'GROUP',
'Id': 'string',
'Path': 'string'
},
'LastAuthenticated': datetime(2015, 1, 1)
},
],
'IsTruncated': True|False,
'Marker': 'string',
'Error': {
'Message': 'string',
'Code': 'string'
}
}
Response Structure
(dict) --
JobStatus (string) --
The status of the job.
JobCreationDate (datetime) --
The date and time, in ISO 8601 date-time format , when the report job was created.
JobCompletionDate (datetime) --
The date and time, in ISO 8601 date-time format , when the generated report job was completed or failed.
EntityDetailsList (list) --
An EntityDetailsList object that contains details about when an IAM entity (user or role) used group or policy permissions in an attempt to access the specified AWS service.
(dict) --
An object that contains details about when the IAM entities (users or roles) were last used in an attempt to access the specified AWS service.
This data type is a response element in the GetServiceLastAccessedDetailsWithEntities operation.
EntityInfo (dict) --
The EntityInfo object that contains details about the entity (user or role).
Arn (string) --
The Amazon Resource Name (ARN). ARNs are unique identifiers for AWS resources.
For more information about ARNs, go to Amazon Resource Names (ARNs) and AWS Service Namespaces in the AWS General Reference .
Name (string) --
The name of the entity (user or role).
Type (string) --
The type of entity (user or role).
Id (string) --
The identifier of the entity (user or role).
Path (string) --
The path to the entity (user or role). For more information about paths, see IAM Identifiers in the Using IAM guide.
LastAuthenticated (datetime) --
The date and time, in ISO 8601 date-time format , when the authenticated entity last attempted to access AWS. AWS does not report unauthenticated requests.
This field is null if no IAM entities attempted to access the service within the reporting period .
IsTruncated (boolean) --
A flag that indicates whether there are more items to return. If your results were truncated, you can make a subsequent pagination request using the Marker request parameter to retrieve more items. Note that IAM might return fewer than the MaxItems number of results even when there are more results available. We recommend that you check IsTruncated after every call to ensure that you receive all your results.
Marker (string) --
When IsTruncated is true , this element is present and contains the value to use for the Marker parameter in a subsequent pagination request.
Error (dict) --
An object that contains details about the reason the operation failed.
Message (string) --
Detailed information about the reason that the operation failed.
Code (string) --
The error code associated with the operation failure.
After you generate a user, group, role, or policy report using the GenerateServiceLastAccessedDetails operation, you can use the JobId parameter in GetServiceLastAccessedDetails . This operation retrieves the status of your report job and a list of AWS services that the resource (user, group, role, or managed policy) can access.
Note
Service last accessed data does not use other policy types when determining whether a resource could access a service. These other policy types include resource-based policies, access control lists, AWS Organizations policies, IAM permissions boundaries, and AWS STS assume role policies. It only applies permissions policy logic. For more about the evaluation of policy types, see Evaluating Policies in the IAM User Guide .
For each service that the resource could access using permissions policies, the operation returns details about the most recent access attempt. If there was no attempt, the service is listed without details about the most recent attempt to access the service. If the operation fails, the GetServiceLastAccessedDetails operation returns the reason that it failed.
The GetServiceLastAccessedDetails operation returns a list of services that includes the number of entities that have attempted to access the service and the date and time of the last attempt. It also returns the ARN of the following entity, depending on the resource ARN that you used to generate the report:
User – Returns the user ARN that you used to generate the report
Group – Returns the ARN of the group member (user) that last attempted to access the service
Role – Returns the role ARN that you used to generate the report
Policy – Returns the ARN of the user or role that last used the policy to attempt to access the service
By default, the list is sorted by service namespace.
See also: AWS API Documentation
Request Syntax
client.get_service_last_accessed_details(
JobId='string',
MaxItems=123,
Marker='string'
)
string
[REQUIRED]
The ID of the request generated by the GenerateServiceLastAccessedDetails operation.
integer
Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true .
If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true , and Marker contains a value to include in the subsequent call that tells the service where to continue from.
string
Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.
dict
Response Syntax
{
'JobStatus': 'IN_PROGRESS'|'COMPLETED'|'FAILED',
'JobCreationDate': datetime(2015, 1, 1),
'ServicesLastAccessed': [
{
'ServiceName': 'string',
'LastAuthenticated': datetime(2015, 1, 1),
'ServiceNamespace': 'string',
'LastAuthenticatedEntity': 'string',
'TotalAuthenticatedEntities': 123
},
],
'JobCompletionDate': datetime(2015, 1, 1),
'IsTruncated': True|False,
'Marker': 'string',
'Error': {
'Message': 'string',
'Code': 'string'
}
}
Response Structure
(dict) --
JobStatus (string) --
The status of the job.
JobCreationDate (datetime) --
The date and time, in ISO 8601 date-time format , when the report job was created.
ServicesLastAccessed (list) --
A ServiceLastAccessed object that contains details about the most recent attempt to access the service.
(dict) --
Contains details about the most recent attempt to access the service.
This data type is used as a response element in the GetServiceLastAccessedDetails operation.
ServiceName (string) --
The name of the service in which access was attempted.
LastAuthenticated (datetime) --
The date and time, in ISO 8601 date-time format , when an authenticated entity most recently attempted to access the service. AWS does not report unauthenticated requests.
This field is null if no IAM entities attempted to access the service within the reporting period .
ServiceNamespace (string) --
The namespace of the service in which access was attempted.
To learn the service namespace of a service, go to Actions, Resources, and Condition Keys for AWS Services in the IAM User Guide . Choose the name of the service to view details for that service. In the first paragraph, find the service prefix. For example, (service prefix: a4b) . For more information about service namespaces, see AWS Service Namespaces in the AWS General Reference .
LastAuthenticatedEntity (string) --
The ARN of the authenticated entity (user or role) that last attempted to access the service. AWS does not report unauthenticated requests.
This field is null if no IAM entities attempted to access the service within the reporting period .
TotalAuthenticatedEntities (integer) --
The total number of authenticated entities that have attempted to access the service.
This field is null if no IAM entities attempted to access the service within the reporting period .
JobCompletionDate (datetime) --
The date and time, in ISO 8601 date-time format , when the generated report job was completed or failed.
This field is null if the job is still in progress, as indicated by a JobStatus value of IN_PROGRESS .
IsTruncated (boolean) --
A flag that indicates whether there are more items to return. If your results were truncated, you can make a subsequent pagination request using the Marker request parameter to retrieve more items. Note that IAM might return fewer than the MaxItems number of results even when there are more results available. We recommend that you check IsTruncated after every call to ensure that you receive all your results.
Marker (string) --
When IsTruncated is true , this element is present and contains the value to use for the Marker parameter in a subsequent pagination request.
Error (dict) --
An object that contains details about the reason the operation failed.
Message (string) --
Detailed information about the reason that the operation failed.
Code (string) --
The error code associated with the operation failure.
Retrieves a list of policies that the IAM identity (user, group, or role) can use to access each specified service.
Note
This operation does not use other policy types when determining whether a resource could access a service. These other policy types include resource-based policies, access control lists, AWS Organizations policies, IAM permissions boundaries, and AWS STS assume role policies. It only applies permissions policy logic. For more about the evaluation of policy types, see Evaluating Policies in the IAM User Guide .
The list of policies returned by the operation depends on the ARN of the identity that you provide.
User – The list of policies includes the managed and inline policies that are attached to the user directly. The list also includes any additional managed and inline policies that are attached to the group to which the user belongs.
Group – The list of policies includes only the managed and inline policies that are attached to the group directly. Policies that are attached to the group’s user are not included.
Role – The list of policies includes only the managed and inline policies that are attached to the role.
For each managed policy, this operation returns the ARN and policy name. For each inline policy, it returns the policy name and the entity to which it is attached. Inline policies do not have an ARN. For more information about these policy types, see Managed Policies and Inline Policies in the IAM User Guide .
Policies that are attached to users and roles as permissions boundaries are not returned. To view which managed policy is currently used to set the permissions boundary for a user or role, use the GetUser or GetRole operations.
See also: AWS API Documentation
Request Syntax
client.list_policies_granting_service_access(
Marker='string',
Arn='string',
ServiceNamespaces=[
'string',
]
)
string
Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.
string
[REQUIRED]
The ARN of the IAM identity (user, group, or role) whose policies you want to list.
list
[REQUIRED]
The service namespace for the AWS services whose policies you want to list.
To learn the service namespace for a service, go to Actions, Resources, and Condition Keys for AWS Services in the IAM User Guide . Choose the name of the service to view details for that service. In the first paragraph, find the service prefix. For example, (service prefix: a4b) . For more information about service namespaces, see AWS Service Namespaces in the AWS General Reference .
(string) --
dict
Response Syntax
{
'PoliciesGrantingServiceAccess': [
{
'ServiceNamespace': 'string',
'Policies': [
{
'PolicyName': 'string',
'PolicyType': 'INLINE'|'MANAGED',
'PolicyArn': 'string',
'EntityType': 'USER'|'ROLE'|'GROUP',
'EntityName': 'string'
},
]
},
],
'IsTruncated': True|False,
'Marker': 'string'
}
Response Structure
(dict) --
PoliciesGrantingServiceAccess (list) --
A ListPoliciesGrantingServiceAccess object that contains details about the permissions policies attached to the specified identity (user, group, or role).
(dict) --
Contains details about the permissions policies that are attached to the specified identity (user, group, or role).
This data type is used as a response element in the ListPoliciesGrantingServiceAccess operation.
ServiceNamespace (string) --
The namespace of the service that was accessed.
To learn the service namespace of a service, go to Actions, Resources, and Condition Keys for AWS Services in the IAM User Guide . Choose the name of the service to view details for that service. In the first paragraph, find the service prefix. For example, (service prefix: a4b) . For more information about service namespaces, see AWS Service Namespaces in the AWS General Reference .
Policies (list) --
The PoliciesGrantingServiceAccess object that contains details about the policy.
(dict) --
Contains details about the permissions policies that are attached to the specified identity (user, group, or role).
This data type is an element of the ListPoliciesGrantingServiceAccessEntry object.
PolicyName (string) --
The policy name.
PolicyType (string) --
The policy type. For more information about these policy types, see Managed Policies and Inline Policies in the IAM User Guide .
PolicyArn (string) --
The Amazon Resource Name (ARN). ARNs are unique identifiers for AWS resources.
For more information about ARNs, go to Amazon Resource Names (ARNs) and AWS Service Namespaces in the AWS General Reference .
EntityType (string) --
The type of entity (user or role) that used the policy to access the service to which the inline policy is attached.
This field is null for managed policies. For more information about these policy types, see Managed Policies and Inline Policies in the IAM User Guide .
EntityName (string) --
The name of the entity (user or role) to which the inline policy is attached.
This field is null for managed policies. For more information about these policy types, see Managed Policies and Inline Policies in the IAM User Guide .
IsTruncated (boolean) --
A flag that indicates whether there are more items to return. If your results were truncated, you can make a subsequent pagination request using the Marker request parameter to retrieve more items. We recommend that you check IsTruncated after every call to ensure that you receive all your results.
Marker (string) --
When IsTruncated is true , this element is present and contains the value to use for the Marker parameter in a subsequent pagination request.