External Azure storage

The Hybrid Assets module lets you integrate external Azure Blob Storage assets into Magnolia.

Prerequisites

Magnolia 6.2
An Azure Blob Storage account with:
- Account name
- Account key or Shared Access Signature (SAS) token
- Container name
A light module in your Magnolia instance for decorations

Step 1: Configure Azure credentials

Store your Azure credentials securely using the Passwords app.

Open the Passwords app in Magnolia.
Add the following entries under a node (e.g., /azure-credentials):
- accountkey: Your Azure account key or SAS token.
- sig: Your Azure Shared Access Signature (if applicable).
Save the entries.

Step 2: Update `config.yaml` for Hybrid Assets

In your light module, create or edit /modules/hybrid-assets/config.yaml to reference the credentials and configure the Azure store and reference factory.

For a full list of properties for Azure, see Azure external content store.

sig: 'azure-credentials/sig' (1)
accountKey: 'azure-credentials/accountkey' (1)
displayPdfAndVideoPreview: false
referenceFactory: (2)
  class: info.magnolia.dam.hybrid.mapping.SimpleReferenceFactory
  mappings:
    referenceAzure:
      class: info.magnolia.dam.hybrid.mapping.TransformReferenceMapping
      referenceTemplate: azure://hybridassets/test/#{baseName}.${extension} (3)
      voters: (4)
        mgnlDam:
          class: info.magnolia.dam.hybrid.voters.NodeWorkspaceVoter
stores:
  storeAzure: (5)
    class: info.magnolia.dam.hybrid.store.AzureAssetStore
    description: Azure Blob asset store
    enabled: true (6)
    baseUrl: 'blob.core.windows.net'
    endpointSuffix: 'core.windows.net'
    accountName: 'hybridAssets' (7)
    container: 'example-container' (8)
    pageSize: 10
    signedPermissions: 'racwd1' (9)
    signedStartTime: '2025-05-01T07:18:00Z' (10)
    signedExpiryTime: '2025-05-11T07:18:00Z' (10)
    serviceVersion: '2023-11-02'
    signedResource: 'c'

1	Paths to credentials stored in the Passwords app.
2	The `referenceFactory` defines how Azure assets are referenced in Magnolia using a `referenceTemplate`.
3	The `referenceTemplate` specifies the storage URL format for assets. Ensure the `referenceTemplate` generates unique URLs to avoid overwriting assets. For advanced mapping options, see External reference factory.
4	`voters` determine when the mapping applies. The `NodeWorkspaceVoter` ensures assets are in the DAM workspace.
5	`storeAzure` configures the Azure Blob Storage connection.
6	Ensure `enabled` is `true`.
7	`accountName` is your Azure storage account name.
8	`container` is the Azure container holding your assets.
9	`signedPermissions` are the permissions for the SAS token (e.g., `racwd1` for read, add, create, write, delete, list).
10	`signedStartTime` and `signedExpiryTime` specify the validity period for the SAS token (adjust based on your token).

Optional parameters like signedResourceTypes or signedServices can be added for advanced setups. See External content stores for details.

Azure external content store

The Hybrid Assets module also supports working with external Azure content storage: info.magnolia.dam.hybrid.store.AzureAssetStore.

The following are configurable properties of a Azure external content store:

Property Description

Property	Description
`class`	required Must be `info.magnolia.dam.hybrid.store.AzureAssetStore`.
`enabled`	required Set to `true`.
`description`	optional A brief description of the external content store.
`baseURL`	required Base URL to build connection string to REST API.
`endpointSuffix`	required The endpoint suffix to Azure storage.
`accountName`	required Azure account name.
`container`	required Azure container name.
`pageSize`	required Max results per request, default is 10.
`plusHours`	required Expiration time for token when getting blob url, default value is 1 hour.
`signedProtocol`	required The SAS can only be used over HTTPS, default value is 'https'.
`serviceVersion`	required Specifies the version of the service.
`signedPermissions`	required Grants read, write, delete, list, add, create, update, and process permissions.
`signedStartTime`	required Signed start time.
`signedExpiryTime`	required Signed expiry time.
`signedResource`	optional Grants access to service, container, and object.
`signedResourceTypes`	optional Grants access to service, container, and object.
`signedServices`	optional Grants access to the Blob service.
`requestParams`	optional More parameters that are optional and can be put in a dynamic requestParams configuration.

class

required

Must be info.magnolia.dam.hybrid.store.AzureAssetStore.

enabled

required

Set to true.

description

optional

A brief description of the external content store.

baseURL

required

Base URL to build connection string to REST API.

endpointSuffix

required

The endpoint suffix to Azure storage.

accountName

required

Azure account name.

container

required

Azure container name.

pageSize

required

Max results per request, default is 10.

plusHours

required

Expiration time for token when getting blob url, default value is 1 hour.

signedProtocol

required

The SAS can only be used over HTTPS, default value is 'https'.

serviceVersion

required

Specifies the version of the service.

signedPermissions

required

Grants read, write, delete, list, add, create, update, and process permissions.

signedStartTime

required

Signed start time.

signedExpiryTime

required

Signed expiry time.

signedResource

optional

Grants access to service, container, and object.

signedResourceTypes

optional

Grants access to service, container, and object.

signedServices

optional

Grants access to the Blob service.

requestParams

optional

More parameters that are optional and can be put in a dynamic requestParams configuration.

Step 3: Decorate the SubApp for linking Azure content

To enable the "Link external content" action for Azure assets, decorate the Hybrid Assets subApp.

Create or edit /modules/hybrid-assets/hybridAssets.subApps.yaml in your light module.

Override the linkContent action to use the linkAzureContent dialog.

jcrBrowser:
  actions:
    linkContent: !override
      icon: icon-link
      class: info.magnolia.ui.dialog.actions.OpenDialogActionDefinition
      dialogId: hybrid-assets-advanced:linkAzureContent
      availability:
        root: true
        writePermissionRequired: true
        rules:
          notDeleted:
            $type: jcrIsDeletedRule
            negate: true

Step 4: Register the light module

Ensure your light module is registered by including a module.yaml file in the root of your light module. This file ensures Magnolia applies your decorations in the correct order.

version: 1.0
dependencies:
  hybrid-assets-advanced:
    version: "*"

Step 5: Test your configuration

Restart your Magnolia instance.
In the Hybrid Assets app, use the Link external content action to connect to Azure assets.
Verify that assets from your Azure container appear and can be linked.

Troubleshooting

Credentials error: Ensure accountKey and sig match the Passwords app entries.
Assets not loading: Check accountName, container, and SAS token validity (signedStartTime, signedExpiryTime).
Action not available: Confirm the hybridAssets.subApps.yaml decoration is applied correctly.
Asset conflicts: Ensure the referenceTemplate generates unique URLs to avoid overwriting assets. See External reference factory for guidance on unique templates.

For advanced users

For custom reference mappings, voters, or additional Azure store parameters, refer to External reference factory.

External Azure storage

Prerequisites

Step 1: Configure Azure credentials

Step 2: Update config.yaml for Hybrid Assets

Azure external content store

Step 3: Decorate the SubApp for linking Azure content

Step 4: Register the light module

Step 5: Test your configuration

Troubleshooting

For advanced users

Location

Main doc sections

Step 2: Update `config.yaml` for Hybrid Assets