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

IAM Authentication Using Temporary Credentials

Amazon Neptune supports IAM authentication using temporary credentials.

You can use an assumed role to authenticate using an IAM authentication policy, like one of the example policies in the previous sections.

If you are using temporary credentials, you must specify AWS_SESSION_TOKEN in addition to AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and SERVICE_REGION.

Note

The temporary credentials expire after a specified interval, including the session token.

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

The following sections describe how to allow access and retrieve temporary credentials.

To authenticate using temporary credentials

  1. Create an IAM role with permission to access a Neptune cluster. For information about creating this role, see Creating and Using an IAM Policy for IAM Database Access.

  2. Add a trust relationship to the role that allows access to the credentials.

    Retrieve the temporary credentials, including the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.

  3. Connect to the Neptune cluster and sign the requests using the temporary credentials. For more information about connecting and signing requests, see Connecting and Signing with AWS Signature Version 4.

There are various methods for retrieving temporary credentials depending on the environment.

Get Credentials with the AWS CLI

To get credentials using the AWS Command Line Interface (AWS CLI), first you need to add a trust relationship that grants permission to assume the role to the AWS user that will run the AWS CLI command.

Add the following trust relationship to the Neptune IAM authentication role. If you don't have a Neptune IAM authentication role, see Creating and Using an IAM Policy for IAM Database Access.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/test" }, "Action": "sts:AssumeRole" } ] }

For information about adding the trust relationship to the role, see Editing the Trust Relationship for an Existing Role.

If the Neptune policy is not yet attached to a role, create a new role. Attach the Neptune IAM authentication policy, and then add the trust policy. For information about creating a new role, see Create Role.

Note

The following sections assume that you have the AWS CLI installed.

To run the AWS CLI manually

  1. Enter the following command to request the credentials using the AWS CLI. Replace the role ARN, session name, and profile with your own values.

    aws sts assume-role --role-arn arn:aws:iam::123456789012:role/NeptuneIAMAuthRole --role-session-name test --profile testprofile
  2. The following is example output from the command. The Credentials section contains the values that you need.

    Note

    Record the Expiration value because you need to get new credentials after this time.

    { "AssumedRoleUser": { "AssumedRoleId": "AROA3XFRBF535PLBIFPI4:s3-access-example", "Arn": "arn:aws:sts::123456789012:assumed-role/xaccounts3access/s3-access-example" }, "Credentials": { "SecretAccessKey": "9drTJvcXLB89EXAMPLELB8923FB892xMFI", "SessionToken": "AQoXdzELDDY//////////wEaoAK1wvxJY12r2IrDFT2IvAzTCn3zHoZ7YNtpiQLF0MqZye/qwjzP2iEXAMPLEbw/m3hsj8VBTkPORGvr9jM5sgP+w9IZWZnU+LWhmg+a5fDi2oTGUYcdg9uexQ4mtCHIHfi4citgqZTgco40Yqr4lIlo4V2b2Dyauk0eYFNebHtYlFVgAUj+7Indz3LU0aTWk1WKIjHmmMCIoTkyYp/k7kUG7moeEYKSitwQIi6Gjn+nyzM+PtoA3685ixzv0R7i5rjQi0YE0lf1oeie3bDiNHncmzosRM6SFiPzSvp6h/32xQuZsjcypmwsPSDtTPYcs0+YN/8BRi2/IcrxSpnWEXAMPLEXSDFTAQAM6Dl9zR0tXoybnlrZIwMLlMi1Kcgo5OytwU=", "Expiration": "2016-03-15T00:05:07Z", "AccessKeyId": "ASIAJEXAMPLEXEG2JICEA" } }
  3. Set the environment variables using the returned credentials.

    export AWS_ACCESS_KEY_ID=ASIAJEXAMPLEXEG2JICEA export AWS_SECRET_ACCESS_KEY=9drTJvcXLB89EXAMPLELB8923FB892xMFI export AWS_SESSION_TOKEN=AQoXdzELDDY//////////wEaoAK1wvxJY12r2IrDFT2IvAzTCn3zHoZ7YNtpiQLF0MqZye/qwjzP2iEXAMPLEbw/m3hsj8VBTkPORGvr9jM5sgP+w9IZWZnU+LWhmg+a5fDi2oTGUYcdg9uexQ4mtCHIHfi4citgqZTgco40Yqr4lIlo4V2b2Dyauk0eYFNebHtYlFVgAUj+7Indz3LU0aTWk1WKIjHmmMCIoTkyYp/k7kUG7moeEYKSitwQIi6Gjn+nyzM+PtoA3685ixzv0R7i5rjQi0YE0lf1oeie3bDiNHncmzosRM6SFiPzSvp6h/32xQuZsjcypmwsPSDtTPYcs0+YN/8BRi2/IcrxSpnWEXAMPLEXSDFTAQAM6Dl9zR0tXoybnlrZIwMLlMi1Kcgo5OytwU= export SERVICE_REGION=us-east-1|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1|ap-southeast-1|ap-southeast-2|ap-northeast-1|ap-south-1|ap-northeast-2
  4. Connect using one of the following methods.

