To get started with the Blob Share sample, you can run it locally using the Windows Azure compute emulator and your local SQL Server. If you want to deploy the sample to Windows Azure, please follow the instructions in the Deployment section.

To run the sample, you first need to provide a set of configuration settings that depend on your Windows Azure account and your local environment and then run the setup scripts. These will check for any missing prerequisites and perform a set of configuration steps using the information that you provide.

Altogether, getting started with the sample involves the following tasks:

  • Creating an AppFabric Access Control Service (ACS) namespace
  • Editing an XML file to provide the following values:
    • Your local SQL Server instance name
    • An AppFabric Access Control Service namespace and management key
    • SMTP server settings to enable the application to send invitations
    • One or more identity providers to use with the application
  • Running the setup scripts to check for prerequisites and configuring the sample
  • Running the sample in Visual Studio, signing in to the application and providing the pre-configured administrator secret value. This secret is used to verify the identity of the site administrator who will be enabled to send invitations and upload files.

To ease the process of providing all the configuration settings required for the sample, these are stored in a single file named Configuration.xml. The following steps will guide you through the process of obtaining these values and entering them into this file.

Creating an AppFabric Access Control Service Namespace

The application takes advantage of the AppFabric Access Control Service to enable authentication using one of several configured identity providers, for instance Windows Live ID, Yahoo!, Google, and Facebook.

In this task, you configure an AppFabric Access Control Service namespace that the application uses to enable this support.

  1. Start by browsing to the Windows Azure Management Portal at http://windows.azure.com. If you are not already signed in, do so with the same account that you used for redeeming the free pass. Alternatively, you can sign in with any valid Windows Azure account.

    noteNote:

    The Windows Azure Management Portal is where you create and configure your hosted services, storage accounts, SQL Azure databases, and other offerings from the Windows Azure platform.

  2. Next, create a new Service Namespace. In the home page of the Windows Azure Management Portal, select Service Bus, Access Control and Caching in the lower half of the navigation pane.

    ac99a6d5-f5e0-4396-a76b-511c15cde9d4

    Figure 1 - Windows Azure Management Portal

  3. Now, under the AppFabric subarea in the upper half of the navigation pane, select Access Control and then click New on the ribbon.

    ec3e0118-174d-4e44-9f0e-b6d63b442bc0

    Figure 2 - Managing AppFabric Access Control Service namespaces

  4. In the Create a new Service Namespace dialog, choose a Namespace name and a Country/Region for the new namespace. Then, verify that the chosen namespace is available by clicking Check Availability and that Access Control is selected under Available Services. Make a note of the name you have chosen and then click Create Namespace.

    68546723-abb8-49a9-8056-cdb08e857b9a

    Figure 3 - Creating a new AppFabric Access Control Service namespace

    note[1]Note:

    Service names must be globally unique as they are in the cloud and accessible by whomever you decide to grant access.

  5. Locate the new entry in the list of configured service namespaces and then wait for its Status column to show the namespace as Active.
  6. On the ribbon, click Access Control Service to browse to the ACS Management site.

    c11a3f49-ce77-4398-8f7a-b63f0f5b2283

    Figure 4 - Navigating to the AppFabric Access Control Service Management site

  7. In the ACS Management site, under Administration in the navigation pane, select Management Service.

    0ece0cb5-e651-484f-9e80-9d19937696ab

    Figure 5 - Administering ACS management service accounts

  8. In the Management Service Accounts section, select the ManagementClient service account.

    97bfcdbd-d082-43a3-899f-62a261bdfc97

    Figure 6 - Retrieving the properties of the default management service account

  9. In the Edit Management Service Account page, under Credentials, select Symmetric Key.

    e7f1da17-8a5b-4a56-9e29-20b7f4b5b05d

    Figure 7 - Accessing the service management credentials

  10. In the Edit Management Credential page, make note of the value displayed for Key. You will need this value later, when you configure the application.

    97ea2c6d-1647-48e5-9434-8d7ebf96d41d

    Figure 8 - Retrieving the management key


