S3 Configuration
Configuration parameters for integrating your Onyxia service with S3.
The installation guide provides instructions on how to set up Minio with a basic configuration. However, you may want more control or need to connect to a different S3-compatible system.
Below are all the available configuration options.
onyxia:
api:
regions: [
{
# ...
data: {
S3 : { ... } # ...See expected format below
}
}
]type S3 = {
/**
* The URL of the S3 server.
* Examples: "https://minio.lab.sspcloud.fr" or "https://s3.amazonaws.com".
*/
URL: string;
/**
* The AWS S3 region. This parameter is optional if you are configuring
* integration with a MinIO server.
* Example: "us-east-1"
*/
region?: string;
/**
* This parameter informs Onyxia how to format file download URLs for the configured S3 server.
* Default: true
*
* Example:
* Assume "https://minio.lab.sspcloud.fr" as the value for region.data.S3.URL.
* For a file "a/b/c/foo.parquet" in the bucket "user-bob":
*
* With pathStyleAccess set to true, the download link will be:
* https://minio.lab.sspcloud.fr/user-bob/a/b/c/foo.parquet
*
* With pathStyleAccess set to false (virtual-hosted style), the link will be:
* https://user-bob.minio.lab.sspcloud.fr/a/b/c/foo.parquet
*
* For MinIO, pathStyleAccess is typically set to true.
* For Amazon Web Services S3, is has to be set to false.
*/
pathStyleAccess?: boolean;
/**
* Defines where users are permitted to read/write S3 files,
* specifying the allocated storage space in terms of bucket and object name prefixes.
*
* Mandatory unless data.S3.sts is not defined then it's optional.
*
* Example:
* For a user "bob" in the "exploration" group, using the configuration:
*
* Shared bucket mode, all the users share a single bucket:
* "workingDirectory": {
* "bucketMode": "shared",
* "bucketName": "onyxia",
* "prefix": "user-",
* "prefixGroup": "project-"
* }
*
* In this configuration Onyxia will assumes that Bob has read/write access to objects starting
* with "user-bob/" and "project-exploration/" in the "onyxia" bucket.
*
* Multi bucket mode:
* "workingDirectory": {
* "bucketMode": "multi",
* "bucketNamePrefix": "user-",
* "bucketNamePrefixGroup": "project-",
* }
*
* In this configuration Onyxia will assumes that Bob has read/wite access to the entire
* "user-bob" and "project-exploration" buckets.
*
* If STS is enabled and a bucket doesn't exist, Onyxia will try to create it.
*/
workingDirectory?:
| {
bucketMode: "shared";
bucketName: string;
prefix: string;
prefixGroup: string;
}
| {
bucketMode: "multi";
bucketNamePrefix: string;
bucketNamePrefixGroup: string;
};
/**
* Defines a list of S3 directory bookmarks to display in the user's file explorer interface.
*
* Bookmarks can be:
* - Static: shown to all users.
* - Dynamic: shown only if specific conditions based on the user's identity token are met.
*
* Each bookmark must define:
* - `fullPath`: The absolute S3 path to the bookmarked folder.
* - `title`: The display title, supporting dynamic content via template variables.
* - `description` (optional): A short description of the bookmark.
* - `tags` (optional): An array of LocalizedString tags for UI categorization.
*
* For static bookmarks:
* - Set `claimName` to `undefined` (or omit it entirely).
* - The bookmark is shown to all users.
*
* For dynamic bookmarks:
* - Set `claimName` to the name of a claim (e.g., `"groups"`) from the user's **ID token**.
* - The ID token is the one issued by the **OIDC configuration associated with the S3 client** (i.e., from `sts.oidcConfiguration`).
* - `includedClaimPattern` is a regular expression that must match at least one value in the specified claim for the bookmark to be shown.
* - `excludedClaimPattern` is a regular expression that, if matched by any value in the claim, causes the bookmark to be ignored.
* - If a `claimValue` matches both, exclusion takes precedence (i.e., the bookmark is not shown).
*
* Template placeholders:
* - `$1`, `$2`, ...: inserts corresponding capture groups from `includedClaimPattern` (useful for custom rendering in `fullPath`, `title`, `description`, or `tags`).
*
* 🔁 Example (static):
* ```json
* {
* "bookmarkedDirectories": [
* {
* "fullPath": "data/public",
* "title": {
* "fr": "Données publiques",
* "en": "Public Data"
* },
* "description": {
* "fr": "Dossier partagé contenant des jeux de données publics.",
* "en": "Shared folder containing public datasets."
* },
* "tags": [
* {
* "fr": "lecture seule",
* "en": "read-only"
* }
* ]
* }
* ]
* }
* ```
*
* 🔁 Example (dynamic):
* ```json
* {
* "bookmarkedDirectories": [
* {
* "fullPath": "group-$1/",
* "claimName": "groups",
* "includedClaimPattern": "^group-(.*)$",
* "excludedClaimPattern": "^group-secret$",
* "title": "Group: $1",
* "description": "Files accessible to group $1",
* "tags": ["group", "$1"]
* }
* ]
* }
* ```
*/
bookmarkedDirectories?: ({
fullPath: string;
title: LocalizedString;
description: LocalizedString | undefined;
tags: LocalizedString[] | undefined;
} & (
| { claimName: undefined }
| {
claimName: string;
includedClaimPattern: string;
excludedClaimPattern: string;
}
))[];
/**
* Configuration for Onyxia to dynamically request S3 tokens on behalf of users.
* Enabling S3 allows users to avoid manual configuration of a service account via the Onyxia interface.
*/
sts?: {
/**
* The STS endpoint URL of your S3 server.
* For integration with MinIO, this property is optional as it defaults to region.data.S3.URL.
* For Amazon Web Services S3, set this to "https://sts.amazonaws.com".
*/
URL?: string;
/**
* The duration for which temporary credentials are valid.
* AWS: Maximum of 43200 seconds (12 hours).
* MinIO: Maximum of 604800 seconds (7 days).
* Without this parameter, Onyxia requests 7-day validity, subject to the S3 server's policy limits.
*/
durationSeconds?: number;
/**
* Optional parameter to specify RoleARN and RoleSessionName for the STS request.
*
* Example:
* "role": {
* "roleARN": "arn:aws:iam::123456789012:role/onyxia",
* "roleSessionName": "onyxia"
* }
*/
role?: {
roleARN: string;
roleSessionName: string;
};
/**
* See: https://docs.onyxia.sh/admin-doc/openid-connect-configuration#oidc-configuration-for-services-onyxia-connects-to
*/
oidcConfiguration?: OidcConfiguration;
};
};Last updated
Was this helpful?