External Portal Setup

Azure Components

External Portal uses following Microsoft’s Azure Component for deployment.

Azure AD B2C

It serves as an identity provider for external users. Manages user account sign-up, sign-in, profile edit, and password resets - all from outside of the applications which have been developed to meet specific functionality. Azure AD B2C has its own login Portal management for which you can customize the look and feel.

Azure Functions

Azure Functions is used to host Portal Service. It communicates with the Azure relay service to generate credentials. The Portal Service is a public facing service secured by the identity provider. Only valid, authenticated users of the identity provider can communicate with the Portal service. The Portal UI securely communicates with the Portal service to acquire the connection information necessary to relay requests. Next, the Portal UI raises a request to securely relay requests to the internal network.

Azure App Service

Azure App Service is a fully managed web hosting service for building web applications, services, and RESTful APIs. Microsoft Azure App Service is used as a hosting provider.

Azure Storage

Azure Storage is used to provide file storage for hosting an Angular-based user interface (UI). This storage is used to create static website for portal UI.

Azure CDN

Azure CDN offers a secured, public facing UI component which is mapped with your custom portal domain. It helps to reduce load times and save bandwidth.

Azure Relay Service

Azure Relay Service facilitates your hybrid applications by enabling you to securely expose services that reside within a corporate enterprise network to the public cloud. It does this without having to open a firewall connection and without requiring intrusive changes to the corporate network infrastructure.

Azure Hybrid Connections

Communicates between the relay service in the cloud and the relay worker installed in the internal network.

Prerequisites

1. You should have added a valid feature license for creating external Portal.

2. You should have Microsoft Azure Subscription.

3. Define the name of Azure CDN End point. This will be created by deployment script but needed in next step. Example: aryabhataendpoint.

4. Get domain from domain provider and perform the CNAME domain mapping of Azure End Point. This will be done at domain provider website (like: godaddy). For example, If you have purchased wsevolve.com domain and want to use https://fuse.wsevole.com as your Portal URL, then do the CNAME mapping of "fuse" with "aryabhataendpoint.azureedge.net". Here aryabhataendpoint is the name of Azure CDN Endpoint, defined in previous step.

5. Azure AD B2C should be configured. Below are the steps which should be done to accomplish this:

   • Create an Azure AD B2C tenant with help of below link:

     https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-tenant

   • Create an application in Azure AD B2C tenant, with the help of below steps.

   • Switch to your newly created in Azure AD B2C directory (created in above step).

   • In the B2C tenant directory (created in above step) open Azure AD B2C and click on App Registrations → New Registration.

   • In Register an application window, in the Display Name for this application provide a valid name for the App (for example AppForPortal) and in Supported Account Type select Accounts in any identity provider or organizational directory (for authenticating users with user flows).

   • In Register an application window, in Redirect URI select SPA and in URL provide the portal URL. This URL is same as defined in step 4. Example: https://fuse.wsevole.com.

   • Select newly created application and in API permissions check for openid permission being present. This permission is added by default.

   • Select the new app created and go to Authentication and check Access tokens and ID tokens check box and click on Save.

   • In Azure AD B2C go to Policies → User flows and click on New user flow.

   • Under Create a user flow select Sign-in and under Version select Recommended and click on Create, to create SignIn policy.

   • In Name provide any valid name for example “signin” and in Identity Providers check Email signin checkbox. In Application claims click Show More, and check Email Addresses checkbox. Click OK and Create.

   • Create another user flow, go to Policies → User flows and click on New user flow.

   • Under Create a user flow select Sign up and under Version select Recommended and click on Create, to create SignUP policy.

   • In Name Provide a valid name for example “signup”. Under Identity Providers check the Email Signup checkbox. In User attributes and claims click Show More and check the Email Address and Display Name check boxes in Collect attribute, also check Email Addresses under Return Claim. Then click on OK and Create.

   • Create another user flow, go to Policies → User flows and click on New user flow.

   • Under Create a user flow select Password reset and under Version select Recommended and click on Create.

   • In Name provide any valid name for example “passwordreset” and in Identity Providers select Reset password using email address. In Application claims click Show More, and check Email Addresses checkbox. Click OK and Create.

   • Enable Localization support for user flows: To enable localization support for all the three user flows created do below:

     In Azure AD B2C go to Policies → User flows and click on the name of user flow. Under Customize click on Languages, then click on Enable Language customization. Select the language you want to enable from table below and toggle the Enabled button to yes and click save.

