Amazon Neptune
User Guide (API Version 2017-11-29)

IAM Database Authentication for Neptune

You can authenticate to your Neptune DB instance or DB cluster using AWS Identity and Access Management (IAM) database authentication.

When IAM database authentication is enabled, each request must be signed using AWS Signature Version 4.

AWS Signature Version 4 is the process to add authentication information to AWS requests. For security, all requests to Neptune DB clusters with IAM authentication enabled must be signed with an access key, which consists of an access key ID and secret access key. The authentication is managed externally using IAM polices.

Neptune authenticates on connection, and for WebSockets connections it verifies the permissions periodically to ensure the user still has access.

Note

Revoking, deleting or rotating of credentials associated with the IAM User would not terminate open connections, and thus is not recommended.

WebSocket Concurrent Connections

The maximum number of concurrent websocket connections per database instance is 60,000. When the limit is reached Neptune will throttle a request to open a new websocket connection.

If a client properly closes a connection then it will be reflected in the open connections count immediately. If the client does not close the connection then the connection will remain open until it is closed after a 60 minute idle timeout. The idle timeout is the time elapsed since the last message was received from the client.

WebSocket Maximum Connection Time

WebSocket connections are disconnected 36 hours after the connection is established.

Enabling IAM Authentication

By default, IAM database authentication is disabled when you create a Neptune DB cluster. You can enable IAM database authentication (or disable it again) using the AWS Management Console.

AWS Management Console

To create a new Neptune DB cluster with IAM authentication by using the console, you must follow the instructions to create a Neptune DB cluster in the Launching a Neptune DB Cluster topic.

On the second page of the creation process, choose Yes for Enable IAM DB Authentication.

To enable or disable IAM authentication for an existing DB instance or cluster

  1. Sign in to the AWS Management Console, and open the Amazon Neptune console at https://console.aws.amazon.com/neptune/home.

  2. In the navigation pane, choose Clusters.

  3. Choose the Neptune DB cluster that you want to modify, and then choose Cluster actions, and then choose Modify cluster.

  4. In the Database options section, for IAM DB Authentication, choose Enable IAM DB authorization or No (to disable), and then choose Continue.

  5. To apply the changes immediately, choose Apply immediately.

  6. Choose Modify cluster.

Creating and Using an IAM Policy for IAM Database Access

To allow an IAM user to connect to your Neptune DB cluster, you must create an IAM policy. After that, you attach the policy to an IAM user or role. For information on attaching a policy to a role, see Adding and Removing IAM Policies in the IAM documentation.

Note

The IAM policy, IAM user, and Neptune DB cluster must be in the same account. Cross-account access is not supported.

The following example policy allows an IAM user to connect to Neptune DB cluster using IAM database authentication.

Important

The neptune-db ARN for the IAM authorization Resource is not the same as the ARN assigned to the cluster on creation. You must construct the ARN as shown after the example.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "neptune-db:*" ], "Resource": [ "arn:aws:neptune-db:us-east-1:123456789012:cluster-ABCD1234EFGH5678IJKL90MNOP/*" ] } ] }

Important

The neptune-db: prefix and the neptune-db:* action are only for IAM database authentication. They aren't valid in any other context.

The resource section above includes a resource ARN in a format that is particular to Neptune IAM authentication. The following section goes over how to construct the ARN. The ARN for the IAM authorization Resource is not the same as the ARN assigned to the cluster on creation. You must construct the ARN as shown.

Constructing a Resource ARN for a Cluster

The a Resource ARN includes a single statement with the following elements:

  • Effect—Specify Allow to grant access to the DB cluster. If you don't explicitly allow access, then access is denied by default.

  • Action—Specify neptune-db:* to allow connection to the DB cluster.

  • Resource—Specify an Amazon Resource Name (ARN) that describes a specific DB cluster. The ARN format is as follows:

    arn:aws:neptune-db:region:account-id:cluster-resource-id/*

    In this format, the following are so:

    • region is the AWS Region for the Amazon Neptune DB cluster. In the example policy, the AWS Region is us-east-1.

    • account-id is the AWS account number for the DB cluster. In the example policy, the account number is 123456789012.

    • cluster-resource-id is a resource id for the DB cluster . In the example policy, the identifier is cluster-ABCD1234EFGH5678IJKL90MNOP.

      Important

      The cluster-resource-id is different than the cluster identifier.

      To find a cluster resource ID in the AWS Management Console for Amazon Neptune, choose the DB cluster you want and the Resource ID is shown in the Details section.

Important

Changes to an IAM policy take up to 10 minutes to apply to the specified Neptune resources.

IAM policies applied to a Neptune DB cluster apply to all instances in that cluster.

IAM Authentication Policy Examples

The following example policies require that you construct a Resource ARN. The example resource ARNs may use wildcards to include multiple resources.

The Resource ARN in the "Resource" list in the policy is not the same as a cluster ARN and must be constructed according to the Resource ARN format. For more information, see Constructing a Resource ARN for a Cluster.

Important

Changes to an IAM policy take up to 10 minutes to apply to the specified Neptune resources.

IAM policies applied to a Neptune DB cluster apply to all instances in that cluster.

Grant Access to All Clusters

The following policy uses the "*" character to match all of the DB clusters for a particular AWS account and AWS Region.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "neptune-db:*" ], "Resource": [ "arn:aws:neptune-db:us-east-1:123456789012:*/*" ] } ] }