Configuring the Application

  1. The application requires you to specify several configuration settings before it can be used, including settings for the application’s database server, an AppFabric Access Control Service namespace that the application uses for authentication, an SMTP server for invitations and notification emails, and a Windows Azure storage account to store the uploaded content.
  2. To make it easier to gather the information in a single place, you enter all the required settings into a configuration file that the setup scripts then use to install the application.
  3. In Visual Studio, open the Configuration.xml file located inside the root folder of this package.
  4. Near the top of the file, locate the UseLocalComputeEmulator setting and ensure that its value is set to true to indicate to the setup script that you will run the application in the compute emulator.
  5. Now, locate the BootstrapAdministratorSecret entry and make a note of its value. You will be prompted for the administrator secret value the first time you sign in to the application to verify your identity. You can change the default value, if you wish to do so.

    8ba894e9-05d4-403a-980c-524b0558e5d7

    Figure 9 - Configuring the administrator secret value

  6. The application stores its information in a relational database. To configure the database server used by the application, locate the Database section in the configuration file and enter the settings required to access the server that will host the application’s database.

    The table below summarizes each setting in this section.

    image
    note[2]Note: The Quick Configuration column in this table shows the values that you need to enter when using a default instance of SQL Server Express running locally and configured for integrated authentication.

    6b7ad30f-a6f6-4620-b220-c549128c8e46

    Figure 10 - Configuring for a default instance of SQL Server Express with integrated authentication

  7. Authentication in the application is handled by the AppFabric Access Control Service. To configure it, find the AccessControlService section and enter the settings for the service namespace that you created in the previous task. Additionally, you can enable one or more identity providers that the application can use by setting the value of the corresponding UseXXXProvider element to true. By default, all the available providers except Facebook are enabled.

    The table below describes each setting in this section.

    image

    note[3]Note: The Quick Configuration column in this table shows the values that you need to enter when running the application in the compute emulator, with Windows Live ID, Yahoo!, and Google enabled as identity providers. The values for the ACS namespace and management key are your own, which you obtained in the previous task.

    note[4]Note: To use Facebook as an identity provider, you need to provide a Facebook application name, Id and secret. For detailed instructions on how to do this, see this article: http://msdn.microsoft.com/en-us/library/gg185919.aspx.

    356562ab-df01-42e3-b6e2-7426b5ddcc85

    Figure 11 - Configuring AppFabric Access Control Service settings for your namespace

  8. The application sends invitations and can notify users whenever a resource is updated. To enable this functionality, you need to configure an SMTP server that the application can use for this purpose. To do this, locate the SMTP section in the configuration file and enter the settings for the SMTP server of your chosen service provider.

    The table below summarizes each setting in this section.

    image
    note[5]Note:

    The Quick Configuration column in this table shows the values that you need to enter when using Windows Live as your email service.
    If you choose an SMTP provider different from Windows Live, you need to update the host address and port to match the one used by your provider.

    03bce47f-aea0-4c76-bf5b-beed4656c76f

    Figure 12 - Configuring the application to send invitations and notification emails

  9. The application stores any uploaded content in blob storage. By default, when running the application in the compute emulator, it will use the storage emulator and it is not necessary to specify any additional settings. You can, however, use a Windows Azure Storage account instead. To configure the storage account, locate the WindowsAzureStorage section of the configuration file and enter the settings for the account.

    The table below summarizes each setting in this section.

    image
    note[6]Note: The Quick Configuration column in this table shows the values that you need to enter when using the local storage emulator.

    bdaeddad-0c74-4776-973f-30d4e70cac69

    Figure 13 - Configuring the application to use the storage emulator

    e57a9279-e94c-42e4-a04e-24aea0c07f57

    Figure 14 - Configuring the application to use Windows Azure Storage


Preparing the Application to Run for the First Time