6. Portal B2C Details: To set up external portal, IDP configuration details for azure B2C needs to be filled in Evolve. Before you start adding IDP details, follow below steps to have the information ready.

   • Domain: This is the Domain Name of Azure B2C tenant created. In Azure, go to b2c tenant directory and select azure b2c, Under Essentials you will find Domain Name. Domain Name will look like “domain.onmicrosoft.com“ . for example: if domain name is EvolveWinshuttle.onmicrosoft.com then note down the value EvolveWinshuttle as your domain.

   • TenantID : Select the app created in B2C directory in App registrations , Under Essentials you will find TenantID under Directory (tenant) ID.

   • ClientID: Select the app created in B2C directory in App registrations , Under Essentials you will find ClientID under Application (client) ID.

   • SignIn, SignUp, PasswordReset Policies: Go to Azure AD B2C → Policies → User Flows and note down the name of SignIn, SignUp, and Password reset policies that we created in Step 4.

Once you have got all the above details you can fill the IDP configuration page in Evolve for Portal using the values as below.

Issuer: https://{Domain}.b2clogin.com/{TenantId}/v2.0/

Replace {Domain} and {TenantId} with values we got in steps above.

MetadataURL: https://{Domain}.b2clogin.com/{domain}.onmicrosoft.com/<policy-name>/v2.0/.well-known/openid-configuration

Replace {Domain} with values we got in above steps.

Scope: Provide openid in scope value.

Client Id: Provide the value we got in above steps.

Redirect URL: Provide Portal URL for Redirect URL. It is the same URL which we have defined in step 4.

Auth EndPoint: https://{Domain}.b2clogin.com/{Domain}.onmicrosoft.com/<policy-name>/oauth2/v2.0/authorize

Replace {Domain} with values we got in above steps.

SignUp Policy Name: Provide the value of SignUp policy you got in above steps.

SignIn Policy Name: Provide the value of SignIn policy you got in above steps.

Password Reset Policy: Provide the value of Password reset policy you got in above steps.

Description of IDP Configuration fields

All the above nine configuration values are used to configure IDP so that external user can be authenticated by added IDP and the authentication token issued by IDP can be validated by Evolve.

Issuer value is used to validate the authentication token issued by IDP. It matches the ValidIssuer claim. Only token which are issued by this authority is considered valid.

MetadataURL is used in authentication token validation. MetaData URL end point is used to fetch the metadata (SigningKeys) that has been used to sign the authentication token.

openid scope is used to get the authenticated user information. It is passed as parameter to the request made at auth EndPoint.

ClientID is used to validate the token. It matches the ValidAudience claim in the token. It is also added to authentication request made with identity provider.

Redirect URL is passed to the Identity provider during request made to auth EndPoint and identity provider redirect back to this url after executing authentication user flow (signin,signup,paswword reset).

Auth EndPoint is the identity provider end point, all authentication requests are redirected to this end point with some additional parameters.

SignUp Policy Name, SignIn Policy Name, Password Reset Policy are the policies(user flows) created at the identity provider side. and users are redirected from portal to IDP to execute respective user flows. for example, during signup action request is made with IDP to execute signup user flow so that user gets registered with identity provider.

External Portal creation and Portal UI set up on Azure

In this step we will create and external portal and deploy the Portal UI on Azure.

1. Go to Portal tab on the left menu in Evolve (this should be visible if appropriate license is available).

2. Click Add to add a new Portal. Select External in Portal mode and fill in appropriate Name, Description, choose Default Language, Select Architect and Reviewers. In Portal URL fill the same URL which is defined in Prerequisite Step 4.