To use a script to get the credentials

  1. Run the following command to install the jq command. The script uses this command to parse the output of the AWS CLI command.

    sudo yum -y install jq
  2. Create a file named credentials.sh in a text editor and add the following text. Replace the service Region, role ARN, session name, and profile with your own values.

    #!/bin/bash creds_json=$(aws sts assume-role --role-arn arn:aws:iam::123456789012:role/NeptuneIAMAuthRole --role-session-name test --profile testprofile) export AWS_ACCESS_KEY_ID=$(echo "$creds_json" | jq .Credentials.AccessKeyId |tr -d '"') export AWS_SECRET_ACCESS_KEY=$(echo "$creds_json" | jq .Credentials.SecretAccessKey| tr -d '"') export AWS_SESSION_TOKEN=$(echo "$creds_json" | jq .Credentials.SessionToken|tr -d '"') export SERVICE_REGION=us-east-1|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1|ap-southeast-1|ap-southeast-2|ap-northeast-1|ap-south-1|ap-northeast-2
  3. Connect using one of the following methods.

Setting Up AWS Lambda for Neptune IAM Authentication

AWS Lambda includes credentials automatically each time the Lambda function is run.

First you add a trust relationship that grants permission to assume the role to the Lambda service.

Add the following trust relationship to the Neptune IAM authentication role. If you don't have a Neptune IAM authentication role, see Creating and Using an IAM Policy for IAM Database Access.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

For information about adding the trust relationship to the role, see Editing the Trust Relationship for an Existing Role.

If the Neptune policy is not yet attached to a role, create a new role. Attach the Neptune IAM authentication policy, and then add the trust policy. For information about creating a new role, see Create Role.

To access Neptune from Lambda

  1. Sign in to the AWS Management Console and open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

  2. Create a new Lambda function for Python version 3.6.

  3. Assign the AWSLambdaVPCAccessExecutionRole role to the Lambda function. This is required to access Neptune resources, which are VPC only.

  4. Assign the Neptune authentication IAM role to the Lambda function.

    For more information, see AWS Lambda Permissions Model.

  5. Copy the IAM authentication Python sample into the Lambda function code.

    For more information about the sample and the sample code, see Example: Connecting to Neptune Using Python with Signature Version 4 Signing.

Set Up Amazon EC2 for Neptune IAM Authentication

Amazon EC2 allows you to use instance profiles to automatically provide credentials. For more information, see Using Instance Profiles.

First you add a trust relationship that grants permission to assume the role to the Amazon EC2 service.

Add the following trust relationship to the Neptune IAM authentication role. If you don't have a Neptune IAM authentication role, see Creating and Using an IAM Policy for IAM Database Access.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

For information about adding the trust relationship to the role, see Editing the Trust Relationship for an Existing Role.

If the Neptune policy is not yet attached to a role, create a new role. Attach the Neptune IAM authentication policy, and then add the trust policy. For information about creating a new role, see Create Role.

To use a script to get the credentials

  1. Run the following command to install the jq command. The script uses this command to parse the output of the curl command.

    sudo yum -y install jq
  2. Create a file named credentials.sh in a text editor and add the following text. Replace the service Region with your own value.

    #!/bin/bash role_name=$( curl -s https://169.254.169.254/latest/meta-data/iam/security-credentials/ ) creds_json=$(curl -s https://169.254.169.254/latest/meta-data/iam/security-credentials/${role_name}) export AWS_ACCESS_KEY_ID=$(echo "$creds_json" | jq .AccessKeyId |tr -d '"') export AWS_SECRET_ACCESS_KEY=$(echo "$creds_json" | jq .SecretAccessKey| tr -d '"') export AWS_SESSION_TOKEN=$(echo "$creds_json" | jq .Token|tr -d '"') export SERVICE_REGION=us-east-1|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1|ap-southeast-1|ap-southeast-2|ap-northeast-1|ap-south-1|ap-northeast-2
  3. Connect using one of the following methods.