Alpha Anywhere Application Server for IIS Provider Configuration

Overview

 

There are four extension points that Alpha Anywhere Application Server for IIS uses to handle authentication, authorization, session, and profile data. These are defined in ASP.NET as the following providers:

These providers are configured in a web project profile settings that are used during publication. They use databases and/or other resources to fulfill their purpose. The web project settings create genie has a page for selecting the type of provider configuration your app uses.

Select security store type.

There are three types:
  • Active Directory
  • Specific IIS Providers
  • web.config (for testing only)
Users and groups may be defined by your application and may need to be published to a test, staging, or production database for use by the MembershipProvider and RoleProvider. This setting is also handled in this configuration and explained below.

Active Directory

The Active Directory option will only be available if you have configured the web application's security settings to use Active Directory. For details on configuring your application to use Active Directory for users and group see the Alpha Anywhere Application Server Active Directory Authentication and Authorization document.

The MembershipProvider and RoleProvider configuration is done through the Active Directory Configuration dialog in the Publishing An Application section in the document linked above. The session state and profile providers configuration are described in the Specific IIS Providers section below.

Specific IIS Providers

Provider Definition

Provider definitions can have different types of sources based on the selected provider. All providers have at least 4 types of sources:

  • SqlServer
  • MySQL
  • Oracle
  • Custom

The SqlServer, MySQL, and Oracle providers are version specific. The versions that are selectable are based on the installed assemblies for the provider. SqlServer's version is fixed at 2.0.0.0 and is already installed as part of ASP.NET. MySQL requires a version of the MySQL Connector/NET to be installed. If none is installed Alpha Anywhere Developer Edition can install version 6.7.4. Oracle requires a version of the Oracle Data Access Components to be installed. The packages for MySQL and Oracle also need to be installed on the IIS server. Alpha Anywhere Application Server for IIS includes a utility for installing MySql Connector/NET 6.7.4: A5InstallMySqlConnector.exe. This utility is located in the installation folder which defaults to C:\Program Files (x86)\A5V12 Application Server for IIS.

Require Client Certificates

A client certificate (also known as PKI authentication) is a way a user can be authenticated instead of using a login page with username and password prompts. This advanced feature is available for all "Specific IIS Providers" types.

A client certificate is issued by a certificate authority just like a server certificate. Whereas a server certificate validates the identity of a server, a client certificate validates the identity of a client e.g. user. When Require Client Certificates is enabled, the server will request that the client sends a client certificate with its request. The server will validate the client certificate as being issued by the stated certificate authority, is within the issued start and end date, and is not revoked. Once the certificate is valid the user is authenticated. The email address for that user is extracted from the certificate and that email address is used to authorize the user’s access to pages. The email address can be located either in the subject field or in the subject alternative name field.

In order for a server to validate a client certificate, a certificate for the certificate authority that issued the client certificate must be installed on the server. This certificate is typically stored in the server machine’s Intermediate Certificate Authorities store or the Trusted Root Certificate Authorities store.

Developing an application to use client certificates is the same as developing an application to use a login page with username and password prompts. The only special consideration that needs to be made is that user names must be an email address since an email address will be extracted from the client certificate to identify the user in the application.

An application can add a new user and assign that user to groups using Context.Security() methods in an "Administrator" level access pages as is typically done in Alpha Anywhere applications.

Using Require Client Certificates

Prerequisite: The IIS site must already exist and have an HTTPS binding set before publishing. Refer to the follow Microsoft documents for setting an HTTPS binding:

The publish profile defines whether or not a client certificate is required or not. However, a user and group assignments for that user must exist in the security tables before that user can be authenticated and authorized in the application. This is the same whether the user is authenticated with a username and password or with a client certificate. So the membership and role providers must first be defined as would be done when using usernames and passwords.

The option to require client certificates is located on the "Advanced Settings..." dialog of the Membership tab of the Security Store configuration page of the new publishing profile Genie.

Require client certificates setting in genie.

The option is also available in the publish profile property sheet in the membership provider group:

Require client certificates setting in property sheet.