3. Click on Next and add Portal Identity Provider details. All of these are available in perquisites step 6.

4. Submit the Portal. Here you will see that the Config Status is Pending.

5. Click on the icon in Actions for your Portal and configure the Portal with required widgets. Click on Deploy.

   Note: You can change the portal design anytime by simply adding/removing new widgets and clicking on Deploy.

6. Go back to All Portals and select the created Portal by checking the checkbox in front of it; and click on Download Package.

7. Unzip the file and you should be able to view files like PortalService, UI, Prerequisites.ps1 script, Setup.Ps1 script, dsettings.json, and other related files.

8. Open PowerShell in admin mode and run the Prerequisites.ps1 script. Follow the instructions as they appear in PowerShell. This will install the required packages for deployment. You will see Name and Version listed; this indicates that all packages have been installed.

9. Close the PowerShell and relaunch the PowerShell again in admin mode and run the Setup.Ps1 script and login with the user who has azure subscription.

10. Enter the appropriate Resource Group name to be created on Azure or you can add here the existing resource group name here. Press enter. Enter the appropriate location where you want to create the resource group or add the location of existing resource group, then press enter. If the Azure Resource Group is already existing, enter the existing Resource Group name and its location value in the dsettings.json file before running Setup.ps1 script.

    Note:

    • Japanese characters are allowed only in Azure Resource Group Name and Azure App Service plan name.

    • For rest of the Azure resources that are being used in External portal - Storage Account, Endpoint, FunctionApp, CDN Profile and Custom Hostname , Japanese characters are not allowed from Microsoft Azure End.

11. Enter appropriate Relay Service name to be created on Azure. Press enter to create Relay.

12. Enter appropriate App Service Plan name to be created on Azure. Press enter to create App service plan.

13. Enter appropriate App Storage name to be created on Azure. Press enter to create App storage.

14. Enter appropriate Web App Storage name to be created on Azure. Press enter to create Web App storage.

15. Enter appropriate Function App name to be created on Azure. Press enter to create Function App.

16. Next provide consent to upload the PortalService.zip file to Azure for the function app created in last step.

17. Enter the appropriate profile name to be created on Azure. It is the CDN profile name. Press enter to create CDN profile.

18. Enter the appropriate Endpoint name to be created. It is the CDN Endpoint (It must be same as Prerequisite step 3, Example: aryabhataendpoint) on Azure. Press enter to create end point.

19. In case you get the message “EndPoint is not available: your end point name” follow below steps:

    Update the CNAME mapping with appropriate CDN endpoint name i.e., repeat Prerequisite step 3 and step 4.

    After CNAME mapping is updated then provide that endpoint name to PowerShell script. i.e., continue from step 18.

20. Enter the custom domain, it is the domain you have acquired in prerequisite step 4. Example: if your portal URL is https://fuse.wsevolve.com then provide “fuse.wsevolve.com” in custom domain. For troubleshooting the errors, refer to Troubleshooting Common Errors.

21. In a few minutes, all resources will be created / uploaded on Azure.

22. From the deployment folder copy the contents of dsettings.json file.

23. In Azure Portal, go to the Relay created in step 11. Select hybrid connections →Select evolvehybrid→click on Shared access policies→select Evolve in policy; and copy the Primary connection string.

24. Go to the Evolve site. Select the Portal and click on edit. Click on next on the first screen and you will see two new sections: Connection string and Deployment Metadata.

25. Copy the connection string copied in step 23 and Paste the content of dsettings.json into Deployment metadata copied in step 22.

26. Submit the Portal. You will observe the Config Status will be changed to Completed.

27. Setup steps are now completed. Do an IIS reset on all the WFE.

    Note:

    When you import or export an External Portal, check the Portal setup settings after import of portal and remove the settings those are not relevant for the destination environment.

    Using the same settings of External portal on two setups make the External portal stop working on both the environments.

