Connecting to Azure Blob Storage

Overview

Azure Blob Storage connections allow you to browse, read, write, and manage files stored in Azure Blob Storage containers directly from the MagicSuite Files interface. Files stored in Azure Blob Storage appear alongside your other file sources like SharePoint, SFTP, and Git repositories.

Prerequisites

• An Azure subscription with at least one Storage Account
• Appropriate permissions to access the storage account (Storage Blob Data Contributor or higher)
• Connection credentials (see Authentication Methods below)

Creating an Azure Blob Storage Connection

1. Navigate to Admin > Connections
2. Click Add Connection
3. Select Azure Blob Storage from the Connection Type dropdown
4. Enter a Name for your connection (this will appear as the folder name in the file explorer)
5. Enter the URL in the format: https://ACCOUNTNAME.blob.core.windows.net
6. Enter your credentials (see Authentication Methods below)
7. Optionally, enter Configuration JSON to specify a container or path prefix
8. Click Save

Authentication Methods

MagicSuite supports three authentication methods for Azure Blob Storage. The system automatically detects which method to use based on your credentials.

Method 1: Connection String

The simplest method - use a full Azure connection string.

How to obtain: Azure Portal > Storage Account > Access keys > Copy "Connection string"

Method 2: Account Name + Account Key

Use the storage account name and access key separately.

How to obtain: Azure Portal > Storage Account > Access keys > Copy "Key"

Method 3: Azure AD (Service Principal)

Use Azure Active Directory authentication with a service principal for enhanced security.

{
  "TenantId": "your-tenant-id",
  "StorageAccountName": "mystorageaccount"
}

How to obtain:

1. Create an App Registration in Azure AD
2. Generate a Client Secret for the app
3. Assign the "Storage Blob Data Contributor" role to the app on your storage account

Configuration Options

The optional Configuration field accepts JSON with the following properties:

Example: Show all containers

{}

or leave the Configuration field empty.

Example: Show contents of a specific container

{
  "ContainerName": "reports"
}

Example: Show only files under a specific path

{
  "ContainerName": "documents",
  "PathPrefix": "2024/quarterly-reports"
}

How Folders Work

Azure Blob Storage is a flat storage system (no real directories). MagicSuite emulates folders by:

• Virtual folders: Blob names containing / are displayed as a folder hierarchy. For example, documents/reports/file.pdf appears as folder "documents" containing folder "reports" containing "file.pdf".
• Creating folders: When you create a new folder, a hidden placeholder file (.placeholder) is created to represent the empty folder.
• Deleting folders: Deleting a folder removes all blobs with that path prefix.
• Deleting containers: When you delete a root-level folder (which is an Azure container), Azure processes the deletion asynchronously in the background. This can take up to two minutes or more, even though the folder disappears from the list immediately. During this time, you cannot create a new folder with the same name — see Troubleshooting below for details.

Naming Rules

Azure Blob Storage enforces strict naming rules for containers, files, and folders. Names that violate these rules will be rejected with an InvalidResourceName error. The rules differ depending on the type of resource.

Container Names