Checking this option will configure the IIS site to require client certificates and will also disable anonymous authentication. When anonymous authentication is disabled no page for file can be accessed without a client client certificate.

After the application has been published with this setting, the browser will prompt the user for a client certificate to be sent to the server when a page is requested.

Role, Session State, and Profile

The Role, Session State, and Profile providers can all use the same provider definition as the Membership provider. They have the additional option of:

  • SameAsMembershipProvider

The Session State provider has 3 additional options specific to it:

  • LocalStateServer
  • StateServer
  • Redis

The Profile provider has one additional option specific to it:

  • None

The default source for Role, Session State, and Profile providers is SameAsMembershipProvider.

The following sections define the configuration settings for each source type.

SqlServer

Configure providers.

The SqlServer type uses the Microsoft SqlServer providers. These providers require a connection string to a database, and, except for the session state provider, a security application name. Additionally, you may want to publish users and groups through the membership and role providers. If you need to do this and the provider connection string does not have create/update access you can define a connection string to be used at publish time that has create/update access in the Create/Publish Connection String prompt. When the web profile is saved an attempt will be made to validate the database is set up for use by the provider. If the database cannot be found or parts of the schema are missing you will be prompted to create and/or initialized the database.

Once the web project profile is saved the provider databases will be checked if the connection string for create/update is changed. If you want to manually check the provider databases, select the the profile to be checked in the profile list and then click on the "More..." button underneath the profile list. Select the "Validate Provider Databases" from the pop-up menu and the databases will be created/initialized if they are not found or there are missing tables.

Validate provider databases.

MySQL

Configure MySQL providers.

The MySQL type is like the Sql Server type, but instead of validating the chosen database when the web profile is saved the MySQL type has an option for "Automatically generate and update schema" that can be selected. When this option is selected the MySQL provider will automatically generate or update the database schema when any of the providers are used. This built-in type uses MySQL .NET Connector 6.7.4.0. There is a utility named A5InstallMySQLConnector.exe that is packaged with Alpha Anywhere Developer Edition and Alpha Anywhere Application Server for IIS. Use it to install the MySQL .NET Connector 6.7.4.0 assemblies on an IIS server and register the assemblies in the GAC. This utility will also be used by Alpha Anywhere Developer Edition if needed when publishing users and roles of a web application.

IIS Manager has a feature named ".NET Users" and ".NET Roles" that can be used to view, edit and add users and roles. In order to use these two features when MySQL is the configured provider the MySQL assemblies need to be added to the list of "Trusted Providers" for IIS Manager. This can only be done by editing the C:\Windows\System32\inetsrv\config\administration.config file. You will need to do this from an editor "Run as Administrator" or from an editor started from an administrator command prompt. Edit the file and add the following 2 lines to the "trustedProviders" section:

<add type="MySql.Web.Security.MySQLMembershipProvider, MySql.Web, Version=6.7.4.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d" />

<add type="MySql.Web.Security.MySQLRoleProvider, MySql.Web, Version=6.7.4.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d" />


This does not need to be done to use MySQL providers in your web application. It is only needed to use the IIS Manager ".NET Users" and ".NET Roles" features.

Oracle

Configure Oracle providers.

The Oracle type does not generate the required schema. This must be done manually using the utilities installed with the Oracle Data Access Components 12c Release 3 (Release 12.1.0.2.1 for ODAC 12c Release 3). The version of the assemblies that get installed are 2.121.2.0.

IIS Manager has a feature named ".NET Users" and ".NET Roles" that can be used to view, edit and add users and roles. In order to use these two features when Oracle is the configured provider the Oracle assemblies need to be added to the list of "Trusted Providers" for IIS Manager. This can only be done by editing the C:\Windows\System32\inetsrv\config\administration.config file. You will need to do this from an editor "Run as Administrator" or from an editor started from an administrator command prompt. Edit the file and add the following 2 lines to the "trustedProviders" section:

<add type="Oracle.Web.Security.OracleMembershipProvider, Oracle.Web, Version=2.121.2.0, Culture=neutral, PublicKeyToken=89b483f429c47342" />

