Link Search Menu Expand Document
Start for Free

AWS Aurora IAM Pass-Through Setup

This page describes the AWS-side setup required before Stardog can use pass-through authentication with an Amazon Aurora data source. Once this setup is complete, configure the Stardog data source as described under AWS Aurora.

This page covers the AWS-side setup required to use IAM pass-through authentication with an Aurora data source.

Page Contents
  1. AWS Aurora IAM Pass-Through Setup
    1. Overview
    2. Prerequisites
    3. Step 1 — Enable IAM database authentication
    4. Step 2 — Register the identity provider in IAM
    5. Step 3 — Create the IAM role Stardog assumes
    6. Step 4 — Provision the database users
    7. Hardening the role
      1. Restrict who can assume the role
      2. Pin each session to a single database user
    8. Next steps

Overview

With AWS Aurora, pass-through authentication relies on Aurora IAM database authentication rather than passing the user’s token directly into the JDBC connection. When a query arrives carrying the user’s token, Stardog uses AWS STS web-identity federation to assume an IAM role, generates a short-lived IAM authentication token for the database user derived from the token, and connects to Aurora as that per-user database role.

This flow works with any OAuth identity provider whose access tokens are JSON Web Tokens (JWTs). You register the provider in AWS IAM (see Step 2), and AWS STS validates each token against it, so the token’s issuer and audience must match what you register. The examples on this page use Okta; providers that issue opaque (non-JWT) access tokens are not supported.

The end-to-end identity path is:

  1. The user logs in through a Stardog client application (such as Stardog Launchpad or a web portal) using the configured identity provider. The client application (not the Stardog server) obtains the user’s token.
  2. The user queries Stardog, presenting that token in the Authorization: Bearer header, and Stardog verifies it.
  3. When the query reads a passthrough-configured Aurora data source, Stardog sends the user’s token to AWS STS (AssumeRoleWithWebIdentity). STS verifies the token against the OAuth identity provider you registered, checking its signature, issuer, and audience, and returns temporary credentials if the role’s trust policy allows it.
  4. Stardog generates an IAM authentication token for the database user derived from the token.
  5. Stardog connects to Aurora using IAM authentication, and Aurora runs the session as that database user.

Prerequisites

  • An Amazon Aurora cluster (PostgreSQL- or MySQL-compatible).
  • An OAuth identity provider whose tokens are JWTs and that you can register in AWS IAM, with a known issuer URL and audience value.
  • Permissions to manage IAM identity providers, roles, and policies in the target AWS account.

Step 1 — Enable IAM database authentication

Enable IAM database authentication on the Aurora cluster.

This option can be set when the cluster is created, or enabled later by modifying the cluster. Applying it to an existing cluster requires a reboot.

Step 2 — Register the identity provider in IAM

In the IAM console, go to Identity providers → Add provider and select the OpenID Connect type. Register your identity provider’s authorization server:

Field Value
Provider URL Your identity provider’s issuer URL
Audience The audience your identity provider sets in the tokens Stardog presents to AWS

The audience must match the aud claim in the JWTs that Stardog presents to AWS. After creating the provider, note its ARN for the next step.

Step 3 — Create the IAM role Stardog assumes

Create an IAM role that Stardog assumes through web-identity federation. In the IAM console, choose Roles → Create role → Web identity, and select the identity provider from Step 2.

The role’s trust policy allows the identity provider to assume the role, restricted to your audience:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<account-id>:oidc-provider/<provider-url>"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "<provider-url>:aud": "<audience>"
        }
      }
    }
  ]
}

The role’s permissions policy grants rds-db:connect against the cluster:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "rds-db:connect",
      "Resource": "arn:aws:rds-db:<region>:<account-id>:dbuser:<cluster-resource-id>/*"
    }
  ]
}

The <cluster-resource-id> is the cluster’s Resource ID (RDS console → cluster → Configuration), not the cluster name. The trailing /* allows the role to connect as any database user; access for an individual user is enforced by the database grants in Step 4.

Note the role’s ARN, which is the value of the aws.role.arn data source option.

Step 4 — Provision the database users

The database user that Stardog derives from each user’s token must already exist in the database and be enabled for IAM authentication. Stardog does not create these users; provision them ahead of time, granting each one the privileges it needs.

The database username must match the value Stardog derives from the token, including case. See Deriving the database username for how that value is determined.

Enabling a user for IAM authentication is engine-specific. See Creating a database account using IAM authentication for the exact steps for your Aurora engine.

Hardening the role

The trust and permission policies in Step 3 are intentionally permissive so the integration works out of the box: the role can be assumed by any caller that presents a valid token for the configured provider and audience, and the trailing /* in the rds-db:connect resource lets it connect as any database user on the cluster. In a typical deployment Stardog mediates all access and the Aurora cluster is reachable only by Stardog, so this is acceptable. Where you want stronger guarantees, for example if the cluster is reachable beyond Stardog, you can tighten the role in either or both of the following ways.

Restrict who can assume the role

Add a condition to the role’s trust policy so it can only be assumed from Stardog’s network. (AssumeRoleWithWebIdentity is an anonymous call, so the role can’t be restricted by an AWS identity, but it can be restricted by network origin.)

  • Use aws:SourceIp when Stardog reaches AWS over the public internet, pinned to Stardog’s stable egress address (an Elastic IP or NAT gateway IP):

    "Condition": {
  "StringEquals": {
    "<provider-url>:aud": "<audience>"
  },
  "IpAddress": {
    "aws:SourceIp": "<stardog-egress-ip>/32"
  }
}

  • Use aws:SourceVpce when Stardog reaches STS through a VPC interface endpoint, pinned to that endpoint’s ID.

This ensures only Stardog (by network origin) can obtain the temporary credentials.

Pin each session to a single database user

You can also constrain the role so that a session can only connect as the database user named in its own token, which removes the /* breadth entirely (even a holder of valid role credentials cannot request a different database user). This uses AWS session tags:

  1. Configure your identity provider to emit an AWS session-tag claim named https://aws.amazon.com/tags on the token, carrying the database username. In Okta, add a custom claim on the access token whose value is an expression that builds the tag object with dbuser set to the user’s login:

    {"principal_tags":{"dbuser":{user.login}},"transitive_tag_keys":{"dbuser"}}

    Here user.login resolves per user, so each token carries its own dbuser value. After saving, decode a minted token to confirm the claim contains the resolved username.

  2. Add sts:TagSession to the trust policy’s action. STS rejects token-supplied session tags without it:

    "Action": ["sts:AssumeRoleWithWebIdentity", "sts:TagSession"]

  3. Change the permission policy resource from /* to ${aws:PrincipalTag/dbuser}:

    "Resource": "arn:aws:rds-db:<region>:<account-id>:dbuser:<cluster-resource-id>/${aws:PrincipalTag/dbuser}"

With this in place, the role can only generate IAM authentication tokens for the database user whose name matches the dbuser session tag carried in the signed token, so a session authenticated as one user cannot connect as a different database user.

When session-tag pinning is used, the database username must exactly equal the value carried in the session tag. The identity-provider username, the session tag, and the Aurora database user must all be the same value, and the username-derivation options in the AWS Aurora data source configuration (aws.db.user.regex and aws.db.user.lowercase) must not be used, because any transformation would make the username Stardog connects with differ from the tag and the connection would be denied. (aws.db.user.claim defaults to sub; whichever claim is used must match both the tag and the Aurora username.)

Next steps

With the AWS-side setup complete, configure the Stardog data source as described under AWS Aurora.