Container names have the strictest rules because the name becomes part of the storage URL (e.g. https://myaccount.blob.core.windows.net/my-container). The following rules apply:

• Must be between 3 and 63 characters long
• Must start and end with a lowercase letter or number
• Can contain only lowercase letters, numbers, and the hyphen (-) character
• Every hyphen must be immediately preceded and followed by a letter or number — consecutive hyphens are not allowed
• No uppercase letters, spaces, underscores, or special characters

File and Blob Names

File (blob) names are more flexible than container names:

• Must be between 1 and 1,024 characters long
• Can contain any combination of characters
• Names are case-sensitive (Report.pdf and report.pdf are different files)
• The forward slash (/) acts as a folder separator
• Avoid ending names with a dot (.), forward slash (/), or backslash (\)
• Control characters (0x00 to 0x1F) and certain Unicode code points (e.g. \uE000) are not allowed
• Reserved URL characters must be properly escaped (this is handled automatically by MagicSuite)

Folder (Virtual Directory) Names

Because Azure Blob Storage uses virtual folders (see How Folders Work above), folder names follow blob naming rules with a few additional considerations:

• Can contain any combination of characters (more permissive than container names)
• Must be at least 1 character long and no more than 1,024 characters
• Names are case-sensitive
• Avoid ending folder names with a dot (.) or backslash (\)
• Folder names containing characters that are not valid in URLs (e.g. #, %, ?) may cause errors when renaming or moving

Tip: For maximum compatibility, stick to letters, numbers, hyphens, underscores, and spaces when naming folders and files.

MagicSuite Behaviour

MagicSuite automatically sanitizes container names to comply with Azure's strict rules. When you create a folder at root level (which creates a container), MagicSuite will:

• Convert to lowercase — My-Reports becomes my-reports
• Replace spaces and underscores with hyphens — my reports becomes my-reports, my_reports becomes my-reports
• Remove invalid characters — dots, special characters, and other disallowed characters are stripped
• Collapse consecutive hyphens — my--reports becomes my-reports
• Trim leading/trailing hyphens
• Pad short names — names shorter than 3 characters are padded (e.g. a becomes a00)
• Truncate long names — names longer than 63 characters are truncated
• Resolve conflicts — if the sanitized name already exists, a numeric suffix is appended (e.g. my-reports-2, my-reports-3)

This means the created folder may have a different name from what you typed. For example, typing Client_Data 2024 will create a container called client-data-2024.

File and folder names are not sanitized — they are passed directly to Azure. If the name contains invalid characters (e.g. control characters or invalid Unicode code points), Azure will reject it with an InvalidResourceName error and MagicSuite will display a message explaining the issue.

Note: Renaming a file or folder performs a copy-and-delete operation (Azure Blob Storage does not support native rename). The new name must comply with the naming rules above.

Supported Operations

Read-Only Connections

Check the Read Only option when creating the connection to prevent any modifications. This is useful for:

• Connecting to production data that should not be modified
• Using credentials with read-only permissions
• Compliance requirements

Troubleshooting

Connection fails with "Unable to determine authentication method"

Ensure your credentials are in the correct format for one of the three authentication methods described above.

Connection fails with "The specified container does not exist"

Check that the ContainerName in your Configuration JSON exactly matches an existing container name (case-sensitive).

"Access Denied" or "Authorization failed"

• Verify your credentials are correct and not expired
• For Azure AD authentication, ensure the service principal has the "Storage Blob Data Contributor" role assigned
• Check that the storage account firewall allows access from your location

"InvalidResourceName" or "The specified resource name contains invalid characters"

The name you used for a container, folder, or file contains characters that Azure does not allow. This commonly occurs when:

• Creating or renaming a container with uppercase letters, spaces, underscores, or special characters (see Naming Rules > Container Names above)
• Creating or renaming a file or folder with control characters or invalid Unicode code points

To resolve: Rename the item using only permitted characters. For containers, use only lowercase letters, numbers, and hyphens. For files and folders, avoid control characters and characters that are not valid in URLs. See the Naming Rules section above for detailed guidance and examples.

Spinner after deleting and re-creating a folder

If you delete a root-level folder (container) and immediately create a new folder with the same or similar name, you may see a loading spinner in the Files page for an extended period. This is normal behaviour caused by Azure.

What's happening: Azure Blob Storage deletes containers asynchronously. Even though the folder disappears from the list, Azure continues cleaning up the container in the background for up to two minutes (sometimes longer). During this time, any attempt to create a container with the same name will be retried automatically by MagicSuite.

What you'll see:

• The loading spinner on the Files page while MagicSuite waits for Azure to finish the deletion
• MagicSuite retries the creation automatically with increasing delays — you do not need to do anything
• If the original name is still unavailable after all retries, MagicSuite will try an alternative name with a numeric suffix (e.g. my-reports-2)

To avoid this: Wait approximately two minutes after deleting a root-level folder before creating a new one.

If the spinner persists for more than a few minutes or you see an error message about the container still being deleted, refresh the page and try again shortly.

Files not appearing

Only Block Blobs are displayed. Page Blobs and Append Blobs are not listed.