authentik/website/docs/installation/storage-s3.md

title
S3 storage setup

Preparation

First, create a user on your S3 storage provider and get access credentials for S3, hereafter referred as access_key and secret_key.

You'll also need to know which endpoint authentik is going to use to access the S3 API, hereafter referred as https://s3.provider.

The bucket in which authentik is going to store files is going to be called authentik-media. You may need to change this name depending on your S3 provider limitations. Also, we're suffixing the bucket name with -media as authentik currently only stores media files, but may use other buckets in the future.

The domain used to access authentik is going to be referred to as authentik.company.

You will also need the AWS CLI.

S3 configuration

Bucket creation

Let's create the bucket in which authentik is going to store files:

AWS_ACCESS_KEY_ID=access_key AWS_SECRET_ACCESS_KEY=secret_key aws s3api --endpoint-url=https://s3.provider create-bucket --bucket=authentik-media --acl=private

If using AWS S3, you can omit the --endpoint-url option, but may need to specify the --region option. If using Google Cloud Storage, refer to its documentation on how to create buckets.

The bucket ACL is set to private, although that is not strictly necessary, as an ACL associated with each object stored in the bucket will be private as well.

CORS policy

Next, let's associate a CORS policy to the bucket, to allow the authentik web interface to show images stored in the bucket.

First, save the following file locally as cors.json:

{
    "CORSRules": [
        {
            "AllowedOrigins": ["authentik.company"],
            "AllowedHeaders": ["Authorization"],
            "AllowedMethods": ["GET"],
            "MaxAgeSeconds": 3000
        }
    ]
}

If authentik is accessed from multiple domains, you can add them to the AllowedOrigins list.

Let's apply that policy to the bucket:

AWS_ACCESS_KEY_ID=access_key AWS_SECRET_ACCESS_KEY=secret_key aws s3api --endpoint-url=https://s3.provider put-bucket-cors --bucket=authentik-media --cors-configuration=file://cors.json

Configuring authentik

Add the following to your .env file:

AUTHENTIK_STORAGE_MEDIA_BACKEND=s3
AUTHENTIK_STORAGE_MEDIA_S3_ACCESS__KEY=access_key
AUTHENTIK_STORAGE_MEDIA_S3_SECRET__KEY=secret_key
AUTHENTIK_STORAGE_MEDIA_S3_BUCKET__NAME=authentik-media

If you're using AWS S3 as your S3 provider, add the following:

AUTHENTIK_STORAGE_MEDIA_S3_REGION=us-east-1  # Use the region of the bucket

If you're not using AWS S3 as your S3 provider, add the following:

AUTHENTIK_STORAGE_MEDIA_S3_ENDPOINT=https://s3.provider
AUTHENTIK_STORAGE_MEDIA_S3_CUSTOM__DOMAIN=s3.provider/authentik-media

The ENDPOINT setting specifies how authentik talks to the S3 provider.

The CUSTOM__DOMAIN setting specifies how URLs are constructed to be shown on the web interface. For example, an object stored at application-icons/application.png with a CUSTOM__DOMAIN setting of s3.provider/authentik-media will result in a URL of https://s3.provider/authentik-media/application-icons/application.png. You can also use subdomains for your buckets depending on what your S3 provider offers: authentik-media.s3.provider. Whether HTTPS is used is controlled by the AUTHENTIK_STORAGE_MEDIA_S3_SECURE__URLS which defaults to true.

For more control over settings, refer to the configuration reference

Migrating between storage backends

The following section assumes that the local storage path is /media and the bucket name is authentik-media. It also assumes you have a working aws CLI that can interact with the bucket.

From file to s3

Follow the setup steps above, and then migrate the files from your local directory to s3:

aws s3 sync /media s3://authentik-media

From s3 to file

aws s3 sync s3://authentik-media /media