Enterprise Administration

This document covers advanced configuration and administration for Quilt Enterprise installations.

For installation instructions, see Installation. For architecture details, see Architecture.

Health and Monitoring

To check the status of your Quilt stack after bring-up or update, check the stack health in the CloudFormation console.

Elasticsearch Cluster

If you notice slow or incomplete search results, check the status of the Quilt Elasticsearch cluster. To find the Quilt search cluster from CloudFormation, click on the Quilt stack, then "Resources." Click on the "Search" resource.

If your cluster status is not "Green" (healthy), please contact Quilt support. Causes of unhealthy search clusters include:

Running out of storage space
High index rates (e.g., caused by adding or updating very large numbers of files in S3)

Service Limits

This deployment does not require an increase in limits for your AWS Account.

External Dependencies

In addition to containers running in Fargate, Quilt includes a set of AWS Lambda functions. These lambda functions are not scanned by AWS Marketplace. The code for the lambda functions is open-source and has been verified through an independent security audit.

Advanced configuration

The default Quilt settings are adequate for most use cases. The following section covers advanced customization options.

Setting the default role

The Quilt admin must log in and set the default role in order for new users to be able to sign up.

Single sign-on (SSO)

Google

You can enable users on your Google domain to sign in to Quilt. Refer to Google's instructions on OAuth2 user agents and create authorization credentials to identify your Quilt stack to Google's OAuth 2.0 server.

Copy the Client ID and Client secret to a safe place. Add <QuiltWebHost>/oauth-callback to authorized redirect URIs.

Microsoft Entra ID (Azure Active Directory)

