How to use the Azure Storage Connector?
To get an advantage on all the capabilities Azure Storage offers inside your OutSystems applications, you must perform a 2-stage set-up inside the Active Directory and Service Center.
Section 1: Definition Inside Active Directory. Once you access your Active Directory Portal, search App Registrations inside the Microsoft Azure Services.
In the new screen, click over the New Registration button. This action redirects to a screen where you can define the name of your newly created application. Leave the Supported Account Types marked on the Accounts in this organizational directory-only option.
After creating your App Registration, your screen shows the application details. Now, you need to define the API permissions to access the storage account via REST API. On the left menu, search for API Permissions under the Manage options.
Inside the API Permissions, all the granted permissions will display as a list. To define more, click over Add a Permission. This action loads a lateral tab with all the APIs Microsoft offers based on your needs. For the current scope, select the Azure Storage option.
Inside, select the user_impersonation permission. Once selected, the permissions list updates. Now, you need to grant admin consent for the defined permissions. This step is crucial to perform API calls successfully. If not, you will get 403 errors while generating the Access Token or performing other calls.
NOTE: TO GRANT ADMIN CONSENT, YOU NEED ADMIN PERMISSIONS INSIDE THE AAD PORTAL. IF YOU DON'T HAVE THE NECESSARY PERMISSIONS, ASK YOUR ADMINISTRATOR.
Now, head to the Certificates and Secrets tab on the left-side menu. Inside this space, you can create client secrets to generate access tokens for REST API Calls. Clicking over New Client Secret opens a lateral bar to add a client secret. Just make sure to add a descriptive name and a proper lifespan.
After defining the information, the Secret Id and the Client Secret Value appear. Copy the value and store it safely. Once you leave this screen, it disappears.
Section 1.2. Storage Account
The next step is creating the Storage Account. Head to the Portal Main page and look for Storage Accounts inside Microsoft Azure Services.
This action will open a new screen with a list of existing accounts (if any). To create a new account, click on the Create button.
NOTE: TO CREATE AN STORAGE ACCOUNT, YOU NEED TO HAVE AN AZURE SUBSCRIPTION.
The creation process is a step-by-step flow. The first tab lets users assign the storage account basic information such as name, region, subscription, and resource group. You can create resource groups from this screen by adding a name to the respective input.
The second tab manages the security aspects of the account. Here click over the Default to Azure Active Directory authorization in the Azure portal checkbox. This option lets access to the storage account by token authentication (from the app registration).
The other tabs you can leave with the default values. So, click on Review and Assign, then on Create. Now, your storage account details are on the screen.
As the final stage inside storage accounts, go over Access Control (IAM). Here, you can assign roles for accessing the storage account and executing actions inside. Inside this space, click over Add Role Assignment.
Now, a new screen appears. Here you need to specify the roles that will let us perform document and container operations inside the account. On the enabled widget, select the Storage Blob Data Contributor option.
Head to the member's tab. Then, click on the Select Members button. This action will enable a lateral menu where you can search for users or app registrations inside your AAD Portal. Write the name of the app registration created before. Then click on the Review+Assign button.
Now, the storage account is ready to start working.
NOTE: YOU CAN ADD THE STORAGE BLOB DATA OWNER TO THE APP REGISTRATION ALONG WITH THE DATA CONTRIBUTOR ROLE. JUST FOLLOW THE SAME STEPS.
NEW FEATURE: SHARE BLOBS USING SAS ( December 2023 )Now, the Azure Storage Account Connector supports BLOB share with Signature Access Token.To do so programatically, you need to obtain the Connection string.
At the left-side menu from the Storage Account Home page, click on the Access Keys button under Security+Networking. This action will open a new window.
Now, inside the Access keys screen, you will see your account information with 2 keys (similar to the next picture)
From this space, pick any of the keys. Click over the Show button (highlighted in yellow). This will reveal the value of the Connection String. Copy the value and store it.
Section 1.3. Before Leaving the Portal
Up to this point, everything is in place for a storage account. Now, to set values inside Outsystems, you need to gather the following information:
Values like the Tenant Identifier and Application Identifier are available on the app registration details screen. The client secret and storage account name are values obtained in the previous steps.
Finally, the API Version is the latest release for the Azure Storage API. You can look at the latest version here: https://learn.microsoft.com/en-us/rest/api/storageservices/versioning-for-the-azure-storage-services
Section 2: Definition Inside Outsystems.
After downloading the connector and before the first use of the actions, you need to declare some site properties and values inside Service Center. So, head to your environment Service Center. Inside, look for the Module AzureStorage_IS. Once you get there, go over the Site Properties tab.
Inside each property, define the corresponding values for the Tenant ID, API Version, Storage Account Name, Connection String, Client ID, Client Secret and ExpirationTime.
About ExpirationTime Site PropertyThis site property sets the time in minutes for the SAS to expire. Meaning the effective time for the generated URL. This value can change based on your needs.
Now, go to the Integrations Tab. Search for Consumed REST APIs. There you will find two services called: StorageToken and AzureStorageAccount.
The StorageToken REST API is the endpoint used to generate the Access Token. While the AzureStorageAccount is the actual URL for performing container and document actions.
As you can see, the defined URL has the following syntax:
https://YOURSTORAGEACCOUNTNAME.blob.core.windows.net
The storage account name must reference the one created inside AAD in the previous version. So, click on the REST API Name. This action will take you to a different screen.
Look for the Effective URL input widget. Write your storage account URL following the previous syntax and click Apply.
(With the guide example, the URL should be: https://testingguideaacount.blob.core.windows.net)
Now, to finish the configuration. Go over the Timers Tab and select the Refresh_StorageAccessToken timer. Click on Run Now. This action will automatically create an access token inside the Service Studio Module.