Create SAS tokens for your storage containers

In this article, you'll learn how to create user delegation, shared access signature (SAS) tokens, using the Azure portal or Azure Storage Explorer. User delegation SAS tokens are secured with Azure AD credentials. SAS tokens provide secure, delegated access to resources in your Azure storage account.

At a high level, here's how SAS tokens work:

  • Your application submits the SAS token to Azure Storage as part of a REST API request.

  • If the storage service verifies that the SAS is valid, the request is authorized.

  • If the SAS token is deemed invalid, the request is declined and the error code 403 (Forbidden) is returned.

Azure Blob Storage offers three resource types:

  • Storage accounts provide a unique namespace in Azure for your data.
  • Data storage containers are located in storage accounts and organize sets of blobs (files, text, or images).
  • Blobs are located in containers and store text and binary data such as files, text, and images.

Important

  • SAS tokens are used to grant permissions to storage resources, and should be protected in the same manner as an account key.

  • Operations that use SAS tokens should be performed only over an HTTPS connection, and SAS URIs should only be distributed on a secure connection such as HTTPS.

Prerequisites

To get started, you'll need the following resources:

  • An active Azure account. If you don't have one, you can create a free account.

  • A Translator resource.

  • A standard performance Azure Blob Storage account. You'll create containers to store and organize your files within your storage account. If you don't know how to create an Azure storage account with a storage container, follow these quickstarts:

    • Create a storage account. When you create your storage account, select Standard performance in the Instance details > Performance field.
    • Create a container. When you create your container, set Public access level to Container (anonymous read access for containers and files) in the New Container window.

Create SAS tokens in the Azure portal

Go to the Azure portal and navigate to your container or a specific file as follows and continue with the steps below:

Create SAS token for a container Create SAS token for a specific file
Your storage accountcontainersyour container Your storage accountcontainersyour containeryour file
  1. Right-click the container or file and select Generate SAS from the drop-down menu.

  2. Select Signing methodUser delegation key.

  3. Define Permissions by checking and/or clearing the appropriate check box:

    • Your source container or file must have designated read and list access.

    • Your target container or file must have designated write and list access.

  4. Specify the signed key Start and Expiry times.

    • When you create a shared access signature (SAS), the default duration is 48 hours. After 48 hours, you'll need to create a new token.
    • Consider setting a longer duration period for the time you'll be using your storage account for Translator Service operations.
    • The value for the expiry time is a maximum of seven days from the creation of the SAS token.
  5. The Allowed IP addresses field is optional and specifies an IP address or a range of IP addresses from which to accept requests. If the request IP address doesn't match the IP address or address range specified on the SAS token, it won't be authorized.

  6. The Allowed protocols field is optional and specifies the protocol permitted for a request made with the SAS. The default value is HTTPS.

  7. Review then select Generate SAS token and URL.

  8. The Blob SAS token query string and Blob SAS URL will be displayed in the lower area of window.

  9. Copy and paste the Blob SAS token and URL values in a secure location. They'll only be displayed once and cannot be retrieved once the window is closed.

  10. To construct a SAS URL, append the SAS token (URI) to the URL for a storage service.

Create SAS tokens with Azure Storage Explorer

Azure Storage Explorer is a free standalone app that enables you to easily manage your Azure cloud storage resources from your desktop.

  • You'll need the Azure Storage Explorer app installed in your Windows, macOS, or Linux development environment.

  • After the Azure Storage Explorer app is installed, connect it to the storage account you're using for Document Translation. Follow the steps below to create tokens for a storage container or specific blob file:

  1. Open the Azure Storage Explorer app on your local machine and navigate to your connected Storage Accounts.

  2. Expand the Storage Accounts node and select Blob Containers.

  3. Expand the Blob Containers node and right-click a storage container node to display the options menu.

  4. Select Get Shared Access Signature... from options menu.

  5. In the Shared Access Signature window, make the following selections:

    • Select your Access policy (the default is none).
    • Specify the signed key Start and Expiry date and time. A short lifespan is recommended because, once generated, a SAS can't be revoked.
    • Select the Time zone for the Start and Expiry date and time (default is Local).
    • Define your container Permissions by checking and/or clearing the appropriate check box.
    • Review and select Create.
  6. A new window will appear with the Container name, URI, and Query string for your container.

  7. Copy and paste the container, URI, and query string values in a secure location. They'll only be displayed once and can't be retrieved once the window is closed.

  8. To construct a SAS URL, append the SAS token (URI) to the URL for a storage service.

Use your SAS URL to grant access

The SAS URL includes a special set of query parameters. Those parameters indicate how the resources may be accessed by the client.

You can include your SAS URL with REST API requests in two ways:

  • Use the SAS URL as your sourceURL and targetURL values.

  • Append the SAS query string to your existing sourceURL and targetURL values.

Here is a sample REST API request:

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

That's it! You've learned how to create SAS tokens to authorize how clients access your data.

Next steps