<add type="Oracle.Web.Security.OracleRoleProvider, Oracle.Web, Version=2.121.2.0, Culture=neutral, PublicKeyToken=89b483f429c47342" />


This does not need to be done to use Oracle providers in your web application. It is only needed to use the IIS Manager ".NET Users" and ".NET Roles" features.

Custom

A custom provider configuration has 1 required setting: The provider class name. This is the assembly qualified name of the class that implements the required provider interface. The assembly the class is in must be in the Global Assembly Cache on the server. It should also be installed on your development machine so that it can be used to populate its storage if needed as in the case of the membership or role providers. It is installed on your development machine you will also be able to choose it from the Select Provider Class dialog. The provider class usually has one or more parameters that can be set to configure how the provider should work. For instance, a membership provider may limit the number of failed password attempts. This value default to a number, but can be configured through a parameter. The "Edit provider parameters" button brings up a dialog for adding this parameters. Once a provider class is selected the parameters dialog will be pre-filled with the provider's public properties. Parameters can be removed, added, and changed as needed. If a provider class is not selected before using the "Edit provider parameters" dialog the list of parameters will be empty. The name of the provider class is displayed under the parameters list. See the Custom Provider Configuration document for an example of using Oracle as a customer provider.

Custom provider settings.

The Select Provider Class dialog has prompts for filtering the list of assemblies and an assembly's types. The filtering is applied as you type.

Select provider class.

Enter parameters required by provider class as name/value pairs with pre-filled names.

Enter parameters required by provider class as name/value pairs.

SameAsMembershipProvider

This source type for role, session State, and profile providers uses the same configuration that is defined for the membership provider. The same provider connection string, application name, and create/publish connection string will be used. This means all role, session state and profile data will be stored in the same database.

LocalStateServer

IIS is installed with an out of process state server named aspnet_state.exe. This is a Windows service. This service is set to manual start up by default. The Alpha Anywhere Application Server for IIS installation program sets this service to automatic start-up and ensures that it is running. The LocalStateServer setting will have IIS use this service for storing session state.

Redis

Redis session state provider configuration.

Redis is a free, distributable, in-memory database with a backing store and is the preferred session state provider when using IIS behind a load balancer. Session state under Redis is stored and accessed on a separate machine, allowing you to setup a web farm. Redis keeps data in-memory and only writes to disk as-needed.

Redis has built-in support for replication and can be run in a cluster. This ensures sessions are more reliable, allowing for failures such as server becoming unresponsive or loss of connectivity to a server with minimal service interruptions to the user.

When configuring Redis, the service should be setup to restrict port access and use an Access key. Using SSL is also recommended. See Appedix A: Configuring Redis for more details.

StateServer

This is similar to LocalStateServer. An aspnet_state.exe service is running on a remote machine and IIS will connect to that for storing session state. StateServer is also similar to Redis in that session state is stored/accessed on a separate machine which will allow you to set up a web farm. That is, allow you to have more than one web server process request for a single web site. Each web server will point to the same session state data. However, the aspnet_state.exe service only stores session state in memory so if the aspnet_state.exe service is shut down or crashes the session state data cannot be recovered. The amount of session state that it can handle is also restricted to the amount of memory on the system. Virtual memory means that running out of memory is unlikely, but performance will degrade as physical memory is exceeded.

In a web farm configuration, Redis is the preferred session state provider to use due to performance benefits.

None

The profile provider allows you to store persistent data for a logged in user. This is different from the Session State which is only persistent for the session lifetime. If your web application does not need user profile data or already manages user profile data in a different way, use None for the Profile provider source.

web.config (for testing only)

The web.config option is only appropriate for testing or proof-of-concepts where only a demonstration of users and groups is needed. The users and groups data is stored in the web application's web.config file which is only moderately secure, does not scale well, and is not easy to maintain. This option only has a pre-set configuration.

Publish Security Data