Go to Microsoft Entra admin center → Microsoft Entra ID → Applications → App registrations → New registration.
Name the app, select the supported account types, and click Register. Note the Application (client) ID and Directory (tenant) ID.
Go to Authentication → Add a platform → Web. Add the redirect URI <QuiltWebHost>/oauth-callback. Under Implicit grant and hybrid flows, enable ID tokens (required — login will fail without it). Click Save.
Go to Certificates & secrets → New client secret. Copy the Value immediately — it is not shown again. (Do not use the Secret ID.)
Go to API permissions → Add a permission → Microsoft Graph → Delegated. Add openid, profile, email, offline_access, and User.Read, then click Grant admin consent. Without admin consent, each user is typically prompted to grant these permissions on their first login; granting admin consent approves them tenant-wide (subject to your org's policies) and avoids end-user prompts.
Your AzureBaseUrl is https://login.microsoftonline.com/<TENANT_ID>/v2.0. Reference Microsoft identity platform and OpenID Connect protocol and National clouds for non-standard endpoints.

AzureBaseUrl must end in /v2.0. Append it if missing.
For SSO Permissions Mapping:
- Create security groups in Entra and assign users.
- In the app registration, go to Token configuration → Add groups claim (or Edit if it already exists) and configure it to emit Group IDs in the ID token.
- Create a configuration file to map Entra Group IDs to Quilt roles.
Proceed to Enabling SSO.

Okta

Go to Okta > Admin > Applications > Applications
Click Create App Integration. A new modal window opens.
Assign Sign-in method radio button to OIDC - OpenID Connect.
Assign Application type radio button to Web Application.
Click the Next button.
Rename the default App integration name to Quilt or something distinctive for your organization to identify it.
Add the Quilt logo for user recognition.
Configure the new web app integration as follows:
1. For Grant type check the following: Authorization Code, Refresh Token, and Implicit (hybrid).
  
  Important: Refresh Token must be checked. Without it, the Quilt registry cannot complete the sign-in flow and will return a 401 error.
2. To the Sign-in redirect URIs add <QuiltWebHost>/oauth-callback URL.
3. Leave the Allow wildcard * in the login URI redirect checkbox unchecked unless you need wildcard redirect URIs (e.g., for multiple subdomains). Note that wildcards only match a single subdomain level: *.example.com matches app.example.com but NOT app.dev.example.com.
4. Optionally add to the Sign-out redirect URIs (if desired by your organization).
5. Uncheck "Enable immediate access" (also called Federation Broker Mode). This setting is on by default and will cause SSO to fail with access_denied — Identity Provider: Unknown. When unchecked, you can assign users directly.
6. For the Assignments > Controlled Access selection, choose the option desired by your organization. Ensure at least one user or group is assigned to the app.
Once you click the Save button you will have a new application integration to review.
1. If it's undefined, update the Initiate login URI to your <QuiltWebHost> URL.
2. Copy the Client ID, Secret, and Base URL to a safe place
Configure the authentication policy. Go to Security > Authentication Policies and check which policy your new app is assigned to. The default policy ("Any two factors") requires MFA, which will block sign-in unless all users have MFA enrolled. Create or use a policy that allows password-only authentication. When creating a new policy, also edit the Catch-all Rule — it defaults to 2 factor types.
Go to Okta > Security > API > Authorization servers
1. You should see a default entry with the Audience value set to api://default, and an Issuer URI that looks like the following:
```
<MY_COMPANY>.okta.com/oauth2/default
```
2. Click on the default authorization server. Go to the Access Policies tab and ensure there is at least one rule that grants tokens for Authorization Code flow. A policy with no rules will silently deny all token requests, causing sign-in to fail.
3. See Okta authorization servers for more.
Proceed to Enabling SSO

OneLogin

Go to Administration > Applications > Custom Connectors
Click New Connector
1. Name the connector Quilt Connector or something similar
2. Set Sign on method to OpenID Connect
3. Set Login URL to <QuiltWebHost>/oauth-callback
4. Click "Save"
Go back to Applications > Custom Connectors
Click Add App to Connector
Save the app (be sure to save it for the Organization)
Go to Applications > Applications > Your new app > SSO
1. Click SSO. Copy the Client ID, ClientSecret and Issuer URL to a safe place.
2. "Application Type" should be set to Web.
3. "Token Endpoint" should be set to POST.
Add Your new app to the users who need to access Quilt:
Proceed to Enabling SSO.

Enabling SSO

The SSO parameter names in your stack depend on how the CloudFormation template was built — not on whether you use the Console, CLI, or Terraform to deploy it. To determine which applies, look at your stack's parameters in CloudFormation:

SingleSignOnProvider dropdown present → your stack uses single-provider SSO; follow the single-provider instructions below.
GoogleAuth, AzureAuth, etc. present → your stack uses multi-provider SSO; follow the multi-provider instructions below.

Single-provider SSO

Set PasswordAuth to Enabled in the Quilt template (AWS Console > CloudFormation > Quilt stack > Update > Use current template > Next > Specify stack details), then select your provider from the SingleSignOnProvider dropdown (Google, Okta, OneLogin, or Azure).

Use the following settings for the remaining parameters:

CFT Parameter	Google SSO	Okta SSO	OneLogin SSO	Azure SSO
`SingleSignOnClientId`	Client ID	Client ID	Client ID	Application (client) ID
`SingleSignOnClientSecret`	Client secret	Secret	ClientSecret	Client secret Value
`SingleSignOnBaseUrl`	N/A	Base URL	Issuer URL	AzureBaseUrl

Be sure to set the default role as indicated above.

Multi-provider SSO

Stacks built with multi-provider SSO use per-provider parameters instead of the shared SingleSignOnProvider dropdown, allowing multiple providers to be enabled simultaneously. These parameters are passed the same way regardless of deployment method — Console, CLI, or Terraform. See Authentication Examples for examples using the Quilt IAC Terraform module.

Function	Google	Okta	OneLogin	Azure
Enable	`GoogleAuth`	`OktaAuth`	`OneLoginAuth`	`AzureAuth`
Client ID	`GoogleClientId`	`OktaClientId`	`OneLoginClientId`	`AzureClientId`
Client Secret	`GoogleClientSecret`	`OktaClientSecret`	`OneLoginClientSecret`	`AzureClientSecret`
Base URL	N/A	`OktaBaseUrl`	`OneLoginBaseUrl`	`AzureBaseUrl`

Preparing an AWS Role for use with Quilt

These instructions document how to set up an existing role for use with Quilt. If the role you want to use doesn't exist yet, create it now. For guidance creating IAM roles, see: IAM best practices, and the Principle of Least Privilege

Go to your Quilt stack in CloudFormation. Go to Outputs, then find RegistryRoleARN and copy its value. It should look something like this: arn:aws:iam::000000000000:role/stackname-ecsTaskExecutionRole.

Go to the IAM console and navigate to Roles. Select the role you want to use. Go to the Trust Relationships tab for the role, and select Edit Trust Relationship. The statement might look something like this:

{
  "Version": "2012-10-17",
  "Statement": [
    "... one or more statements"
  ]
}

Add an object to the beginning of the Statement array with the following contents:

{
  "Effect": "Allow",
  "Principal": {
    "AWS": "$YOUR_REGISTRY_ROLE_ARN"
  },
  "Action": "sts:AssumeRole"
},

Note the comma after the object. Your trust relationship should now look something like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "$YOUR_REGISTRY_ROLE_ARN"
      },
      "Action": "sts:AssumeRole"
    },
    "... whatever was here before"
  ]
}

