# Identity and access management for Amazon Detective
AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be *authenticated* (signed in) and *authorized* (have permissions) to use Detective resources. IAM is an AWS service that you can use with no additional charge.
**Topics**
+ [Audience](#security_iam_audience)
+ [Authenticating With Identities](#security_iam_authentication)
+ [Managing Access Using Policies](#security_iam_access-manage)
+ [How Amazon Detective works with IAM](security_iam_service-with-iam.md)
+ [Amazon Detective identity-based policy examples](security_iam_id-based-policy-examples.md)
+ [AWS managed policies for Amazon Detective](security-iam-awsmanpol.md)
+ [Using service-linked roles for Detective](using-service-linked-roles.md)
+ [Troubleshooting Amazon Detective identity and access](security_iam_troubleshoot.md)
## Audience
How you use AWS Identity and Access Management (IAM) differs based on your role:
+ **Service user** - request permissions from your administrator if you cannot access features (see [Troubleshooting Amazon Detective identity and access](security_iam_troubleshoot.md))
+ **Service administrator** - determine user access and submit permission requests (see [How Amazon Detective works with IAM](security_iam_service-with-iam.md))
+ **IAM administrator** - write policies to manage access (see [Amazon Detective identity-based policy examples](security_iam_id-based-policy-examples.md))
## Authenticating With Identities
Authentication is how you sign in to AWS using your identity credentials. You must be authenticated as the AWS account root user, an IAM user, or by assuming an IAM role.
You can sign in as a federated identity using credentials from an identity source like AWS IAM Identity Center (IAM Identity Center), single sign-on authentication, or Google/Facebook credentials. For more information about signing in, see [How to sign in to your AWS account](https://docs.aws.amazon.com/signin/latest/userguide/how-to-sign-in.html) in the *AWS Sign-In User Guide*.
For programmatic access, AWS provides an SDK and CLI to cryptographically sign requests. For more information, see [AWS Signature Version 4 for API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) in the *IAM User Guide*.
### AWS account root user
When you create an AWS account, you begin with one sign-in identity called the AWS account *root user* that has complete access to all AWS services and resources. We strongly recommend that you don't use the root user for everyday tasks. For tasks that require root user credentials, see [Tasks that require root user credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks) in the *IAM User Guide*.
### IAM Users and Groups
An *[IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)* is an identity with specific permissions for a single person or application. We recommend using temporary credentials instead of IAM users with long-term credentials. For more information, see [Require human users to use federation with an identity provider to access AWS using temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) in the *IAM User Guide*.
An [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) specifies a collection of IAM users and makes permissions easier to manage for large sets of users. For more information, see [Use cases for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/gs-identities-iam-users.html) in the *IAM User Guide*.
### IAM Roles
An *[IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)* is an identity with specific permissions that provides temporary credentials. You can assume a role by [switching from a user to an IAM role (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html) or by calling an AWS CLI or AWS API operation. For more information, see [Methods to assume a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) in the *IAM User Guide*.
IAM roles are useful for federated user access, temporary IAM user permissions, cross-account access, cross-service access, and applications running on Amazon EC2. For more information, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*.
## Managing Access Using Policies
You control access in AWS by creating policies and attaching them to AWS identities or resources. A policy defines permissions when associated with an identity or resource. AWS evaluates these policies when a principal makes a request. Most policies are stored in AWS as JSON documents. For more information about JSON policy documents, see [Overview of JSON policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json) in the *IAM User Guide*.
Using policies, administrators specify who has access to what by defining which **principal** can perform **actions** on what **resources**, and under what **conditions**.
By default, users and roles have no permissions. An IAM administrator creates IAM policies and adds them to roles, which users can then assume. IAM policies define permissions regardless of the method used to perform the operation.
### Identity-Based Policies
Identity-based policies are JSON permissions policy documents that you attach to an identity (user, group, or role). These policies control what actions identities can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.
Identity-based policies can be *inline policies* (embedded directly into a single identity) or *managed policies* (standalone policies attached to multiple identities). To learn how to choose between managed and inline policies, see [Choose between managed policies and inline policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-choosing-managed-or-inline.html) in the *IAM User Guide*.
### Resource-Based Policies
Resource-based policies are JSON policy documents that you attach to a resource. Examples include IAM *role trust policies* and Amazon S3 *bucket policies*. In services that support resource-based policies, service administrators can use them to control access to a specific resource. You must [specify a principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in a resource-based policy.
Resource-based policies are inline policies that are located in that service. You can't use AWS managed policies from IAM in a resource-based policy.
### Access Control Lists (ACLs)
Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format.
Amazon S3, AWS WAF, and Amazon VPC are examples of services that support ACLs. To learn more about ACLs, see [Access control list (ACL) overview](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html) in the *Amazon Simple Storage Service Developer Guide*.
### Other Policy Types
AWS supports additional policy types that can set the maximum permissions granted by more common policy types:
+ **Permissions boundaries** – Set the maximum permissions that an identity-based policy can grant to an IAM entity. For more information, see [Permissions boundaries for IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *IAM User Guide*.
+ **Service control policies (SCPs)** – Specify the maximum permissions for an organization or organizational unit in AWS Organizations. For more information, see [Service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*.
+ **Resource control policies (RCPs)** – Set the maximum available permissions for resources in your accounts. For more information, see [Resource control policies (RCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html) in the *AWS Organizations User Guide*.
+ **Session policies** – Advanced policies passed as a parameter when creating a temporary session for a role or federated user. For more information, see [Session policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) in the *IAM User Guide*.
### Multiple Policy Types
When multiple types of policies apply to a request, the resulting permissions are more complicated to understand. To learn how AWS determines whether to allow a request when multiple policy types are involved, see [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*.
# How Amazon Detective works with IAM
By default, users and roles don't have permission to create or modify Amazon Detective resources. They also can't perform tasks using the AWS Management Console, AWS CLI, or AWS API. A Detective administrator must have AWS Identity and Access Management (IAM) policies that grant IAM users and roles permission to perform specific API operations on the specified resources they need. The administrator must then attach those policies to the principal that require those permissions.
Detective uses IAM identity-based policies to grant permissions for the following types of users and actions:
+ **Administrator accounts** – The administrator account is the owner of a behavior graph, which uses data from their account. Administrator accounts can invite member accounts to contribute their data to the behavior graph. The administrator account can also use the behavior graph for triage and investigation of findings and resources associated with those accounts.
You can set up policies to allow users other than the administrator account to perform different types of tasks. For example, a user from an administrator account might only have permissions to manage member accounts. Another user might only have permissions to use the behavior graph for investigation.
+ **Member accounts** – A member account is an account that is invited to contribute data to a behavior graph. A member account responds to an invitation. After accepting an invitation, a member account can remove their account from the behavior graph.
To get a high-level view of how Detective and other AWS services work with IAM, see [Creating policies on the JSON tab](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html#access_policies_create-json-editor) in the *IAM User Guide*.
## Detective identity-based policies
With IAM identity-based policies, you can specify allowed or denied actions and resources, as well as the conditions under which actions are allowed or denied. Detective supports specific actions, resources, and condition keys.
To learn about all of the elements that you use in a JSON policy, see [IAM JSON Policy Elements Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the *IAM User Guide*.
### Actions
Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.
The `Action` element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Include actions in a policy to grant permissions to perform the associated operation.
Policy statements must include either an `Action` element or a `NotAction` element. The `Action` element lists the actions allowed by the policy. The `NotAction` element lists the actions that are not allowed.
The actions defined for Detective reflect tasks that you can perform using Detective. Policy actions in Detective have the following prefix: `detective:`.
For example, to grant permission to use the `CreateMembers` API operation to invite member accounts to a behavior graph, you include the `detective:CreateMembers` action in their policy.
To specify multiple actions in a single statement, separate them with commas. For example, for a member account, the policy includes the set of actions related to managing an invitation:
```
"Action": [
"detective:ListInvitations",
"detective:AcceptInvitation",
"detective:RejectInvitation",
"detective:DisassociateMembership
]
```
You can also use wildcards (\$1) to specify multiple actions. For example, to manage the data used in their behavior graph, administrator accounts in Detective must be able to perform the following tasks:
+ View their list of member accounts (`ListMembers`).
+ Get information about selected member accounts (`GetMembers`).
+ Invite member accounts to their behavior graph (`CreateMembers`).
+ Remove members from their behavior graph (`DeleteMembers`).
Instead of listing these actions separately, you can grant access to all actions that end with the word `Members`. The policy for that could include the following action:
```
"Action": "detective:*Members"
```
To see a list of Detective actions, see [Actions defined by Amazon Detective](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazondetective.html#amazondetective-actions-as-permissions) in the *Service Authorization Reference*.
### Resources
Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.
The `Resource` JSON policy element specifies the object or objects to which the action applies. As a best practice, specify a resource using its [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html). For actions that don't support resource-level permissions, use a wildcard (\$1) to indicate that the statement applies to all resources.
```
"Resource": "*"
```
For more information about the format of ARNs, see [Amazon Resource Names (ARNs) and AWS Service Namespaces](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
For Detective, the only resource type is the behavior graph. The behavior graph resource in Detective has the following ARN:
```
arn:aws:detective:${Region}:${AccountId}:graph:${GraphId}
```
For example, a behavior graph has the following values:
+ The Region for the behavior graph is `us-east-1`.
+ The account ID for the administrator account ID is `111122223333`.
+ The graph ID of the behavior graph is `027c7c4610ea4aacaf0b883093cab899`.
To identify this behavior graph in a `Resource` statement, you would use the following ARN:
```
"Resource": "arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899"
```
To specify multiple resources in a `Resource` statement, use commas to separate them.
```
"Resource": [
"resource1",
"resource2"
]
```
For example, the same AWS account may be invited to be a member account in more than one behavior graph. In the policy for that member account, the `Resource` statement would list the behavior graphs they were invited to.
```
"Resource": [
"arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899",
"arn:aws:detective:us-east-1:444455556666:graph:056d2a9521xi2bbluw1d164680eby416"
]
```
Some Detective actions, such as creating a behavior graph, listing behavior graphs, and listing behavior graph invitations, are not performed on a specific behavior graph. For those actions, the `Resource` statement must use the wildcard (\$1).
```
"Resource": "*"
```
For administrator account actions, Detective always verifies that the user making the request belongs to the administrator account for the affected behavior graph. For member account actions, Detective always verifies that the user making the request belongs to the member account. Even if an IAM policy grants access to a behavior graph, if the user does not belong to the correct account, the user cannot perform the action.
For all actions that are performed on a specific behavior graph, the IAM policy should include the graph ARN. The graph ARN can be added later. For example, when an account first enables Detective, the initial IAM policy provides access to all Detective actions, using the wildcard for the graph ARN. This allows the user to immediately start to manage member accounts for and conduct investigations in their behavior graph. After the behavior graph is created, you can update the policy to add the graph ARN.
### Condition keys
Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.
The `Condition` element specifies when statements execute based on defined criteria. You can create conditional expressions that use [condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html), such as equals or less than, to match the condition in the policy with values in the request. To see all AWS global condition keys, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*.
Detective does not define its own set of condition keys. It does support using global condition keys. To see all AWS global condition keys, see [AWS Global Condition Context Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*.
To learn which actions and resources allow you to use a condition key, see [Actions defined by Amazon Detective](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazondetective.html#amazondetective-actions-as-permissions).
### Examples
To view examples of Detective identity-based policies, see [Amazon Detective identity-based policy examples](security_iam_id-based-policy-examples.md).
## Detective resource-based policies (Not supported)
Detective does not support resource-based policies.
## Authorization based on Detective behavior graph tags
Each behavior graph can be assigned tag values. You can use those tag values in condition statements to manage access to the behavior graph.
The condition statement for a tag value uses the following format.
```
{"StringEquals"{"aws:ResourceTag/": ""}}
```
For example, use the following code to allow or deny an action when the value of the `Department` tag is `Finance`.
```
{"StringEquals"{"aws:ResourceTag/Department": "Finance"}}
```
For examples of policies that use resource tag values, see [Administrator account: Restricting access based on tag values](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-graph-tags).
## Detective IAM Roles
An [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) is an entity within your AWS account that has specific permissions.
### Using temporary credentials with Detective
You can use temporary credentials to sign in with federation, assume an IAM role, or to assume a cross-account role. You obtain temporary security credentials by calling AWS STS API operations such as [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) or [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html).
Detective supports using temporary credentials.
### Service-linked roles
[Service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role) allow AWS services to access resources in other services to complete an action on your behalf. Service-linked roles appear in your IAM account and are owned by the service. An IAM administrator can view but not edit the permissions for service-linked roles.
For details about creating or managing Detective service-linked roles, see [Using service-linked roles for Detective](using-service-linked-roles.md).
### Service roles (Not supported)
This feature allows a service to assume a [service role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-role) on your behalf. This role allows the service to access resources in other services to complete an action on your behalf. Service roles appear in your IAM account and are owned by the account. This means that an IAM administrator can change the permissions for this role. However, doing so might break the functionality of the service.
Detective does not support service roles.
# Amazon Detective identity-based policy examples
By default, IAM users and roles don't have permission to create or modify Detective resources. They also can't perform tasks using the AWS Management Console, AWS CLI, or AWS API.
An IAM administrator must create IAM policies that grant users and roles permission to perform specific API operations on the specified resources they need. The administrator then attaches those policies to the IAM users or groups that require those permissions.
To learn how to create an IAM identity-based policy using these example JSON policy documents, see [Creating Policies on the JSON Tab](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-json-editor) in the *IAM User Guide*.
**Topics**
+ [Policy best practices](#security_iam_service-with-iam-policy-best-practices)
+ [Using the Detective console](#security_iam_id-based-policy-examples-console)
+ [Allowing users to view their own permissions](#security_iam_id-based-policy-examples-view-own-permissions)
+ [Administrator account: Managing the member accounts in a behavior graph](#security_iam_id-based-policy-examples-admin-account-mgmt)
+ [Administrator account: Using a behavior graph for investigation](#security_iam_id-based-policy-examples-admin-investigate)
+ [Member account: Managing behavior graph invitations and memberships](#security_iam_id-based-policy-examples-member-account)
+ [Administrator account: Restricting access based on tag values](#security_iam_id-based-policy-examples-graph-tags)
## Policy best practices
Identity-based policies determine whether someone can create, access, or delete Detective resources in your account. These actions can incur costs for your AWS account. When you create or edit identity-based policies, follow these guidelines and recommendations:
+ **Get started with AWS managed policies and move toward least-privilege permissions** – To get started granting permissions to your users and workloads, use the *AWS managed policies* that grant permissions for many common use cases. They are available in your AWS account. We recommend that you reduce permissions further by defining AWS customer managed policies that are specific to your use cases. For more information, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) or [AWS managed policies for job functions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html) in the *IAM User Guide*.
+ **Apply least-privilege permissions** – When you set permissions with IAM policies, grant only the permissions required to perform a task. You do this by defining the actions that can be taken on specific resources under specific conditions, also known as *least-privilege permissions*. For more information about using IAM to apply permissions, see [ Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*.
+ **Use conditions in IAM policies to further restrict access** – You can add a condition to your policies to limit access to actions and resources. For example, you can write a policy condition to specify that all requests must be sent using SSL. You can also use conditions to grant access to service actions if they are used through a specific AWS service, such as CloudFormation. For more information, see [ IAM JSON policy elements: Condition](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) in the *IAM User Guide*.
+ **Use IAM Access Analyzer to validate your IAM policies to ensure secure and functional permissions** – IAM Access Analyzer validates new and existing policies so that the policies adhere to the IAM policy language (JSON) and IAM best practices. IAM Access Analyzer provides more than 100 policy checks and actionable recommendations to help you author secure and functional policies. For more information, see [Validate policies with IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-policy-validation.html) in the *IAM User Guide*.
+ **Require multi-factor authentication (MFA)** – If you have a scenario that requires IAM users or a root user in your AWS account, turn on MFA for additional security. To require MFA when API operations are called, add MFA conditions to your policies. For more information, see [ Secure API access with MFA](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_configure-api-require.html) in the *IAM User Guide*.
For more information about best practices in IAM, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
## Using the Detective console
To use the Amazon Detective console, the user or role must have access to the relevant actions, which match corresponding actions in the API.
To enable Detective and become an administrator account for a behavior graph, the user or role must be granted permission for the `CreateGraph` action.
To use the Detective console to perform any administrator account actions, the user or role must be granted permission for the `ListGraphs` action. This grants permission to retrieve the behavior graphs their account is an administrator account for. They also must be granted permission to perform specific administrator account actions.
The most basic administrator account actions are to view a list of member accounts in a behavior graph, and to use the behavior graph for investigation.
+ To view the list of member accounts in a behavior graph, the principal must be granted permission for the `ListMembers` action.
+ To conduct investigation in a behavior graph, the principal must be granted permission for the `SearchGraph` action.
To use the Detective console to perform any member account actions, the user or role must be granted permission for the `ListInvitations` action. This grants permission to view behavior graph invitations. They can then be granted permission for specific member account actions.
## Allowing users to view their own permissions
This example shows how you might create a policy that allows IAM users to view the inline and managed policies that are attached to their user identity. This policy includes permissions to complete this action on the console or programmatically using the AWS CLI or AWS API.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ViewOwnUserInfo",
"Effect": "Allow",
"Action": [
"iam:GetUserPolicy",
"iam:ListGroupsForUser",
"iam:ListAttachedUserPolicies",
"iam:ListUserPolicies",
"iam:GetUser"
],
"Resource": ["arn:aws:iam::*:user/${aws:username}"]
},
{
"Sid": "NavigateInConsole",
"Effect": "Allow",
"Action": [
"iam:GetGroupPolicy",
"iam:GetPolicyVersion",
"iam:GetPolicy",
"iam:ListAttachedGroupPolicies",
"iam:ListGroupPolicies",
"iam:ListPolicyVersions",
"iam:ListPolicies",
"iam:ListUsers"
],
"Resource": "*"
}
]
}
```
## Administrator account: Managing the member accounts in a behavior graph
This example policy is intended for administrator account users who are only responsible for managing the member accounts used in the behavior graph. The policy also allows the user to view the usage information and deactivate Detective. The policy does not grant permission to use the behavior graph for investigation.
------
#### [ JSON ]
****
```
{"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":["detective:ListMembers","detective:CreateMembers","detective:DeleteMembers","detective:DeleteGraph","detective:Get*","detective:StartMonitoringMember"],
"Resource":"arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899"
},
{
"Effect":"Allow",
"Action":["detective:CreateGraph","detective:ListGraphs"],
"Resource":"*"
}
]
}
```
------
## Administrator account: Using a behavior graph for investigation
This example policy is intended for administrator account users who use the behavior graph for investigation only. They cannot view or edit the list of member accounts in the behavior graph.
------
#### [ JSON ]
****
```
{"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":["detective:SearchGraph"],
"Resource":"arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899"
},
{
"Effect":"Allow",
"Action":["detective:ListGraphs"],
"Resource":"*"
}
]
}
```
------
## Member account: Managing behavior graph invitations and memberships
This example policy is intended for users belonging to a member account. In the example, the member account belongs to two behavior graphs. The policy grants permission to respond to invitations and remove the member account from the behavior graph.
------
#### [ JSON ]
****
```
{"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":["detective:AcceptInvitation","detective:RejectInvitation","detective:DisassociateMembership"],
"Resource":[
"arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899",
"arn:aws:detective:us-east-1:444455556666:graph:056d2a9521xi2bbluw1d164680eby416"
]
},
{
"Effect":"Allow",
"Action":["detective:ListInvitations"],
"Resource":"*"
}
]
}
```
------
## Administrator account: Restricting access based on tag values
The following policy allows the user to use a behavior graph for investigation if the `SecurityDomain` tag of the behavior graph matches the `SecurityDomain` tag of the user.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"detective:SearchGraph"
],
"Resource": "arn:aws:detective:*:*:graph:*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/SecurityDomain": "aws:PrincipalTag/SecurityDomain"
}
}
},
{
"Effect": "Allow",
"Action": [
"detective:ListGraphs"
],
"Resource": "*"
}
]
}
```
------
The following policy prevents the users from using a behavior graph for investigation if the value of the `SecurityDomain` tag for the behavior graph is `Finance`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[ {
"Effect":"Deny",
"Action":["detective:SearchGraph"],
"Resource":"arn:aws:detective:*:*:graph:*",
"Condition": {
"StringEquals": {"aws:ResourceTag/SecurityDomain": "Finance"}
}
} ]
}
```
------
# AWS managed policies for Amazon Detective
An AWS managed policy is a standalone policy that is created and administered by AWS. AWS managed policies are designed to provide permissions for many common use cases so that you can start assigning permissions to users, groups, and roles.
Keep in mind that AWS managed policies might not grant least-privilege permissions for your specific use cases because they're available for all AWS customers to use. We recommend that you reduce permissions further by defining [ customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies) that are specific to your use cases.
You cannot change the permissions defined in AWS managed policies. If AWS updates the permissions defined in an AWS managed policy, the update affects all principal identities (users, groups, and roles) that the policy is attached to. AWS is most likely to update an AWS managed policy when a new AWS service is launched or new API operations become available for existing services.
For more information, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *IAM User Guide*.
## AWS managed policy: AmazonDetectiveFullAccess
You can attach the `AmazonDetectiveFullAccess` policy to your IAM identities.
This policy grants administrative permissions that allow a principal full access to all Amazon Detective actions. You can attach this policy to a principal before they enable Detective for their account. It must also be attached to the role that is used to run the Detective Python scripts to create and manage a behavior graph.
Principals with these permissions can manage member accounts, add tags to their behavior graph, and use Detective for investigation. They can also archive GuardDuty findings. The policy provides permissions that the Detective console needs to display account names for accounts that are in AWS Organizations.
**Permissions details**
This policy includes the following permissions:
+ `detective` – Allows principals full access to all Detective actions.
+ `organizations` – Allows principals to retrieve from AWS Organizations information about the accounts in an organization. If an account belongs to an organization, these permissions allow the Detective console to display account names in addition to account numbers.
+ `guardduty` – Allows principals to get and archive GuardDuty findings from within Detective.
+ `securityhub` – Allows principals to get Security Hub CSPM findings from within Detective.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"detective:*",
"organizations:DescribeOrganization",
"organizations:ListAccounts"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"guardduty:ArchiveFindings"
],
"Resource": "arn:aws:guardduty:*:*:detector/*"
},
{
"Effect": "Allow",
"Action": [
"guardduty:GetFindings",
"guardduty:ListDetectors"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"securityHub:GetFindings"
],
"Resource": "*"
}
]
}
```
------
## AWS managed policy: AmazonDetectiveMemberAccess
You can attach the `AmazonDetectiveMemberAccess` policy to your IAM entities.
This policy provides member access to Amazon Detective and scoped access to the console.
With this policy, you can:
+ View invitations to Detective graph membership and accept or reject those invitations.
+ View how your activity in Detective contributes to the cost of using this service on the **Usage** page.
+ Resign from your membership in a graph.
This policy grants read-only permissions that allow scoped access to the Detective
console.
**Permissions details**
This policy includes the following permissions:
+ `detective` – Allows member access to Detective.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"detective:AcceptInvitation",
"detective:BatchGetMembershipDatasources",
"detective:DisassociateMembership",
"detective:GetFreeTrialEligibility",
"detective:GetPricingInformation",
"detective:GetUsageInformation",
"detective:ListInvitations",
"detective:RejectInvitation"
],
"Resource": "*"
}
]
}
```
------
## AWS managed policy: AmazonDetectiveInvestigatorAccess
You can attach the `AmazonDetectiveInvestigatorAccess` policy to your IAM entities.
This policy provides investigator access to the Detective service and scoped access to the Detective console UI dependencies. This policy grants permissions to enable Detective investigations in Detective for IAM users and IAM roles. You can investigate to identify indicators of compromise such as findings using an investigation report, which provides analysis and insights about security indicators. The report is ranked by severity, which is determined using Detective’s behavioral analysis and machine learning. You can use the report to prioritize remediation of resources.
**Permissions details**
This policy includes the following permissions:
+ `detective` – Allows principals investigator access to Detective actions, to enable Detective investigations, and to enable finding groups summary.
+ `guardduty` – Allows principals to get and archive GuardDuty findings from within Detective.
+ `securityhub` – Allows principals to get Security Hub CSPM findings from within Detective.
+ `organizations` – Allows principals to retrieve information about the accounts in an organization from AWS Organizations. If an account belongs to an organization, then these permissions allow the Detective console to display account names in addition to account numbers.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "DetectivePermissions",
"Effect": "Allow",
"Action": [
"detective:BatchGetGraphMemberDatasources",
"detective:BatchGetMembershipDatasources",
"detective:DescribeOrganizationConfiguration",
"detective:GetFreeTrialEligibility",
"detective:GetGraphIngestState",
"detective:GetMembers",
"detective:GetPricingInformation",
"detective:GetUsageInformation",
"detective:ListDatasourcePackages",
"detective:ListGraphs",
"detective:ListHighDegreeEntities",
"detective:ListInvitations",
"detective:ListMembers",
"detective:ListOrganizationAdminAccount",
"detective:ListTagsForResource",
"detective:SearchGraph",
"detective:StartInvestigation",
"detective:GetInvestigation",
"detective:ListInvestigations",
"detective:UpdateInvestigationState",
"detective:ListIndicators",
"detective:InvokeAssistant"
],
"Resource": "*"
},
{
"Sid": "OrganizationsPermissions",
"Effect": "Allow",
"Action": [
"organizations:DescribeOrganization",
"organizations:ListAccounts"
],
"Resource": "*"
},
{
"Sid": "GuardDutyPermissions",
"Effect": "Allow",
"Action": [
"guardduty:ArchiveFindings",
"guardduty:GetFindings",
"guardduty:ListDetectors"
],
"Resource": "*"
},
{
"Sid": "SecurityHubPermissions",
"Effect": "Allow",
"Action": [
"securityHub:GetFindings"
],
"Resource": "*"
}
]
}
```
------
## AWS managed policy: AmazonDetectiveOrganizationsAccess
You can attach the `AmazonDetectiveOrganizationsAccess` policy to your IAM entities.
This policy grants permission to enable and manage Amazon Detective within an organization. You can enable Detective across the organization and determine the delegated administrator account for Detective.
**Permissions details**
This policy includes the following permissions:
+ `detective` – Allows principals access to Detective actions.
+ `iam` – Specifies that a service linked role is created when Detective calls `EnableOrganizationAdminAccount`.
+ `organizations` – Allows principals to retrieve information about the accounts in an organization from AWS Organizations. If an account belongs to an organization, then these permissions allow the Detective console to display account names in addition to account numbers. Enables the integration of an AWS service, allows register and deregister of the specified member account as a Delegated administrator, and allows principals to retrieve Delegated administrator accounts in other security services like Amazon Detective, Amazon GuardDuty, Amazon Macie, and AWS Security Hub CSPM.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"detective:DisableOrganizationAdminAccount",
"detective:EnableOrganizationAdminAccount",
"detective:ListOrganizationAdminAccount"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iam:CreateServiceLinkedRole"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"iam:AWSServiceName": "detective.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"organizations:EnableAWSServiceAccess",
"organizations:RegisterDelegatedAdministrator",
"organizations:DeregisterDelegatedAdministrator"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"organizations:ServicePrincipal": [
"detective.amazonaws.com"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"organizations:DescribeAccount",
"organizations:DescribeOrganization",
"organizations:ListAccounts"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"organizations:ListDelegatedAdministrators"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"organizations:ServicePrincipal": [
"detective.amazonaws.com",
"guardduty.amazonaws.com",
"macie.amazonaws.com",
"securityhub.amazonaws.com"
]
}
}
}
]
}
```
------
## AWS managed policy: AmazonDetectiveServiceLinkedRole
You can't attach the `AmazonDetectiveServiceLinkedRole` policy to your IAM entities. This policy is attached to a service-linked role that allows Detective to perform actions on your behalf. For more information, see [Using service-linked roles for Detective](using-service-linked-roles.md).
This policy grants administrative permissions that allow the service-linked role to retrieve account information for an organization.
**Permissions details**
This policy includes the following permissions:
+ `organizations` – Retrieves account information for an organization.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"organizations:DescribeAccount",
"organizations:ListAccounts"
],
"Resource": "*"
}
]
}
```
------
## Detective updates to AWS managed policies
View details about updates to AWS managed policies for Detective since this service began tracking these changes. For automatic alerts about changes to this page, subscribe to the RSS feed on the [Document history page](doc-history.md).
| Change | Description | Date |
| --- | --- | --- |
| [AmazonDetectiveInvestigatorAccess](#security-iam-awsmanpol-amazondetectiveinvestigatoraccesspolicy) – Updates to existing policies | Added Detective investigations and finding groups summary actions to the `AmazonDetectiveInvestigatorAccess` policy. These actions allow starting, retrieving, and updating Detective investigations; and obtaining a summary of finding groups from within Detective. | November 26, 2023 |
| [AmazonDetectiveFullAccess](#security-iam-awsmanpol-amazondetectivefullaccess) and [AmazonDetectiveInvestigatorAccess](#security-iam-awsmanpol-amazondetectiveorganizationsaccesspolicy) – Updates to existing policies | Detective added Security Hub CSPM `GetFindings` actions to the `AmazonDetectiveFullAccess` and `AmazonDetectiveInvestigatorAccess` policies. These actions allow getting Security Hub CSPM findings from within Detective. | May 16, 2023 |
| [AmazonDetectiveOrganizationsAccess](#security-iam-awsmanpol-amazondetectiveorganizationsaccesspolicy) – New policy | Detective added `AmazonDetectiveOrganizationsAccess` policy. This policy grants permission to enable and manage Detective within an organization | March 02, 2023 |
| [AmazonDetectiveMemberAccess](#security-iam-awsmanpol-amazondetectivememberaccess) – New policy | Detective added the `AmazonDetectiveMemberAccess` policy. This policy provides member access to Detective and scoped access to the console UI dependencies. | January 17, 2023 |
| [AmazonDetectiveFullAccess](#security-iam-awsmanpol-amazondetectivefullaccess) – Updates to an existing policy | Detective added GuardDuty `GetFindings` actions to the `AmazonDetectiveFullAccess` policy. These actions allow getting GuardDuty findings from within Detective. | January 17, 2023 |
| [AmazonDetectiveInvestigatorAccess](#security-iam-awsmanpol-amazondetectiveinvestigatoraccesspolicy) – New policy | Detective added the `AmazonDetectiveInvestigatorAccess` policy. This policy allows the principal to conduct investigations in Detective. | January 17, 2023 |
| [AmazonDetectiveServiceLinkedRole](#security-iam-awsmanpol-amazondetectiveservicelinkedrolepolicy) – New policy | Detective added a new policy for its service-linked role. The policy allows the service-linked role to retrieve information about the accounts in an organization. | December 16, 2021 |
| Detective started to track changes | Detective started to track changes for its AWS managed policies. | May 10, 2021 |
# Using service-linked roles for Detective
Amazon Detective uses AWS Identity and Access Management (IAM)[ service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role). A service-linked role is a unique type of IAM role that is linked directly to Detective. Service-linked roles are predefined by Detective and include all the permissions that the service requires to call other AWS services on your behalf.
A service-linked role makes setting up Detective easier because you do not have to manually add the necessary permissions. Detective defines the permissions of its service-linked roles, and unless defined otherwise, only Detective can assume its roles. The defined permissions include the trust policy and the permissions policy, and that permissions policy cannot be attached to any other IAM entity.
You can delete a service-linked role only after first deleting their related resources. This protects your Detective resources because you cannot inadvertently remove permission to access the resources.
For information about other services that support service-linked roles, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) and look for the services that have **Yes **in the **Service-Linked Role** column. Choose a **Yes** with a link to view the service-linked role documentation for that service.
## Service-linked role permissions for Detective
Detective uses the service-linked role named **AWSServiceRoleForDetective** – Allows Detective to access AWS Organizations information on your behalf.
The AWSServiceRoleForDetective service-linked role trusts the following services to assume the role:
+ `detective.amazonaws.com`
The AWSServiceRoleForDetective service-linked role uses the managed policy [`AmazonDetectiveServiceLinkedRolePolicy`](security-iam-awsmanpol.md#security-iam-awsmanpol-amazondetectiveservicelinkedrolepolicy).
For details about updates to the `AmazonDetectiveServiceLinkedRolePolicy` policy see [Amazon Detective updates to AWS managed policies](https://docs.aws.amazon.com//detective/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-updates). For automatic alerts about changes to this policy, subscribe to the RSS feed on the [Detective document history](https://docs.aws.amazon.com//detective/latest/userguide/doc-history.html) page.
You must configure permissions to allow an IAM entity (such as a user, group, or role) to create, edit, or delete a service-linked role. For more information, see [Service-linked role permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions) in the *IAM User Guide*.
## Creating a service-linked role for Detective
You do not need to manually create a service-linked role. When you designate the Detective administrator account for an organization in the AWS Management Console, the AWS CLI, or the AWS API, Detective creates the service-linked role for you.
If you delete this service-linked role, and then need to create it again, you can use the same process to recreate the role in your account. When you designate the Detective administrator account for an organization, Detective creates the service-linked role for you again.
## Editing a service-linked role for Detective
Detective does not allow you to edit the AWSServiceRoleForDetective service-linked role. After you create a service-linked role, you cannot change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM. For more information, see [Editing a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role) in the *IAM User Guide*.
## Deleting a service-linked role for Detective
If you no longer need to use a feature or service that requires a service-linked role, we recommend that you delete that role. That way you don’t have an unused entity that is not actively monitored or maintained. However, you must clean up the resources for your service-linked role before you can manually delete it.
**Note**
If the Detective service is using the role when you try to delete the resources, then the deletion might fail. If that happens, wait for a few minutes and then try the operation again.
**To delete Detective resources used by the AWSServiceRoleForDetective**
1. Remove the Detective administrator account. See [Designating the Detective administrator for an organization](accounts-designate-admin.md).
1. Repeat the process in each Region where you designated the Detective administrator account.
**To manually delete the service-linked role using IAM**
Use the IAM console, the AWS CLI, or the AWS API to delete the AWSServiceRoleForDetective service-linked role. For more information, see [Deleting a Service-Linked Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role) in the *IAM User Guide*.
## Supported Regions for Detective service-linked roles
Detective supports using service-linked roles in all of the Regions where the service is available. For more information, see [AWS Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html).
# Troubleshooting Amazon Detective identity and access
Use the following information to help you diagnose and fix common issues that you might encounter when working with Detective and IAM. If you encounter access denied issues or similar difficulties when working with AWS Identity and Access Management(IAM), consult the [Troubleshooting IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot.html) topics in the *IAM User Guide*.
## I am not authorized to perform an action in Detective
If the AWS Management Console tells you that you're not authorized to perform an action, then you must contact your administrator for assistance. Your administrator is the person that provided you with your user name and password.
The following example error occurs when the `mateojackson` IAM user tries to use the console to accept an invitation to become a member account for a behavior graph, but does not have `detective:AcceptInvitation` permissions.
```
User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: detective:AcceptInvitation on resource: arn:aws:detective:us-east-1:444455556666:graph:567856785678
```
In this case, Mateo asks his administrator to update his policies to allow him to access the `arn:aws:detective:us-east-1:444455556666:graph:567856785678` resource using the `detective:AcceptInvitation` action.
## I am not authorized to perform iam:PassRole
If you receive an error that you're not authorized to perform the `iam:PassRole` action, your policies must be updated to allow you to pass a role to Detective.
Some AWS services allow you to pass an existing role to that service instead of creating a new service role or service-linked role. To do this, you must have permissions to pass the role to the service.
The following example error occurs when an IAM user named `marymajor` tries to use the console to perform an action in Detective. However, the action requires the service to have permissions that are granted by a service role. Mary does not have permissions to pass the role to the service.
```
User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole
```
In this case, Mary's policies must be updated to allow her to perform the `iam:PassRole` action.
If you need help, contact your AWS administrator. Your administrator is the person who provided you with your sign-in credentials.
## I want to allow people outside of my AWS account to access my Detective resources
You can create a role that users in other accounts or people outside of your organization can use to access your resources. You can specify who is trusted to assume the role. For services that support resource-based policies or access control lists (ACLs), you can use those policies to grant people access to your resources.
To learn more, consult the following:
+ To learn whether Detective supports these features, see [How Amazon Detective works with IAM](security_iam_service-with-iam.md).
+ To learn how to provide access to your resources across AWS accounts that you own, see [Providing access to an IAM user in another AWS account that you own](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_aws-accounts.html) in the *IAM User Guide*.
+ To learn how to provide access to your resources to third-party AWS accounts, see [Providing access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) in the *IAM User Guide*.
+ To learn how to provide access through identity federation, see [Providing access to externally authenticated users (identity federation)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) in the *IAM User Guide*.
+ To learn the difference between using roles and resource-based policies for cross-account access, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*.