Skip to main content

Authentication

Overview​

Authentication is setup for Depot Datasets by using the auth property when defining a Depot Dataset with the CDK library. There are two configuration options for Dataset authentication: Cognito, and IAM.

See also:

Supported authentication methods​

Cognito​

To enable cognito authentication, create a Cognito IAM Role and Depot Location:

const cognitoRole = new iam.Role(this, "CognitoIdpRole", {
    assumedBy: new iam.AccountPrincipal(depotEnvironment.accountId),
    inlinePolicies: {
        cognito: new iam.PolicyDocument({
            statements: [
                new iam.PolicyStatement({
                    effect: iam.Effect.ALLOW,
                    actions: [
                        "cognito-idp:*",
                    ],
                    resources: [
                        "arn:aws:cognito-idp:eu-west-1:123456789012:userpool/eu-west-1_yourPoolId"
                    ]
                })
            ]
        })
    }
});

new Location.Cognito(this, "CognitoLocation", {
    environment: depotEnvironment,
    region: "eu-west-1",
    userPoolId: "eu-west-1_yourPoolId",
    clientId: "yourClientId",
    roleArn: cognitoRole.roleArn
});

Next, configure your Dataset as follows:

new Dataset(this, "ExampleDatasetWithAuth", {
    environment: depotEnvironment,
    package: myPackage,
    name: "example",
    location: exampleLocation,
    auth: {
        cognito: {
            region: "eu-west-1",
            roleArn: "IAM Role ARN",
            userPoolId: "Cognito User Pool ID",
            clientId: "Cognito Client App ID"
        }
    }
});

Cognito authentication is supported in two modes, selected via the HTTP Authorization header for requests:

  • Bearer {access token}
  • Basic {base64(username:password)}

For Cognito basic authentication to work, the user pool client must have ALLOW_USER_PASSWORD_AUTH enabled, and have no client secret.

IAM​

To enable IAM authentication, configure your Dataset with the auth property and an iam configuration block:

new Dataset(this, "ExampleDatasetWithAuth", {
    environment: depotEnvironment,
    package: myPackage,
    name: "example",
    location: exampleLocation,
    auth: {
        iam: {
            principals: [
                // list of ARNs to principals which should have access, e.g.:
                "arn:aws:iam::<account_id>:root"
            ],
            // toggles whether delegated auth (IAM + Bearer token) is enabled for the dataset
            delegatedAuthEnabled: true,
            // toggles whether raw SQL endpoint (POST /{datasetId}/raw-query) is enabled for the dataset
            rawSqlEndpointEnabled: true,
        }
    }
});

IAM auth is via a separate gateway, the URL form of this gateway is:

  • GraphQL API endpoint: https://iam-{endpoint}/graphql
  • Rest API specification: https://iam-{endpoint}/api (only available within the environment's private VPC network)

Admin principal inheritance​

IAM principals configured on the __admin dataset are automatically propagated to every dataset's IAM principal list at sync time. This ensures that environment administrators retain access to all datasets through the IAM gateway without having to repeat the principal list on every Dataset construct.

Exception: when a dataset has rawSqlEndpointEnabled: true, admin principals are not inherited by default. This forces stricter access control to the dataset's IAM GW to make raw SQL endpoint access more controlled.

To override this and force admin principal inheritance regardless of the rawSqlEndpointEnabled setting, set forceIamGwAdminPrincipalsInheritance: true on the Environment construct:

new depot.Environment(this, "DepotEnvironment", {
    // ...
    forceIamGwAdminPrincipalsInheritance: true,
});

Use this option in development environments where such strict access controls are not mandatory.