28. Verify Setup: To verify everything is setup correctly, we can use Test Connection functionality.

    1. Go to the Evolve site. Select the Portal and click on edit. Click on next on the first screen and you will see Test Connection link. Clicking on this link should take you to Azure AD B2C login screen. As our user is still not added in B2C, so we will not be able to login.

    2. Add your user in portal: Go to Evolve and on the Users screen click on Portals count in front of the user and provide access on the Portal to your user. Click Save.

    3. You will receive an email with the sign-up link. Go to the Sign-up URL and follow the steps to create a user and password. This will add your user in Azure AD B2c.

    4. Now if you use Test Connection (step a), then you will be able to login and browse the portal. This tells us that everything is set up correctly.

Description of the Azure resources created as part of portal setup.

Adding additional portal (more than one)

While creating another portal we can reuse the Azure AD B2C, which work as an identity provider. To set up additional external portal follow all the steps you performed while setting your first external portal except the perquisite step 5 where we set up Azure AD B2C.

Instead of Prerequisites step 5 do below:

1. In Azure portal switch to your Azure AD B2C directory and open Azure AD B2C.

2. Go to App registrations and open the app which is registered for earlier created Portal.

3. Go to Authentication and in Single-page application add the Portal URL in Redirect URIs list and click Save. This Portal URL is same as defined in Prerequisites step 4. Example: https://fuse.wsevole.com.

4. Continue from Prerequisites step 6.

Upgrade Portal UI, Once Evolve server is upgraded

If you upgrade your Evolve server to newer version, then your external Portal will stop working as your Portal UI which is deployed on Azure also needs an upgrade. You will get below message when you browse portal. "Upgrade Required! The version of Portal UI is different from the version of Evolve Server. Please contact your Evolve Global administrator to upgrade the Portal UI and try again."

Follow below steps to upgrade the Portal UI:

1. Go to Portal tab on the left menu in Evolve and select the specific Portal and click on Download Package.

2. Unzip the downloaded file and you should be able to view files like PortalService, UI, Prerequisites.ps1 script, Setup.Ps1 script, dsettings.json, and other related files.

   Note: Step 3 is not mandatory. This is only required to install azure commands packages to your machine. If you have already done setup using current machine, you would not need to run Prerequisites.ps1 script.

3. Open PowerShell in admin mode and run the Prerequisites.ps1 script. Follow the instructions as they appear in PowerShell. This will install the required packages for deployment. You will see Name and Version listed; this indicates that all packages have been installed. Close the PowerShell window.

4. Open PowerShell in admin mode and run the Setup.ps1 script. Follow the instructions as they appear in PowerShell.

5. During upgrade you will not need to enter the details you entered during initial setup like Resource group, function app etc. Just that script can prompt user to login in separate browser window.

After running the script Portal UI will be updated on Azure and you can run the external portal. you should not encounter the Upgrade Required! error.

External Portal Upgrade(20.2 GA to 20.2.2 GA)

DocumentRedirectRule implemented in deployment script of 20.2.2 GA is not getting added on upgrading External Portal. For this you need to add the following rule for Azure EndPoint resource manually.

Follow the steps given below to add the rule manually:

1. Open Azure Resource Group used for External Portal.

2. Open EndPoint.

3. Click Rules Engine.

4. Add new Rule.

   URL path value - /svr/api/v1/wf/form/Documents/Get

   Hostname value - Function App Hostname

5. Save this rule and change order of this Rule to 1.

Setup External Users

Once the setup is completed, you are all set to setup the external users. Follow below steps for configuring external users for Portal use:

1. Go to Evolve. Select Users from left menu and click Add New User.

2. Disable the System IDP and add user details manually.

3. Click on Next. No need to assign license to the external users.

4. Click on Next and provide access to external user on the apps that are required.

5. Click on Submit.

6. On the Users screen click on Portal count in front of the user and provide access on the Portal to the external user. Click Save.

7. User will receive an email with the sign-up link.

8. Go to the sign-up URL and follow the steps to create a user and password.

9. Once user is created you can go to the Portal URL and access the Portal site.

For more information regarding troubleshooting, refer to Troubleshooting and Common Errors.