The IAM user has access to everything on the Neptune DB cluster. Neptune does not support fine-grained access control.

The Resource ARN in the "Resource" list in the policy is not the same as a cluster ARN and must be constructed according to the Resource ARN format. For more information, see Constructing a Resource ARN for a Cluster.

Deny Access to a Specific Cluster

The following policy denies access to a DB cluster for a particular AWS account and AWS Region.

The default IAM action is to deny access to a DB cluster unless an Allow Effect is granted.

To ensure that access is blocked, you can use the Deny Effect. The explicit Deny Effect takes precedent over any Allow Effect.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": [ "neptune-db:*" ], "Resource": [ "arn:aws:neptune-db:us-east-1:123456789012:cluster-ABCD1234EFGH5678IJKL90MNOP/*" ] } ] }

The IAM user is denied access to everything on the Neptune DB cluster. Neptune does not support fine-grained access control.

The Resource ARN in the "Resource" list in the policy is not the same as a cluster ARN and must be constructed according to the Resource ARN format. For more information, see Constructing a Resource ARN for a Cluster.

Deny Access to All Clusters

The following policy denies access to all DB clusters for a particular AWS account and AWS Region.

The default IAM action is to deny access to a DB cluster unless an Allow Effect is granted.

To ensure that access is blocked, you can use the Deny Effect. The explicit Deny Effect takes precedent over any Allow Effect.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": [ "neptune-db:*" ], "Resource": [ "arn:aws:neptune-db:us-east-1:123456789012:*/*" ] } ] }

The IAM user is denied access to everything on the Neptune DB cluster. Neptune does not support fine-grained access control.

The Resource ARN in the "Resource" list in the policy is not the same as a cluster ARN and must be constructed according to the Resource ARN format. For more information, see Constructing a Resource ARN for a Cluster.

Next, you need to attach the IAM policy to a user.

Attaching an IAM Policy to an IAM User

After you create an IAM policy to allow database authentication, you need to attach the policy to an IAM user. For a tutorial on this topic, see Create and Attach Your First Customer Managed Policy in the IAM User Guide.

As you work through the tutorial, you can use one of the policy examples shown in this section as a starting point and tailor it to your needs. At the end of the tutorial, you have an IAM user with an attached policy that can use the neptune-db:* action.

Important

Changes to an IAM policy take up to 10 minutes to apply to the specified Neptune resources.

IAM policies applied to a Neptune DB cluster apply to all instances in that cluster.

IAM Policy Limitations

Changes to an IAM policy take up to 10 minutes to apply to the specified Neptune resources.

IAM policies applied to a Neptune DB cluster apply to all instances in that cluster.

Neptune does not support the following:

  • AWS Global and IAM Condition Context Keys.

  • Fine-grained access control.

  • Actions other than neptune-db:*. A user must have a policy granting the neptune-db:* Action to access an instance.

  • Cross-account access.

Connecting and Signing with AWS Signature Version 4

Amazon Neptune resources that have IAM DB authentication enabled require all HTTP requests to be signed using AWS Signature Version 4.

For general information about signing requests with AWS Signature Version 4, see Signature Version 4 Signing Process.

AWS Signature Version 4 is the process to add authentication information to AWS requests. For security, most requests to AWS must be signed with an access key, which consists of an access key ID and secret access key.

Note

If you are using temporary credentials, they expire after a specified interval, including the session token.

You will need to update your session token when you request new credentials. For more information, see Using Temporary Security Credentials to Request Access to AWS Resources.

Important

Accessing Neptune with IAM-based authentication requires that you create HTTP requests and sign the requests yourself.

How AWS Signature Version 4 works

  1. You create a canonical request.

  2. You use the canonical request and some other information to create a string to sign.

  3. You use your AWS secret access key to derive a signing key, and then use that signing key and the string to sign to create a signature.

  4. You add the resulting signature to the HTTP request in a header or as a query string parameter.

When Neptune receives the request, it performs the same steps that you did to calculate the signature. Neptune then compares the calculated signature to the one you sent with the request. If the signatures match, the request is processed. If the signatures don't match, the request is denied.

For general information about signing requests with AWS Signature Version 4, see Signature Version 4 Signing Process.

The following sections show examples that illustrate how to send signed requests to the Gremlin and SPARQL endpoints of a Neptune DB instance with IAM authentication enabled.