You can now configure a Quilt Role with this role (using the Catalog's admin panel, or quilt3.admin.create_role).

S3 buckets with Service-Side Encryption using Key Management Service (SSE-KMS)

In order for Quilt to access and index buckets encrypted with SSE-KMS, you must do three things:

Add KMS Key Usage to Quilt Permission Boundary
Add Quilt Principals to KMS Key Policy
Add KMS Key Access to a Source=Quilt Role

NOTE: This will not work with the default Source=Custom Roles.

1. Add KMS Key Usage to Quilt Permission Boundary

By default, AWS does not allow anything in your account to access KMS. If you haven't done so already, create an IAM policy that explicitly enables KMS access.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "kms:Decrypt",
      "kms:GenerateDataKey"
    ],
    "Resource": "arn:aws:kms:us-west-2:111122223333:key/*"
  }
}

Go to CloudFormation > Your Quilt Stack -> Update -> Parameters and add the ARN of that IAM policy to ManagedUserRoleExtraPolicies at the bottom of the page:

If other policies are already in that field, you will need to add a comma before appending the ARN.

2. Add Quilt Principals to KMS Key Policy

In order for Quilt to index buckets with SSE-KMS, you must add certain principals to the corresponding key policy. Go to CloudFormation > Your Quilt Stack > Resources and look for IAM roles with the following logical IDs:

AmazonECSTaskExecutionRole
PkgEventsRole
PkgSelectLambdaRole
SearchHandlerRole
T4BucketReadRole
T4BucketWriteRole

Note the ARN for each of the above logical IDs and add an Allow statement similar to the following to the KMS key policy:

{
    "Effect": "Allow",
    "Principal": {
        "AWS": [
            "<RoleARN-1>",
            ...
            "<RoleARN-N>"
        ]
    },
    "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
    ],
    "Resource": "*"
}

3. Add KMS Key Access to Quilt Role

Finally, you need create a restricted policy that gives a Quilt role access to the keys for specific buckets, e.g:

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "kms:Decrypt",
      "kms:GenerateDataKey"
    ],
    "Resource": [
      "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
      "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
    ]
  }
}

You can now create a Quilt Policy from this policy using the Catalog's admin panel. Afterwards, you can attach that Policy to a user-defined Quilt Role (which has Source=Quilt in the Roles panel, as opposed to system-defined Source=Custom Roles).

Backup and Recovery

All data and metadata in Quilt is stored in S3. S3 data is automatically backed up (replicated across multiple available zones). To protect against accidental deletion or overwriting of data, we strongly recommend enabling object versioning for all S3 buckets connected to Quilt.

