Alpha Anywhere Application Server for IIS Migration Guide

This section contains information about features an application running on the stand-alone server may use that could behave differently under IIS and what you can do to get those features working under IIS. Not all applications use these features so these may not apply to your application.

1. Security data is stored differently on IIS

   This feature will affect most applications. Alpha Anywhere Application Server for IIS uses ASP.NET's membership and role providers for authentication and authorization. Membership and role providers are abstract interfaces. These abstract interfaces are a consistent API across implementations. The same interface is used with a membership provider implemented for SqlServer as is used for a membership provider implemented for MySQL. Each implementation is free to store security data in any way it sees fit. This implementation detail (the persistence of security data) is hidden from the application using the membership and/or role provider. An Alpha Anywhere application running under IIS uses providers supplied by the chosen database vendor. These providers do not use the Alpha Anywhere Application Server's schema for security data. This means security data must be migrated to the schema used by the database vendor's provider. See more details in the Migrate Security Data section.

   This also affects how you develop and maintain an application with security. When users and groups are defined in the Web Security settings in Alpha Anywhere Developer Edition there are two options for storing the users and groups: DBF and SQL Database. When SQL Database is selected, users and groups of a production application can be managed through the Alpha Anywhere Developer Edition or by pages in the application that are usually restricted administrator level users. This is no longer the case with IIS since a deployed application's security data is stored in IIS provider specific database tables. The users and groups stored in the DBF or SQL Database are published to the IIS provider specific database tables at application publish time or by way of the "Publish Security Files" feature in the Alpha Anywhere Developer Edition Web Security control panel. Day to day user management (such as adding users, disabling users, resetting passwords, and adding users to groups) needs to be done by administrator level pages in the application. Alpha Anywhere Developer Edition has built-in security components that can be used for creating pages for managing users. An application can also use methods and properties on the Context.Security object for managing users and groups within the application.

2. Authorization works with a slight difference on IIS

   This difference is abstracted away by Alpha Anywhere. Any applications created with Alpha Anywhere 3.0 or later do not require any change. If an application was created before Alpha Anywhere 3.0 a bulk update operation to update component security needs to be run before the application can be published to IIS. To run this bulk update operation, select the web control panel, then "Edit" on the main menu, then "Bulk Operation", and then "Update component security settings (if using Active Directory or IIS)". The need to run this operation will be tracked and if this operation needs to be run you will be prompted to do so at publish time.

