Management Console User Guide
This section is a complete user guide to the Service Gateway Management Console. It also describes prerequisites and instructions for creating a Management Console website in
The Service Gateway Management Console is a website that runs in
Microsoft Azure Websites. Creation of a new Management Console website is easy through the
Microsoft Azure Websites Gallery, but before a new website can be created a number of prerequisites must be satisfied.
Authentication to the Management Console is similar to the rest of the Service Gateway in that it uses
Azure Active Directory (AAD) as an identity provider. This allows Active Directory users from on-premise installations to be authenticated for use with this application. Additionally,
federated users from other identity providers (eg. Facebook, Salesforce.com, etc.) may also be used. For more information on integration with
AAD, see the Authentication and Authorization section of this documentation.
To enable users of the Management Console website to be able to authenticate and perform deployments to
Microsoft Azure on their behalf, please ensure that all of the following steps are performed:
- If not already available, create an Azure Active Directory using the
Microsoft Azure Management Portal.
- Enter a unique name for the Directory that represents your company's identity:
- Once a Directory is available, you may proceed with creating a Management Console website. However, you will be required to return to the
AAD portal to configure an Application to enable access for the Management Console.
Creating a Service Gateway Management Console Website
The Service Gateway Management Console is designed to run in the Microsoft Azure Websites environment. If you have downloaded the code and built the Console project you may deploy that project using any means available. To make the creation process
easier the Management Console has been added to the Microsoft Azure Websites Gallery which provides a wizard guided experience to create a website.
To create a new Service Gateway Management Console website using the Gallery, first logon to the
Microsoft Azure Management Portal.
- In the Microsoft Azure Portal click the New button and navigate to website creation via Gallery:
- Select the Tools category and then click the Service Gateway Management Console entry:
- Enter a name for the URL for the new website. Select a database creation option (a database is required to save configuration and deployment details) and a region where you wish the website to be located.
- Next, enter and select details of the SQL Azure database that will be created to save Gateway information. It is generally a good idea to have to website and database co-exist in the same locality:
Using the Service Gateway Management Console Website
First Time Use
The Service Gateway Management Console has a startup mode where additional pieces of configuration information must be entered so that the application can be authorized to deploy items to
Microsoft Azure on your behalf.
The first time that you navigate to the website after creating it, you will be shown the 'Startup' page which includes detailed instructions for configuring an
Application in AAD that is required to authorize the application to sign-on and interact with Azure's Management API.
When you follow the instructions on the Startup page, you will then be prompted to sign-in to the application using your
AAD user credentials. You must then enter two pieces of information that were generated with creating the
Application. After this, the final pieces of configuration setup are automatically performed by the application and you are ready to start defining roles and deploying Gateways!
Sign In and Out
To sign into the application, click the Sign In link in the top-right on the heading banner. Enter the email address of a
Azure Active Directory user from the Directory configured for use with the website (see above for creation configuration information) and the password. If the
AAD tenant is configured for federated logon using Active Directory Federation Services (ADFS) the browser will automatically be redirected to the tenant's ADFS sign in page where the password may be entered. Upon successful entry of valid
user credentials, the application will display the user's User Principal Name (UPN) to indicate the identity of the logged on user.
To sign out of the application, click on the drop-down link at the user's UPN and click
Sign Out. The browser will be redirected to the AAD sign out page to sign out of all applications and then redirect back to the Management Console's home page.
If a user is logged on for an extended period of time (greater than 1 hour), you may notice the application redirecting to the
AAD sign in page and then automatically returned. This is to allow the authenticated credentials to be refreshed and should be considered normal.
Clicking on the Roles tab will display a list of Roles defined for this Gateway. Roles represent independent components of an application that may exist at different locations and utilize different technology. Roles may also be
flighted independently to enable multiple versions of the same component to be running in production at the same time.
To define a new Role, click the Create New link. Enter details for the name and location of the Role and click the
To modify an existing Role, click the Details link in the Index table next to the desired Role.
To delete an existing Role, click the Delete link in the Index table next to the desired Role. Again, Click the
Delete button on the confirmation page to permanently delete the Role and all its associated information.
Securing the Gateway Application
Authentication is a feature of the Service Gateway that relieves individual Roles of the requirement to implement. Authentication is implemented in the Gateway using
Azure Active Directory. For full details of AAD integration with the Gateway, see the
Authentication and Authorization section of the documentation.
To enable authentication for the Gateway, click the Security tab. Check the
Enable Authentication check-box and click Save. Details of the
Application that will be created in AAD to represent the Gateway website may be updated by clicking on the
Details link (note that setting the App ID URI is an advanced feature. Use the default values unless absolutely necessary).
Note that when entering the Security tab for the first time, you may be prompted that the Management Console doesn't have sufficient access to deploy items to
Microsoft Azure. This prompt will offer to enable this access with the current user's consent. For this consent to be effective, the currently signed on user must be a member of the
Global Administrators role in the AAD Directory. If you are not a member of this Role, sign off from the website and get a user who is a Global Administrator to sign in and provide their consent. Once this consent has been successfully
applied, it is no longer necessary to be a member of any particular role to configure or deploy the Service Gateway.
Deploying the Service Gateway
Once the Role and Security configuration is correct, you may now proceed to deploy a Service Gateway to
Microsoft Azure. To do this, click the Deployments tab and click the
Create New link.
On the Create Deployment page, select the Microsoft Azure subscription that you would like to use to deploy the Gateway into. This drop-down list is populated with the subscriptions that the currently signed on user is an administrator
or co-administrator for (and thus has permissions to deploy a hosted service). Enter a unique name that will form part of the URL for the gateway (eg. If you enter 'tripapp' in this field, the URL to access the Gateway and application will be http://tripapp.cloudapp.net).
Custom domain names may be applied using DNS CNAME entries. Select the region where the Gateway should be deployed to. It is a generally good idea to co-locate as many of your application components to minimize network latency. Either enter details
for a new storage account or select an existing storage account. A storage account is required to store diagnostic and analytic information, including IIS logs, Failed Request Tracing logs and advanced logs (which include pipeline timing information). These
logs can be used for failure diagnostics as well as application analytics. Enter the number of instances for this Gateway deployment. 2 instances should be considered the lowest number as that provides a minimum level of redundancy to ensure the Gateway is
always available. Additional instances should be provisioned as traffic demands require.
Click the Create button to initiate the deployment of Service Gateway instances to
Microsoft Azure. Progress of the deployment will be displayed as it progresses. Note: do not navigate away from this page until the deployment has completed - navigating away will not affect the deployment, but you will not be able to view the progress
or any errors associated with the deployment.
Enabling Application Analytics
Understanding the operation of an application by monitoring the 'ClickStream' logs is a well established practice for web properties. A large amount of information can be gleaned from the logs such as usage patterns, error rates, conversion/purchase rates,
etc. The volume of entries in the ClickStream is so large, however, that it presents challenges to traditional RDBMS databases. New forms of scale-invariant processing, known as Map-Reduce, are now available as a better way of processing ClickStreams and thus
gaining insight into application and user behavior.
The Microsoft Azure HDInsight service is a cloud-based service, powered by Apache Hadoop, that enables big data processing, ideal for ClickStream analysis. Given that the IIS logs for a deployed Gateway service are already located in
Microsoft Azure Blob Store and this happens to be the default 'file system' of HDInsight, an optimized environment has been created to provide Application Analytics.
To enable Application Analytics for your Gateway Application, click on the
Analytics tab. Check the Enable Application Analytics check-box and either select an existing HDInsight cluster or enter details for a new cluster. The
Node Count value specifies how many 'data nodes' are provisioned in a new cluster. As a general rule, the greater the number of data nodes the faster results will be calculated. However, the cost of operating a HDInsight cluster is directly
proportional to the number of data nodes and given that all analytics aggregate calculations will not be interactive with users adding more data nodes is not generally useful.
Click the Apply button. If a new HDInsight cluster has been selected to be created, the Management Console will deploy this via
Microsoft Azure. Progress of this operation will be displayed on the screen. Additionally, jobs will be created in the
Microsoft Azure Scheduler service (if enabled - see prerequisites section) to periodically invoke the HDInsight cluster to process the ClickStream logs and calculate pre-defined aggregate information.
Once Application Analytics has been enabled and there is sufficient information in the ClickStream logs, results of the analytics may be displayed as pre-defined charts. In the
Charting Analytics section of the page, select one of the graph reports and click the
Show button. Analytic information for that report will be rendered as a chart in the area below.
Applying Updates to the Service Gateway and Management Console
The Service Gateway is a live project that is being continually updated. Features are available in the Management Console which allow new updates to be applied. Both the Service Gateway and the Management Console itself may be updated directly from
the Management Console website.
A dedicated service provides the updated packages for the various pieces of software (Service Gateway or Management Console). This service also provides a mechanism for querying the availability of updates for a given version of the software. It also provides
a description of an update as well as the criticality (e.g. if a security vulnerability has been identified and fixed).
Updating the Service Gateway
When a Service Gateway installation has been previously deployed by the Management Console, this information is recorded including the version number that was deployed. On the
Deployments tab, the prior deployments are listed with additional information indicating if the current version can be updated.
If a new version is available click the Update link associated with the deployment to display the
Update Service Gateway Deployment page. This page displays all details of the deployment that is to be updated together with a list of all available deployment packages. The list of available packages also includes prior versions which may
be applied if a downgrade is required. Click the Apply Update link associated with the version that you wish to apply and the Management Console will take care of the rest - displaying status updates as the deployment progresses. All existing
configuration for the Service Gateway (including number of instances, any SSL certificates and role configuration) is preserved for the newly updated version.
For existing Service Gateway deployments, the Update link may be clicked even if an updated package is not available. This option is useful if you wish to roll-back or downgrade a version or you simply want to re-deploy the current software.
Updating the Management Console Website
The Management Console may also be updated as new features and/or bug fixes are made available. Every time you navigate to the Home page of the Management Console site, a check is performed to see if an updated version is available. If an update is available,
a message will be displayed featuring an Update Now link that may be selected to update the website. The
Available Management Console Updates page lists all available versions of the Management Console application. Click the
Apply Update link associated with the version you wish to apply. The website will then apply the update 'in place' (i.e. the website is capable of updating itself using the same WebDeploy technology that was originally used to provision and
deploy the website from the Microsoft Azure Websites Gallery. Applying the update will normally only take a few seconds, after which the application will automatically navigate back to the Home page.
Automatic update checks can be disabled for both the Service Gateway and Management Console by setting the
NoUpdateCheck service configuration value to
Bootstrapping Updating the Management Console Website
For all versions prior to v0.7 of the Management Console application, there is no facility to apply updates of any kind. This means that once the application is deployed from the Gallery, the software is frozen in time. From v0.7 onwards, the self-update
capability described above will enable the Management Console to be upgraded (or downgraded) from any version to any version.
Users of existing Management Console websites prior to v0.7 need a way to bootstrap to v0.7. To do this, follow these steps:
- Delete the current website; [myconsole].azurewebsites.net. Prior to deleting the website, take note of the details of the database associated with the site - you will reconnect to this database later. When you delete the website from the
Microsoft Azure Portal, take care NOT to delete this database.
- Create a new Management Console website from the Gallery using the same name. Repeat the original steps in the
Microsoft Azure Portal to create a Management Console website. In the Gallery page, select the
Tools category and select the Service Gateway Management Console item. Verify that the
Version is greater or equal to 0.7. Click Next.
- In the URL field, enter the exact same name that the previous Management Console had. Because you have already deleted this website the name should be available for use. In the
Database drop-down, ensure that Use an existing SQL database is selected. Click Next.
- On the Database Settings page, select the name of the database associated with the previous Management Console website using the details recorded in step 1. Enter the credentials for this database.
- Click the OK button to provision a new version of the Management Console website and connect it to the existing database.
- Browse to the new/old Management Console website.
- You will be guided through the welcome/initialization sequence to associate your
Azure Active Directory Application information. Click the
Sign In To Continue button as we will reuse the existing AAD Application from the prior version.
- In the Microsoft Azure Portal, navigate to the Active Directory section and select the Directory that you originally registered the Management Console Application.
- Click the Applications tab and select the Application that was registered for the prior version Management Console website.
- On the Configure tab. copy the CLIENT ID value to the clipboard. Switch back to the new Management Console
Step 2 of 2 page and paste this value in the Client ID field.
- Switch back to the AAD Portal. If REPLY URL values does not include an address with the
https protocol, then add this now (i.e. If you only have a REPLY URL value of 'http://myconsole.azurewebsites.net' then add a new value 'https://myconsole.azurewebsites.net').
- Create a new key (1 or 2 years). Click the Save button and copy the new key value to the clipboard when it is displayed. Switch back to the Management Console page and paste this value in the
Key Value field. Click the Complete Initialization button.
- Verify that the Role and Security configuration from the previous Management Console website is preserved. Also verify that prior Service Gateway deployments are displayed.
As subsequent updates are released, these will be notified and be available to update as described above.