Before launching the application, you first need to verify that your computer is properly configured and has all the necessary software to build and use the sample and then execute a script to set up the application using the information that you entered previously.

  1. Launch Setup.exe located in the root folder where you extracted the sample package. Notice that it requires administrator privileges.
  2. When prompted, click ACCEPT if you agree to the terms of the license; otherwise, you will be unable to proceed with the installation and use the sample.

    036d38b6-420d-40f9-a9d1-696f1786b915

    Figure 15 - Accepting the license agreement

  3. The next step involves checking your machine for the prerequisites. If you do not have the necessary configuration or dependencies, the dependency checker will either provide a link to download any required software or launch the Web Platform Installer to install the prerequisite for you. After installing a missing dependency, click Refresh to initiate the detection process again.

    dc56b2db-5051-4a98-812d-6d88911f10a8

    Figure 16 - Checking your system for prerequisites

    note[7]Note:

    By default, you will not be able to proceed with the setup procedure unless the dependency checker has successfully verified every dependency. You can, however, instruct it to ignore a missing dependency by choosing the SKIP or the SKIP ALL option, but be aware that the sample might not run correctly if you do this. This option is mainly used in cases where a dependency has been superseded by a more recent software package not contemplated in the original dependency scripts.

  4. Once the detection process is complete and you have verified every prerequisite, click Next to launch the setup script. The setup script executes the following actions:
    • Creates a new database in the configured database server. This step also updates the connection string in the application with your server name and login credentials.
    • Installs the certificates used by the application.
    • Installs the Windows Azure Platform PowerShell Cmdlets that the installation script uses to configure the AppFabric Access Control Service (ACS) namespace for running the application. The cmdlets are also needed if you plan to deploy the application to Windows Azure using a script provided in this package that automates the deployment process.
    • Configures the ACS namespace using the PowerShell cmdlets. This includes adding the relying party application and configuring identity providers, among other tasks.
    • Configures the SMTP server settings with the provided values to allow the application to send invitations.
    • Configures the provided administrator secret value so that it can be verified by the application.
  5. The script prompts you to confirm that you have entered the necessary settings into the Configuration.xml file. If you have done so, press “Y” to proceed with the installation.
  6. If you proceed with the installation, the script validates the information that you have entered and then executes all the required steps. Wait until the process is complete, which typically takes less than one minute.

    note[8]Note:

    The script verifies whether the configured database is already present in the server and will prompt you for confirmation before dropping and recreating it. If you have executed the application previously, you may answer ‘N’ if you do not want to overwrite an existing database.

    c8dfc27c-775b-4b7d-940a-95369f73ca1e

    Figure 17 - Running the setup scripts

  7. When the script has finished its execution, click Close to exit the dependency checker.

    1fd2947b-ef73-44e4-a5d5-f87318622ced

    Figure 18 - Completing the setup procedure


Running the Blob Share Sample in the Compute Emulator