Security data (users and groups) for your application can be published to the security store that your membership and role providers use when your security store type is Specific IIS Providers. Alpha Anywhere has six different modes for publishing security data:

  • Preserve - Publish only if no users and roles are found in the destination. Both the user store and the role store must be empty for anything to get published. For example, if there is 1 user and no roles nothing (neither user nor roles) will get published because that one user already exists.
  • Ignore - Do not publish users or roles.
  • Merge - Add new users and roles. Any users and roles that don't exist in the store will be added. Existing users and roles remain unchanged.
  • Replace - Replace all users and roles. Any existing users and roles are removed user and role store and then the users and roles defined in the web project are added to the users and roles store.
  • Merge Roles - Add new roles. Any new roles defined in the web project are added to the role store.
  • Replace Roles - Replace all roles. All roles are delete from the role store and then the roles defined in the web project are added to the roles store. Note: If a role of the same name as a role that was deleted will be re-associated with any users that were members of the original role.
This option is set at the bottom of the genie dialog and it defaults Preserve.

Select how to publish security data.

The value you select is the default value used at publish time in the Publish Web Project dialog and the Publish Security Files dialog located in the Web Security dialog.

Publish Web Project dialog.

Web security dialog.

Publish security files dialog.

Modify Provider Configuration

Once a profile is saved, the provider configuration can be modified in the Miscellaneous section of the property grid for that profile.

Modify provider configuration.

Provider Configuration Example

This example uses a remote SqlServer Express database for membership, role, and session state. This example does not use a profile provider. A new database for membership, roles, and session state will be created and initialized. The SqlServer Express server instance already has a login defined for "AspNetDb_Test_User". This login will be added as a user in the new database, it will be given access to the database, and will be used in the provider connection string. I will use my domain account, which has sysadmin access, and integrated authentication for the create/publish connection string.

If you already have a web project profile for publishing the App Server Demo web application to an IIS server, you can use the "Duplicate Profile" button and then make changes to the new copy of the profile following these steps below. If you haven't created a web project profile for publishing the App Server Demo web application to an IIS server follow these instructions for creating a new profile.

Using a remote SqlServer Express instance when editing a duplicated profile

If you have already created a Web Project Profile by following the Getting Started Guide instructions, you can duplicate this profile and then change the provider configuration for the duplicate profile.

Web profile grid with Duplicate button highlighted.

After you have duplicated the profile scroll down to the bottom of the property grid to get to the Security Store Type combobox. It will be set to "web.config (for testing only)" since that was the only type available in earlier versions.

Duplicated web profile highlighting security store type.

  1. Change the Security Store Type to "Specific IIS Providers". This will reveal the rest of the configuration settings.

    Specific IIS providers selected.

  2. Click on the Membership Provider Connection String's "..." button to create a connection string. Enter your server name then enter "AspNetDb_Test_User" in the user prompt and enter the password for that user. (Or use an existing SqlServer user.)

    This example creates a new database. Since this user does not have access to create a database you cannot create the database from this dialog. If you want to test the connection make sure that the database name is blank so that the Test Connection won't attempt to connect to a database that doesn't exist yet. Once you have tested the connection enter "AspNetDb_Test" into the Database prompt and then click OK to save the connection string.

    Connection string dialog.

  3. Back in the property grid, leave the Membership Provider Application Name value set to "/".

  4. Click the "Use a Different Connection String for Membership Provider Create/Publish" to check it.

  5. Click on the Membership Provider Create/Publish Connection String's "..." button to create a connection string. It will default to the provider connection string.

  6. Click on the Use Windows Authentication check-box and then OK to save the connection string. If you are not using Windows authentication enter the credentials for a user with permission to create databases such as the "sa" user.

    Connection string dialog with Use Windows Authentication checked.

    Click OK to save the connection string.

  7. Back in the property grid, skip the Role Provider Type and Session State Provider Type prompts leaving them set to SameAsMembershipProvider. Change the Profile Provider Type to "None".

    Completed changes to profile's property grid.

  8. Click OK to save the changes to the profile. Since the database doesn't exist yet you will be prompted to create and initialize the database.

    Prompts for missing schema.

  9. Now you can publish using this new profile. See the Publish Web Project dialog to do this.

Using a remote SqlServer Express instance when creating a new profile