3. Web server process runs under a virtual account on IIS

   1. File/folder access

      This difference will most notably affect file/folder access. An application pool will be set to run as "Application Pool Identity" by default. This means that IIS will create a virtual account and this account has minimal access. It will have access to read and execute from the web root and have access write to a temporary folder. If an application writes to the web root, to folders outside of web root, reads files outside of the web root the application will be denied access to those folders under IIS. The virtual account must be given the needed access to these other folders, or the application needs to be changed to do the work in a different way. The name of a virtual account has the following pattern:
      IIS APPPOOL\<Application Pool Name>
      If the application pool name is Default Web Site_TestApp then the virtual account name is
      IIS APPPOOL\Default Web Site_TestApp
      Instead of giving access to specific virtual account(s) access can be granted to the built-in group IIS_IUSRS. This group includes all virtual accounts so this option should not be used if multiple applications on the same server should not have access to each other's files/folders.
      If an application runs external programs the folder the external program is in must have Read & Execute access for the application pool identity account or IIS_IUSRS group. Any files or folders the external program uses must have the appropriate access too.
      
      If an external program is run using sys_shell(), it may need to be changed to use sys_shell_result() or use the Helper::ShellProcess object instead:

      dim sp as Helper::ShellProcess = Helper::ShellProcess::Create(" path", "-e") sp.waitUntilTerminate() 'sp.output contains the console output

   2. Connection strings that use Windows Authentication

      Connection strings that use Windows Authentication rather than a username and password will also be affected because the connection to the database will be done under the virtual account. The virtual account probably will not have access to the database. If Windows authentication must be used instead of database credentials, there are a few options.
      1. A virtual account is local to the machine. If the database server is also on the IIS server machine, the virtual account can be granted access to the database.
      2. If the database server is on a remote machine and both the remote machine and the IIS server machine are members of an Active Directory domain, the IIS server machine can be granted access to the database under the machine's account. The machine's account is the machine's name followed by a "$". e.g. "MyDbServer$". Note that this will grant access to any network level process that is running on the IIS server machine so this access may be too broad. Refer to the Microsoft documentation on machine accounts for more details.
      3. The application pool's identity can be changed to use a specific Active Directory domain user instead of using the virtual account with "Application Pool Identity". Refer to the Microsoft IIS documentation on setting an application pool to use a specific account.

   3. Mapped drives to shares

      Mapped drive settings are stored in a user's profile. An application pool by default does not load the user's profile. Additionally, a virtual account's user profile is very impractical and some times impossible to set. This means mapped drives won't be available for an application. Use UNC paths instead.

   4. Regional settings

      Regional settings are another user account setting. When Windows is first set up on a machine the default system regional settings are configured. New user accounts inherit this setting. The application pool's virtual account is created at the time the application pool is create and inherits regional settings from the original system regional settings. Windows may have originally been installed with English (United States) as the default regional settings, so the virtual account will have its regional settings set to English (United States). This will happen even if an application pool is created by a user that has regional settings set to something else like Dutch (Belgium). To have a virtual account set to a different regional setting when it is created, you must change the default regional settings for system and new user accounts. Go to the Windows Control Panel "Clock, Language, and Region" settings, click on the "Region" item, and then click on the "Administrative" tab. This tab has a "Copy settings..." button which can be used to copy the current user's regional settings to be the default for system accounts and new user accounts. Once this is done, an application will run with the expected regional settings.

      

   An alternative solution to the above items is to manual create or set an application pool to use a specific user that already has access to files, folder, or database servers. You may also need to set the application pool to "Load User Profile" in the application pool's advanced settings dialog.

   

   IIS publish will not overwrite an existing application pool so you can specify the application pool name in the publish profile so your application will use this manually created application pool.
   If you do choose to create an application pool manually it must be configured correctly to work with Alpha Anywhere Application Server for IIS. Here are the required settings. They can be set in the application pool's "Advanced Settings" dialog.
   
   

   • .NET Framework Version must be set to v4.0.
   • Enable 32-Bit Applications must be set to true.
   • Start Mode should be set to AlwaysRunning (this will allow for quicker initial response from IIS).
   • Maximum Worker Processes should be set to at least 5.

4. Password recovery is not supported on IIS

   The security configuration Data Recovery option "Lost password action" "Recover Password" is not supported on IIS.

   

5. Password reset when user forgot security question answer

   Alpha Anywhere Application Server for IIS does not directly manipulate security data in a database. It instead uses an API that third party providers like SqlServer and MySQL must implement. This created a need for an API that is available to an application developer to reset a user's password when the security configuration "Lost password action" is set to "Reset Password", an answer to a security question is required, and the user has forgotten the answer to the security question. Use the Context.Security.AdministrativePasswordReset() method to do this. An a5w page or component that uses this method should only be accessible to administrator level users.

6. Legacy components are not supported on IIS

   Legacy dialog components will not work under IIS. They need to be converted before they will work under IIS. Right click on the legacy component in the Web Project control panel and then select the "Create New Dialog component from the legacy Dialog component" menu item to do this conversion.

   

The Context object is now the recommended way to interface with the server in server side code. The Context object is available anywhere server side code runs. This includes a5w pages and components. The Context object works the same whether an application runs under IIS or the stand-alone server and contains properties of the server and interfaces for the request, response, session, and security of the running application. If any other web server platforms supported in the future, the Context object will support these platforms too.

Introduction

Security data (users, groups, and membership) are stored differently under IIS than under Alpha Anywhere Application Server. This means an application running under IIS cannot use the same security data as the application running under the Alpha Anywhere Application Server. When an application running in production under Alpha Anywhere Application Server is moved to IIS, the security data must be migrated to an IIS provider schema. The specific schema that is used by an IIS provider is defined by the provider. Alpha Anywhere Application Server has a Genie in the server settings dialog to export security data and the Alpha Anywhere Application Server for IIS has a utility named A5IISMigrateSecurityData.exe to import security data in to an IIS provider.

The following security data are migrated with steps that follow:

• Users
  • Name
  • Password
  • Email Address
  • Security Question
  • Security Question Answer
  • Locked Out

    A user may be locked out because of too many failed log in attempts or because an application administrator has manually disabled the user. A user that is locked out because of too many failed log in attempts is typically automatically re-enabled after a period of time. When a user in this state is migrated, the user is treated as if an application administrator has manually disabled the user so the user must be manually re-enabled by an application administrator.

• Groups (roles)
• Membership – The list of groups to which each user belongs.

Security Data Migration Steps

1. Create a publish profile to publish to an IIS server. Part of the publish profile includes configuring the membership provider (for users) and role provider (for groups) to be used by the application. See the Provider Configuration documentation for more information on choosing providers.
2. The schema for the membership provider must be initialized before continuing. Refer to your provider's documentation on how to initialize the schema. It usually involves running a SQL script or utility supplied by the provider. In the case of SQL Server Alpha Anywhere will attempt to initialize the schema when the provider is defined in the publish profile. You can also verify the SQL Server provider schema by editing the publish profile and then clicking on the "More..." button and selecting "Validate Provider Databases". MySQL has an option in the provider definition "Membership Provider Auto Generate Schema" to automatically generate the required schema.
3. Publish using the newly created publish profile. The publish dialog has an option to publish security data. This option will publish security data as defined in Alpha Anywhere Developer Edition. This data will not contain an accurate lock out status of users since the lock out status data is kept on the production web server. Since you will be exporting data from the production server instead, choose the "Ignore - Do not publish users and roles." option. This option will define the membership and role providers in the published application. This is needed in order to import users, groups, and membership under IIS.
4. Go to the application server settings dialog in Alpha Anywhere Application Server. This dialog is opened from the context menu of the Alpha Anywhere Application Server tray icon.

   

5. Select the tab labeled “Other” and click on the “Open the Users and Groups Migration Genie” link.

   

6. The User and Groups Migration Genie has an information section to explain its purpose. The information section contains a checkbox labeled “Migrate a web application's security data”. This check box will need to be selected in order to continue with the rest of the genie.

   

7. After selecting the “Migrate a web application's security data” checkbox, the genie will scan the application server for applications that have security data. Select an application and then choose a location for the exported data. The export process will also generate a key for securing sensitive data like passwords, and security questions and answers. This key will be stored in a file with a .key extension. If needed, this .key file can be kept apart from the data file making it easier to move the data file securely to the IIS server. You will only need the .key file once the data file is on the IIS server and you are ready to import the security data. You may also select to encrypt the entire security data file rather than just the sensitive data in it.

   

8. Click the “Export Data” button to begin the export. The export may take some time depending on the amount of users, groups, and number of users assigned to groups. When the export is finished a Windows file explorer window will open to the folder with the .data and .key file and the .data file will be selected. Now the files can be moved to the IIS server.

   

9. Use any means to move the .data file to the IIS server. If you do not want to move the .key file over a network you can copy it to a thumb drive and carry it to the IIS server. When you are ready to do the import copy the .key file from the thumb drive into the same folder as the .data file.
10. Now that the .data and .key files are on the IIS server the A5IISMigrateSecurityData.exe utility can be used to import the security data. This utility is located in the installation folder which defaults to C:\Program Files (x86)\A5V12 Application Server for IIS. This utility must be “Run as administrator” to ensure that it has access IIS application configurations.

    

11. Enter or select the .data file name. If the entire file is encrypted the “Inspect Security Data” button can be used to review the security data before importing. Sensitive data (passwords, security questions and answers) will still be encrypted.

    

12. Select the web application that you published in step 1. The web application has the connection string to the database for the security data. Depending on how the application is allowed to access the database alternate credentials may be needed to import the security. For instance, your application may not add new users so the database credential may only allow read access. In order to do the import write access is needed so alternate credential will need to be supplied.

    

13. Select the import mode. “Merge” is non-destructive. All existing users and roles will remain unchanged. There is a “Replace” option. This option is destructive. All existing users and roles will be deleted before adding new users and roles so use caution choosing this option.
14. Click on the Import button to begin the import. Progress will be shown as the import is being done. Progress is also logged and this log can be reviewed after the import is completed.

    

15. Run your application and test login and page access.