Provides the foundation for integrating with S3 and Bynder and a sample component for using assets in the Pages app.
magnolia-external-dam-bynder
Provides a default implementation to connect to Bynder.
magnolia-external-dam-s3
Provides a default implementation to connect to Amazon S3.
Installing with Maven
Bundled modules are automatically installed for you.
If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement> section and your webapp’s <dependencies> section.
If the module is unbundled but the parent POM manages the version, add the following to your webapp’s <dependencies> section.
Make sure that you have acquired appropriate permissions for the service in the AWS IAM Management Console.
Minimum required permissions
To use Magnolia with AWS S3, the following permissions are required.
Based on your project requirements, you need to decide which specific S3 buckets these permissions apply to and specify them in your policy’s Resource section.
The example below shows permissions granted to all buckets; you should implement a more restrictive policy.
Grant access for the list of bucket and object-level permissions.
2
List the AWS S3 buckets to which you want these permissions to apply.
In this example, the permissions apply to all buckets; you should implement a more restrictive policy based on your specific requirements.
Buckets created via the external DAM connector don’t have ACLs and have blocked public access;
you must adjust them to enable public access.
Configuring the AWS connection
The magnolia-aws-foundation module handles all Amazon connections from Magnolia.
It’s installed automatically by Maven when you install any AWS-dependent module.
To use AWS in Magnolia, you must have a working AWS account.
You need AWS credentials to connect AWS to Magnolia. Credentials consist of:
AWS access key ID
AWS secret access key
Optionally, a session token (when using the AWS default credential provider chain)
Generate the key in the security credentials section of the Amazon IAM Management Console.
In the navigation bar on the upper right, choose your user name, and then choose My Security Credentials.
You can store your AWS credentials using:
Magnolia Passwords app (session tokens aren’t supported in the app)
AWS default credential provider chain
Using the Passwords app
Add your generated access key ID and the secret access key to your Magnolia instance in the Passwords app using the following names and order:
📁 aws-credentials
aws_access_key_id
aws_secret_access_key
Using the AWS default credential provider chain
The AWS SDK uses a chain of sources to look for credentials in a specific order.
For more information, see Default credentials provider chain.
For a more secure implementation using the default credential provider chain, we recommend using a session token, which expires, rather than a permanent user token.
Disable Magnolia’s internal credential handling by doing one of the following:
Disables Magnolia’s internal credential handling using JVM properties.
2
JVM properties to inject environment variables containing the AWS credentials.
Ensure that your environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN are set.
By default, all the buckets in the S3 account you connect to are displayed.
If you don’t want to display all your buckets, you can configure a whitelist in the Resource files app using regex.
If you want to restrict access to a single bucket either because it’s used in different use cases or for some confidentiality-related reasons, you can add a bucket prefix that grants access only to that specific bucket without revealing its actual path which might contain unwanted access information. This way the user will see the bucket and folders will be seen as the only folders in the Magnolia instance.
To make use of the filter, simply add the following bucket prefix to your config.yaml file:
You can use the token value directly in the yaml configuration or add the permanent token to your Magnolia instance in the Password manager app and reference the path in the configuration.
For example:
bynder-credentials
bynder_permanent_token
Connecting
Add your connection configuration under /dam-bynder/config.yaml.
Configuring a single asset provider for link fields
You can configure a link field to limit your users to selecting assets from only one asset provider.
This is possible from External DAM 1.0.7 (DAM module 3.0.8). Previously, you had to use the aggregated damLinkField and users had to choose from all the enabled asset providers.
This example shows a dialog definition with three link fields, each limited to different asset providers:
This connector pack uses Caffeine, a high-performance Java cache library, to manage caching for external assets via a Magnolia helper module called magnolia-addon-commons-cache.
For Bynder and S3 caching, you can specify the behavior of the caches. Essentially, you can configure all the parameters available in CaffeineSpec.
For example:
Set a maximum cache size.
Define how often the cache expires.
Additionally, you can:
Enable or disable the cache.
You configure caching through decoration under /<dam-connector>/decorations/addon-commons-cache/config.yaml.
Note that the Bynder API may be very slow in some regions. For example, one image upload may take up to 20 seconds in EU regions. This may cause some actions to fail in the Magnolia UI and the cache to be invalidated.
If you want to flush the cache, you can either set the cache expiry to a very short time (see above) or configure a script in the Groovy app to flush the cache manually. For example:
Configuring the proxy service to protect private asset URLS
To protect the URLs of private Bynder assets rendered in Magnolia, you must use the proxy service provided.
The proxy service is also required if you want to use Bynder image variations.
The proxy service enforces security by generating a Magnolia URL that hides the private Bynder URL.
If you do not use the proxy service, private Bynder URLS are exposed in published Magnolia pages for example.
When using the proxy, if you want to make a Bynder asset public, for example an image asset used in the Pages app, you must publish the image as well as the page in Magnolia.
You can enable or disable the proxy service using the proxyMode parameter. The functionality is provided via the BynderAssetRenderer.
The proxy service is only available with Magnolia 6.2.6+. If you use an earlier version of Magnolia Core, you must disable the proxy service.
When set to true, the proxy mode is enabled. The Bynder asset generates a Magnolia URL to hide the Bynder URL and the asset is served through the Magnolia instance.
When set to false, the proxy mode is disabled. The Bynder asset generates a Bynder URL and the asset is served directly by Bynder. Private Bynder URLs may be exposed.
Using Bynder image derivatives
You must enable proxy mode to use Bynder derivatives in Magnolia.
Bynder provides image derivatives (referred to as variations or renditions in Magnolia) by default, such as:
Only image type Bynder asset derivatives can be used in Magnolia.
To see which derivatives are available for a given Bynder image, look in the Size variations field in the asset details view:
Magnolia falls back to the original derivative if the requested derivative is unavailable.
Retrieving Bynder derivatives differs from using typical Magnolia image variations:
You do not have to define image variations in a theme when using Bynder derivatives.
In your template script, instead of the Magnolia asset itemKey or renditionName, you use the Bynder derivative name (small, medium, large, original and so on).
For more information about Bynder derivatives, we recommend the following pages in the Bynder documentation:
This section provides instructions specific to configuring the S3 connector.
Configuring the maximum search time for S3
You can configure the maximum time Magnolia Periscope spends searching for S3 assets to be displayed in the Magnolia interface when a user searches for an asset in the Find Bar.
dam-s3/config.yaml
maxSearchTimeInMilis:10000Copy
Property
Description
maxSearchTimeInMilis
optional
The maximum time Magnolia Periscope spends searching for S3 assets. By default, the maximum search time is 10 seconds.
For example: maxSearchTimeInMilis: 10000
Configuring presigned URLs to enable previewing for S3 assets
When you upload assets via Magnolia to S3, they are set to private by default. If you want to keep the preview functionality available, you must use presigned urls.
dam-s3/config.yaml
presignedSignatureDurationInMinutes:60Copy
Property
Description
presignedSignatureDurationInMinutes
optional
Determines how long a presigned URL is valid.
We recommend that the duration is at least equal to the expiration of the caches set for s3-objects`, s3-pages and s3-count. Otherwise, the presigned URL may be not valid while it is still cached.
For example: presignedSignatureDurationInMinutes: 60
Configuring the AWS regions list
When creating an S3 bucket in the Assets app, only AWS-enabled regions are displayed to users.
AWS S3 bucket names are globally unique, meaning no two buckets can have the same name.
If you try to create a bucket and receive an error stating the bucket already exists, it means that the bucket name is already in use, either by you or someone else.
If your users want to use a disabled region, you must enable it first in AWS as described in Managing AWS Regions in the AWS documentation.
Then you must remove the newly enabled region from the list of disabled regions in the Magnolia configuration so that it appears in the chooser.
Configuring the thread pool for S3 search operations
You can control the allocation of system resources for handling search requests in the S3 connector.
dam-s3/config.yaml
searchThreadPoolIdleLiveTime:30LCopy
Property
Description
searchThreadPoolIdleLiveTime
optionaldefault is 30L
Sets the time (in seconds) that the thread is held idle in the pool before being terminated.
This helps to optimize resource usage by reducing the number of idle threads when they’re not needed.
Configuring the number of child objects when renaming folders
When you rename a folder, all the child objects are retrieved via API and aligned accordingly.
The maxKeysRenaming property determines the maximum number of keys returned by the API call.
The higher the value of the property, the longer the action takes to complete.
dam-s3/config.yaml
maxKeysRenaming:1000Copy
Property
Description
maxKeysRenaming
optional, default is 1000
The maximum number of keys returned by the API call retrieving children objects from S3 during folder renaming.
Valid range is [100-1000]
Storing asset width and height in metadata
When you create an asset in Magnolia, the storeWidthAndHeight property determines if the width and height of the asset are stored in the corresponding S3 item as metadata.
dam-s3/config.yaml
storeWidthAndHeight:falseCopy
Property
Description
storeWidthAndHeight
optional, default is false
Set to true to store the width and height of an asset created in Magnolia in the corresponding S3 item as metadata.
Hiding the S3 bucket name
The hideBucket property determines if the S3 bucket name is displayed in the Assets app or not.
When set to true, the bucket name no longer appears in the app folder names and asset descriptions.
dam-s3/config.yaml
hideBucket:falseCopy
Property
Description
hideBucket
optional, default is false
Set to true to hide the S3 bucket name in the Assets app.
Usage
The magnolia-external-dam submodule provides a sample Text and external image page component so that editors and marketers can select and use external assets in the Pages app.
If an asset is uploaded into the DAM app that has been compromised, for example, an image file containing malicious code, an error message is displayed.
Release history
External DAM module 1.1.10
Released on March 13, 2025.
This maintenance release fixes a bug for customers using Bynder:
Bynder: Generated @link for assetReferenceResolver changes the extension if the asset is not an image. (EXTDAM-516)
External DAM module 1.1.9
Released on November 22, 2024.
We keep the details of security fixes private in line with our security policy.
Contact our Support team if you need more information.
This maintenance release fixes a bug for customers using S3:
AWS best practices for SDK client management not followed. (EXTDAM-511)
External DAM module 1.1.8
Released on November 6, 2024.
This maintenance release fixes a bug for customers using S3:
Incorrect REST responses from missing S3 images.
(EXTDAM-482)
External DAM module 1.1.7
Released on August 13, 2024.
This maintenance release fixes a bug for customers using S3:
S3 search thread pool doesn’t shut down. (EXTDAM-433)
This maintenance release fixes a bug for customers using Bynder Assets with associated links that contain special characters. With this fix, special characters are encoded to avoid loading issues. (EXTDAM-327)
External DAM module 1.1.1 and 1.0.9
Released on December 22, 2021.
This maintenance release fixes a bug for Cloud customers using the delivery endpoint where, when working with S3 as your external asset management solution, the time.now timestamp was appended to the URL.
External DAM module 1.1.0
Released on November 15, 2021.
This release brings a number of improvements and bug fixes.
Support for Bynder image derivatives
Bynder provides different image derivatives (referred to as image variations in Magnolia) such as large, medium, small.
This functionality is now integrated into Magnolia and can be used via the DAM templating function (damfn).
For example, to retrieve the small Bynder derivative:
damfn.getAssetLink(bynderAsset, "small")Copy
Bynder derivatives do not function in the same way as standard Magnolia image variations as described in Defining image variations. You do _not have to configure the theme to use Bynder derivatives.
We have improved S3 caching of bucket regions in Magnolia to fix an issue causing performance problems when using the delivery endpoint for Cloud customers.
When selecting external assets, you can now use a filter at the top of the Name column for both Bynder and S3 to reduce the number of assets displayed.
Note that in the case of S3, you must open the bucket of your choice before filtering within it. Filtering at the root level does not produce results.
AWS Regions are listed by code and unavailable regions are not displayed
When creating an S3 bucket in the Assets app, the list of regions available are ordered alphabetically and unavailable regions are no longer displayed.
Previously the DAM Connector Pack provided a sample Text and External Image component in the Travel demo to help get users started using external assets in pages.
This sample component has now been removed. We recommend you use the standard MTK Text and Image component instead.
Sorting by name does not work for S3 and Bynder. EXTDAM-150
External DAM module 1.0.8
Released on Oct 27, 2021.
This release improves S3 caching of bucket regions in Magnolia to fix an issue causing performance problems when using the delivery endpoint for Cloud customers.
This release brings a number of improvements and bug fixes.
Proxy service to protect private asset URLS (Bynder)
To protect the URLs of private Bynder assets rendered in Magnolia, you must use the proxy service provided.
When using the proxy, if you want to make a Bynder asset public, for example an image asset used in the Pages app, you must publish the image as well as the page in Magnolia.
You can enable or disable the proxy service using the proxyMode parameter.
The proxy service is only available with Magnolia Core 6.2.6. If you use an earlier version of Magnolia Core, you must disable the proxy service.
When you upload assets via Magnolia to S3, they are set to private by default.
If you want to keep the preview functionality available, you must use presigned urls.
Bug fix: User sessions overlap when browsing S3 assets
When you have two or more users trying to browse assets in S3 the sessions can overlap each other. Users may enter the app in a folder opened by another user in another session instead of the top level folder.
This release brings compatibility for Magnolia 6.2.4 and a number of improvements and bug fixes.
We have discovered an issue with Bynder SDK version 2.2.4 and External DAM 1.0.2 that blocks users from uploading assets to Bynder via Magnolia.
Do not use this release if you are a Bynder connector user. External DAM 1.0.3 corrects the issue and will be released soon.
Improved handling of large numbers of S3 assets
Magnolia has improved how large numbers (thousands) of assets in a given S3 folder are rendered.
Magnolia has a specialized method that counts the total number of assets in your S3 system instead of creating the corresponding internal objects. Since S3 only allows batches of 1000 assets to be retrieved in a given call, we iterate as many API calls as necessary to retrieve the assets stored in S3.
For example, Magnolia must make 100 API calls to retrieve 100 000 assets. Depending on your internet bandwidth, cache and other factors, this could take around 1 minute to complete. For better response times, we recommend that you store a maximum of 10 000 assets per S3 bucket.
You can configure the maximum time Magnolia Periscope spends searching for S3 assets to be displayed in the Magnolia interface using a new parameter called maxSearchTimeInMilis under dam-s3/config.yaml.
By default, the maximum search time is 10 seconds (maxSearchTimeInMilis: 10000).
The third-party versions listed below are the versions Magnolia has
developed and tested against. If you don’t see a particular version
listed, it simply means that we do not routinely test on it.
If you are using another version of the third-party tool and run into
compatibility issues, please contact our Support.