This example will revise the steps in the Application Server Demo publish example in the Alpha Anywhere Application Server for IIS Getting Started Guide. That example uses the "web.config (for testing only)" option. "web.config" was the only option before this provider configuration UI was implemented. Follow all the steps in the Getting Started Guide until you get to the Security Store Configuration genie page. Once you have completed the security store configuration steps, continue with the Getting Started Guide finishing the steps for publishing Application Server Demo web application.

Security Store Configuration Genie Page

  1. Click on the smart button to bring up the Create SQL Connection String dialog.

    Connection string smart button.

  2. Enter your server name, "AspNetDb_Test_User" in the user prompt and then the password for that user. (Or use an existing SqlServer user.)

    Connection string dialog.

  3. This example creates a new database. Since this user does not have access to create a database you cannot create the database from this dialog. If you want to test the connection make sure that the database name is blank so that the Test Connection won't attempt to connect to a database that doesn't exist yet. Once you have tested the connection enter "AspNetDb_Test" into the Database prompt.

  4. Click OK to create the connection string.

  5. Back on the Genie page, leave the default value of "/" in the Security application name prompt.

  6. Click on the "Advanced Settings..." button

    Membership provider advanced settings.

  7. Click on the "Use a different connection string for publishing security data." This will copy the provider connection string into the Create/Publish connection string prompt. Click on the smart button to bring up the Create SQL Connection String dialog.

    Create/publish connection string section.

  8. Click on the Use Windows Authentication check-box and then OK to save the connection string. If you are not using Windows authentication enter the credentials for a user with permission to create databases such as the "sa" user.

    Connection string dialog with Use Windows Authentication checked.

  9. When the connection string is saved the database schema will be validated. Since the database doesn't exist yet you will be prompted to create and initialize it.

    Prompt for create and initialize provider database.

  10. For the Role and Session State tabs keep the source set to "SameAsMembershipProvider". For the Profile tab, change the source to None.

    Set profile provider source to None.

  11. Since the role provider and session state provider use the "SameAsMembershipProvider" source, the database schema for the role and session state provider won't be validated until the profile is saved. You will get the following 2 prompts:

    Prompts for missing schema.

  12. Now you can continue with the rest of the instructions in the Getting Started Guide for publishing the App Server Demo web application to an IIS server.

Appendix

Appendix A: Configuring Redis

In order to use Redis as a session state provider, you must setup Redis on your server. If you don't have Redis installed as a service, or running on another machine, the easiest way to get started is to open a command window, change directory to the A5v12 executable folder and run redis-server.exe.

C:\Program Files (x86)\A5V12 Application Server for IIS>redis-server.exe

[12312] 30 Jun 13:49:33.959 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server.exe /path/to/redis.conf
                _._
            _.-``__ ''-._
        _.-``    `.  `_.  ''-._           Redis 3.0.501 (00000000/0) 64 bit
    .-`` .-```.  ```\/    _.,_ ''-._
    (    '      ,       .-`  | `,    )     Running in standalone mode
    |`-._`-...-` __...-.``-._|'` _.-'|     Port: 6379
    |    `-._   `._    /     _.-'    |     PID: 12312
    `-._    `-._  `-./  _.-'    _.-'
    |`-._`-._    `-.__.-'    _.-'_.-'|
    |    `-._`-._        _.-'_.-'    |           http://redis.io
    `-._    `-._`-.__.-'_.-'    _.-'
    |`-._`-._    `-.__.-'    _.-'_.-'|
    |    `-._`-._        _.-'_.-'    |
    `-._    `-._`-.__.-'_.-'    _.-'
        `-._    `-.__.-'    _.-'
            `-._        _.-'
                `-.__.-'

[12312] 30 Jun 13:49:33.986 # Server started, Redis version 3.0.501
[12312] 30 Jun 13:49:33.989 * The server is now ready to accept connections on port 6379

In a production environment, Redis should be configured to restrict port access to trusted clients. Redis should also be configured to use SSL if Reids is outside the firewall. For information on how to configure Redis securely, visit the following resources:

  • Redis configuration - Includes a link to a self documented example redis.config file that can be used to configure Redis
  • Redis Security - Check out the sections on "Network security", "Authentication feature", and "Data encryption support".