Once the installation is complete, you are ready to run the application in the compute emulator.

  1. Open Visual Studio as administrator from Start | All Programs | Microsoft Visual Studio 2010 by right-clicking the Microsoft Visual Studio 2010 shortcut and choosing Run as administrator.
  2. In Visual Studio, open the BlobShare.sln solution located inside the code folder of this sample.
  3. Ensure that the BlobShare cloud project is selected as the start-up project (shown in bold in Solution Explorer).

    b0f1291a-e461-4652-9976-1287af7afdac

    Figure 19 - The Blob Share sample solution

  4. Press F5 to build and deploy the application to the compute emulator. Your default Web browser should open and show a warning related to the application certificate. Click Continue to this website to browse to the Blob Share application login page.

    f3bdb6e7-dc46-401a-8ed1-53aba9e1fa57

    Figure 20 - Certificate warning message

    note[9]Note:

    By default, the application is configured to use the default HTTPS port (443). You need to ensure that this port is free before running the application. If the port is already taken and cannot be freed, you must take into account this change in the relying party configuration settings in ACS.
    To update the relying party configuration, go to the Access Control subarea in the Windows Azure Management Portal, select the namespace created for the application, and then go to the ACS Management site by clicking Access Control Service on the toolbar. In the ACS Management site, in the navigation pane, select Relying party applications under Trust relationships, and select the relying party application named “Blob Share Local”. Update the Return URL value to reflect the port number where the application is currently running, for example, https://127.0.0.1:444/Account/LogOn.
    To complete the necessary changes, open the Web.config file of the BlobShare.Web application and locate the microsoft.identityModel/service/audienceUris element. Find the entry for the loopback address (https://127.0.0.1/) and update it to set the proper port number, for example, https://127.0.0.1:444/.

    note[10]Note:

    When the application runs in the cloud emulator, it uses a self-signed certificate to secure the SSL binding. When you visit the site, the browser will show a warning indicating that the certificate is not trusted. You may safely ignore this message.

  5. When the application starts, you are prompted to log in. Note that the account used for the first time will be used as the site’s administrator. Choose the identity provider of your preference and complete its sign in procedure.

    2270f5d0-d64e-42dc-b53c-4792a9e0465c

    Figure 21 - Application login page

  6. Once logged in, your account needs to be verified. Enter your email address and the Bootstrap Administrator Secret value that you specified in the Configuration.xml file during the installation (default value is 123456) and then click Update.

    701cd378-ce35-469b-a411-c50fed8adc56

    Figure 22 - Verifying the administrator account

  7. After you are successfully verified, the application shows a success message. Click the link on this page to browse to the home page.

    c6bac568-6da2-4cbd-9ac6-1adbf227c4ef

    Figure 23 - Successful verification of the administrator account

  8. Sign in again using the same account that you used to register previously.

    2e0a52ca-287b-4f39-bbe5-c293c3046c73

    Figure 24 - Blob Share home page

  9. Now, click Users followed by Invite User (d3a84899-f4b2-4db3-969b-f851fa1e0429) in the upper right corner of the page. Complete all the fields using any alternate e-mail address that you have access to, different than the one used to log in to the application. Click Create to create a new user and send him an invitation email.

    e1886d23-7a72-4c8e-8241-eec5b086e1ab

    Figure 25 - Creating a new user

  10. Next, to upload a new file, click Blobs in the navigation bar and then Upload (56e45772-6393-4a69-9f6c-4f44011d14da) in the upper right corner of the page. Use either the single-file HTML control or the multi-file Silverlight control to upload a sample file. After the upload has completed, click Blobs again to see the list of blobs that are now available, which should include the blob that you have just uploaded.

    6fcabe7a-4172-4414-b50f-e9666b6ffe0b

    Figure 26 - Listing available blobs

  11. Click the link for the new blob to view its details and then click Permissions (c575ade3-87a4-4af9-8f46-a2eeb4f5568e). Grant permissions to the new user that you have just created.

    0ffac46a-1a3e-4505-9ef6-325168f65c08

    Figure 27 - Granting permissions to a blob

  12. Now, check your alternate e-mail account for the invitation message.

    2ec8f34c-9bf0-457b-bdf3-6ec71ce8e169

    Figure 28 - Invitation e-mail for new users

  13. Open another browser, or a new in-private window, and browse to the URL indicated in the e-mail body. This will create a new session in the application, different from the one where you are currently signed in as administrator. You will be prompted to log in to the application. Use the alternate e-mail address you used when creating the new user.

    222610bd-6f15-4dd0-bf38-88979a2fea19

    Figure 29 - Activating the invitation

    note[11]Note:

    If you receive an error indicating that “you are not the invited user” it is either because you tried to accept the invitation while logging in with the same user that sent the invitation or because you did not open a new browser or an in-private window to force a new session.

  14. Click My Blobs in the navigation bar to view the shared files.

    efee6917-0308-4ef0-ac04-819195d761d6

    Figure 30 - My Blobs Page

Last edited Oct 21, 2011 at 4:53 PM by wwegner, version 2

Comments

No comments yet.