No data will be lost if a Quilt stack goes down. The Quilt search indexes will be automatically rebuilt when buckets are added to a new stack.

Region Failure

To protect against data loss in the event of a region failure, enable S3 Bucket Replication on all S3 buckets.

The time to restore varies with storage needs, but a <2-hour recovery time objective (RTO) and <15 minute recovery point objective (RPO) are generally possible.

To restore Quilt in your backup region:

Create a new Quilt stack from the same CloudFormation template in the backup region.
Connect the replica buckets (in the backup region) to your Quilt stack. In the Quilt catalog, select "Users and Buckets"->"Buckets" and enter the bucket information.

Emergency Maintenance

See Troubleshooting

Support

Support is available to all Quilt customers by:

online chat (in the Quilt catalog)
email to support@quilt.bio
Slack

Quilt guarantees response to support issues according to the following SLAs for Quilt Business and Quilt Enterprise customers.

Quilt Business

	Initial Response	Temporary Resolution
Priority 1	1 business day	3 business days
Priority 2	2 business days	5 business days
Priority 3	3 business days	N/A

Quilt Enterprise

	Initial Response	Temporary Resolution
Priority 1	4 business hours	1 business day
Priority 2	1 business day	2 business days
Priority 3	1 business days	N/A

Definitions

Business Day means Monday through Friday (PST), excluding holidays observed by Quilt Data.
Business Hours means 8:00 a.m. to 7:00 p.m. (PST) on Business Days.
Priority 1 means a critical problem with the Software in which the Software inoperable;
Priority 2 means a problem with the Software in which the Software is severely limited or degraded, major functions are not performing properly, and the situation is causing a significant impact to Customer's operations or productivity;
Priority 3 means a minor or cosmetic problem with the Software in which any of the following occur: the problem is an irritant, affects nonessential functions, or has minimal impact to business operations; the problem is localized or has isolated impact; the problem is an operational nuisance; the problem results in documentation errors; or the problem is any other problem that is not a Priority 1 or a Priority 2, but is otherwise a failure of the Software to conform to the Documentation or Specifications;
Temporary Resolution means a temporary fix or patch that has been implemented and incorporated into the Software by Quilt Data to restore Software functionality.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enterprise Administration

Health and Monitoring

Elasticsearch Cluster

Service Limits

External Dependencies

Advanced configuration

Setting the default role

Single sign-on (SSO)

Google

Microsoft Entra ID (Azure Active Directory)

Okta

OneLogin

Enabling SSO

Single-provider SSO

Multi-provider SSO

Preparing an AWS Role for use with Quilt

S3 buckets with Service-Side Encryption using Key Management Service (SSE-KMS)

1. Add KMS Key Usage to Quilt Permission Boundary

2. Add Quilt Principals to KMS Key Policy

3. Add KMS Key Access to Quilt Role

Backup and Recovery

Region Failure

Emergency Maintenance

Support

Quilt Business

Quilt Enterprise

Definitions

FilesExpand file tree

technical-reference.md

Latest commit

History

technical-reference.md

File metadata and controls

Enterprise Administration

Health and Monitoring

Elasticsearch Cluster

Service Limits

External Dependencies

Advanced configuration

Setting the default role

Single sign-on (SSO)

Google

Microsoft Entra ID (Azure Active Directory)

Okta

OneLogin

Enabling SSO

Single-provider SSO

Multi-provider SSO

Preparing an AWS Role for use with Quilt

S3 buckets with Service-Side Encryption using Key Management Service (SSE-KMS)

1. Add KMS Key Usage to Quilt Permission Boundary

2. Add Quilt Principals to KMS Key Policy

3. Add KMS Key Access to Quilt Role

Backup and Recovery

Region Failure

Emergency Maintenance

Support

Quilt Business

Quilt Enterprise

Definitions