add Element for providers for membership (ASP.NET Settings Schema)

  • Article

Adds a membership provider instance to the membership provider collection.

This element is new in the .NET Framework version 2.0.

<configuration> Element
  system.web Element (ASP.NET Settings Schema)
    membership Element (ASP.NET Settings Schema)
      providers Element for membership (ASP.NET Settings Schema)
        add Element for providers for membership (ASP.NET Settings Schema)

<!-- SqlMembershipProvider syntax -->
<add name="string" 
     type="string" 
     connectionStringName="string"
     applicationName="MyApplication"
     commandTimeout
     description
     enablePasswordRetrieval="false"
     enablePasswordReset="true"
     requiresQuestionAndAnswer="true"
     requiresUniqueEmail="false"
     passwordFormat="Hashed"
     maxInvalidPasswordAttempts="5"
     passwordAttemptWindow="10"
     minRequiredPasswordLength
     minRequiredNonalphanumericCharacters
     passwordStrengthRegularExpression
/>
<!-- ActiveDirectoryMembershipProvider syntax -->
<add 
    name="string" 
    type="string" 
    applicationName
    attributeMapUsername="string" 
    attrbuteMapEmail="string" 
    attributeMapPasswordQuestion="string" 
    attributeMapPasswordAnswer="string" 
    attributeMapFailedPasswordAnswerCount="number" 
    attributeMapFailedPasswordAnswerTime="interval" 
    attributeMapFailedPasswordAnswerLockoutTime="interval" 
    clientSearchTimeout="interval"   
    serverSearchTimeout
    connectionUsername="string" 
    connectionPassword="string" 
    connectionProtection="string" 
    connectionStringName="connection string identifier" 
    enablePasswordReset="true|false" 
    enablePasswordRetrieval="true|false" 
    enableSearchMethods="true|false" 
    requiresQuestionAndAnswer="true|false" 
    maxInvalidPasswordAttempts="number" 
    passwordAttemptWindow="number" 
    commandTimeout="number" 
    description="string" 
    passwordAnswerAttemptLockoutDuration="interval" 
    minRequiredPasswordLength
    minRequiredNonalphanumericCharacters
    passwordStregnthRegularExpression="string" 
    passwordAnswerAttemptLockoutDuration="number" 
    requiresUniqueEmail="true|false" 
/>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute

Description

applicationName

Optional String attribute.

Specifies the name of the application under which membership data is stored at the data source. The application name enables multiple ASP.NET applications to use the same database without encountering duplicate user names for different applications. Alternatively, multiple ASP.NET applications can use the same membership information by specifying the same application name.

The membership providers that are included with the .NET Framework use the ApplicationVirtualPath value for the ApplicationName property, if no applicationName attribute is specified.

Although this attribute can be specified for the provider for Active provider, the provider ignores the value.

attributeMapUsername

Applies only to the ActiveDirectoryMembershipProvider attribute.

Optional String attribute.

Used to define the mapping from the UserName property on a MembershipUser object to the UserName attribute within the directory.

The default is userPrincipalName

attributeMapEmail

Applies only to the ActiveDirectoryMembershipProvider attribute.

Optional String attribute.

Used to define the mapping from the Email property on a MembershipUser object to the Email attribute within the directory.

The default is "mail".

attributeMapPasswordQuestion

Applies to the ActiveDirectoryMembershipProvider only.

Optional String attribute.

Used to define the mapping from the PasswordQuestion property on a MembershipUser object to an attribute within the directory.

The default is undefined. Thus, the administrator must explicitly configure this attribute in order to use the password question and answer functionality.

attributeMapPasswordAnswer

Applies to the ActiveDirectoryMembershipProvider only.

Optional String attribute.

Used to define the mapping from a user's password answer to an attribute within the directory.

The default is undefined. Thus, the administrator must explicitly configure this attribute in order to use the password question and answer functionality,

attributeMapFailedPasswordAnswerCount

Applies to the ActiveDirectoryMembershipProvider only.

Optional Int32 attribute.

Used to define the attribute in the directory that tracks failed password answer attempts.

The default is undefined. Thus, the administrator must explicitly configure this attribute in order to use the password question and answer functionality

attributeMapFailedPasswordAnswerTime

Applies to the ActiveDirectoryMembershipProvider only.

Optional Interval attribute.

Used to define the mapping from a property on a MembershipUser object to an attribute within the directory.

The default is undefined. Thus, if the administrator does not explicitly map the attribute to a class property, the functionality that is associated with that property will not try to set or get the value. In this case, the default behavior is implemented in the provider.

attributeMapFailedPasswordAnswerLockoutTime

Applies to the ActiveDirectoryMembershipProvider only.

Optional Interval attribute.

Used to define the attribute in the directory that stores when the user account was locked out due to too many bad password answers.

The default is undefined. Thus, the administrator must explicitly configure this attribute in order to use the password question and answer functionality

clientSearchTimeout

Applies to the ActiveDirectoryMembershipProvider only.

Optional Int32 attribute.

Allows an administrator to specify the LDAP query timeout on the client-side. For information about how client and server search time-outs work with query paging in the directory, see the documentation of the search methods for the provider for Active Directory.

serverSearchTimeout

Allows an administrator to specify the LDAP query timeout on the server-side. For information about how client and server search timeouts work with query paging in the directory, see the documentation of the search methods for the provider for Active Directory.

commandTimeout

Applies to the SQL provider only.

Optional Int32 attribute.

Specifies the number of seconds before a command that is issued to the membership data source times out. This time-out is used by the SQL provider when creating SqlCommand objects. This attribute is not set by default in the ASP.NET configuration. As a result, the ADO.NET default of 30 seconds is used. If this attribute is set, the SQL provider uses the configured time-out value for all SQL commands that are issued to the database.

The default is 30 (the ADO.NET default).

connectionStringName

Required String attribute.

Specifies the name of a connection string that is defined in the <connectionStrings> element. The specified connection string is by the provider that is being added.

connectionUsername

Applies to the ActiveDirectoryMembershipProvider attribute only.

Optional String attribute.

Defines the user name that is used for authentication purposes when connecting to the directory. If this attribute is specified, the connectionPassword attribute must also be specified.

Used instead of the process account or application impersonation credentials that are in effect when the provider connects to the directory.

connectionPassword

Applies to the ActiveDirectoryMembershipProvider attribute only.

Optional String attribute.

Defines the password that is used for authentication purposes when connecting to the directory. If this attribute is specified, the connectionUsername attribute must also be specified.

Used instead of the process account or application impersonation credentials that are in effect when the provider connects to the directory.

connectionProtection

Applies to the ActiveDirectoryMembershipProvider only.

Optional String attribute.

Defines the transport layer security options to use when opening connections to the directory. This attribute can be Secure or None.

If Secure, the provider tries to automatically select the highest level of connection security that is available based on the type of directory that the provider connects to. The protection is determined in the following manner and order:

  1. SSL.

    Because SSL works with both Active Directory and Active Directory Application mode (the Ssl value).

  2. If SSL is not available, and the provider is connecting to either Active Directory or to a domain-joined instance of Active Directory Application mode, encrypt-sign-and-seal is used (the SignAndSeal value).

  3. If neither SSL nor encrypt-sign-seal is available, the provider throws a ProviderException exception stating that it could not automatically select an encrypted channel to the configured directory.

If None, explicit credentials are required. If the connectionUsername and connectionPassword attributes were not supplied, a ProviderException exception is thrown stating that the default for using process credentials is not supported when using None for the connection protection.

description

Optional String attribute.

Specifies a description of the instance of the membership provider.

enablePasswordRetrieval

Optional Boolean attribute.

Specifies whether the membership provider instance supports password retrieval. If true, the membership provider instance supports password retrieval

The default is false for both the SQL and Active Directory providers.

You cannot set enablePasswordRetrieval to true in the configuration file for the ActiveDirectoryMembershipProvider. The provider does not allow retrieving passwords.

enablePasswordReset

Optional Boolean attribute.

Specifies whether the membership provider instance supports password reset. If true, the membership provider instance supports password reset.

The default is true for the SQL provider and false for Active Directory provider.

enableSearchMethods

Applies to the ActiveDirectoryMembershipProvider only.

Optional Boolean attribute.

Specifies whether search-oriented ActiveDirectoryMembershipProvider methods are available. If true, search-oriented ActiveDirectoryMembershipProvider methods are available.

The default is false.

maxInvalidPasswordAttempts

Optional Int32 attribute.

Specifies the number of allowed password or password answer attempts that are not valid. The membership user is locked out when the number of not valid attempts is the configured value.

The default is 5. .

Note that for the provider for Active Directory, this attribute only controls the number of password answer attempts that are not valid. The directory engine itself handles password lockouts.

minRequiredNonalphanumericCharacters

Optional Int32 attribute.

Specifies the minimum number of special characters that must be present in a valid password. This attribute cannot be set to a value that is less than 0, greater than 128, or greater than the value of the minRequiredPasswordLength.

The default is 1.

minRequiredPasswordLength

Optional Int32 attribute.

Specifies the minimum number of characters that are required in a password. This attribute cannot be set to a value that is less than 0 or greater than 128, which is the maximum length of an unencoded password for the SQL provider.

The default is 7.

name

Required String attribute.

Specifies the name of the provider instance. This is the value that is used for the defaultProvider attribute of the membership element to identify the provider instance as the default membership provider. The name of the provider is also used to index the provider in the Providers collection.

passwordAnswerAttemptLockoutDuration

Applies to the ActiveDirectoryMembershipProvider only.

Optional Int32 attribute.

Specifies the length of time, in minutes, for which a user account is locked out after providing too many bad password answers.

The default is 30 minutes.

passwordAttemptWindow

Optional Int32 attribute.

The number of minutes during which failed attempts are tracked. The window resets each time another failure occurs. If the maximum number of valid password or password answer attempts that are not valid occurs, the membership user is locked out.

The default is 10.

passwordFormat

Applies to the SQL provider only.

Optional String attribute.

One of the MembershipPasswordFormat values that indicates the format for storing passwords in the membership data store.

The default is Hashed.

passwordStrengthRegularExpression

Applies to the SqlMembershipProvider only.

Optional String attribute.

Specifies the regular expression that is used to evaluate a password. This attribute must be a regular expression that works with the Regex class.

The default is an empty string ("").

requiresQuestionAndAnswer

Optional Boolean attribute.

Specifies whether the instance of the membership provider requires a password answer for password reset and retrieval. If true, the the membership provider requires a password answer for password reset and retrieval.

The default is true for the SQL provider and false for the provider for Active Directory.

requiresUniqueEmail

Optional Boolean attribute.

Specifies whether an e-mail address that is stored on the server running Active Directory must be unique. If true, the membership provider instance requires a unique e-mail address.

The default is true the SQL provider and false for the provider for Active Directory.

type

Required String attribute.

Specifies the type name of a custom membership provider that that inherits the MembershipProvider abstract base class. For more information about working with a custom membership provider, see Implementing a Membership Provider.

Child Elements

None.

Parent Elements

Element

Description

configuration

Specifies the root element in every configuration file that si used by the common language runtime and the .NET Framework applications.

system.web

Specifies the root element for the ASP.NET configuration section.

membership

Configures an application for ASP.NET membership.

providers

Defines a collection of membership providers for ASP.NET membership.

Remarks

For more information about configuring the Active Directory membership provider, see ActiveDirectoryMembershipProvider.

Default Configuration

The following default add element is configured in the Machine.config file in the .NET Framework version 2.0.

  <providers>
    <add name="AspNetSqlMembershipProvider" type="System.Web.Security.SqlMembershipProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" connectionStringName="LocalSqlServer" enablePasswordRetrieval="false" enablePasswordReset="true" requiresQuestionAndAnswer="true" applicationName="/" requiresUniqueEmail="false" passwordFormat="Hashed" maxInvalidPasswordAttempts="5" minRequiredPasswordLength="7" minRequiredNonalphanumericCharacters="1" passwordAttemptWindow="10" passwordStrengthRegularExpression="" />
  </providers>

Example

The following code examples demonstrate how to configure an ASP.NET application to store and retrieve user information. The first example shows an ASP.NET application that is configured to use the SQLMembershipProvider.

<membership defaultProvider="SqlProvider"
            userIsOnlineTimeWindow="20">
    <providers>
        <add name="SqlProvider"
             type="System.Web.Security.SqlMembershipProvider"
             connectionStringName="SqlServices"
             enablePasswordRetrieval="false"
             enablePasswordReset="true"
             requiresQuestionAndAnswer="true"
             passwordFormat="Hashed"
             applicationName="/" />
    </providers>
</membership>

Element Information

Configuration section handler

System.Web.Configuration.MembershipSection

Configuration member

MembershipSection.Providers

Configurable locations

Machine.config

Root-level Web.config

Application-level Web.config

Requirements

Microsoft Internet Information Services (IIS) version 5.0, 5.1, or 6.0

The .NET Framework version 2.0

Microsoft Visual Studio 2005

See Also

Tasks

How to: Lock ASP.NET Configuration Settings

Reference

providers Element for membership (ASP.NET Settings Schema)

system.web Element (ASP.NET Settings Schema)

<configuration> Element

remove Element for providers for membership (ASP.NET Settings Schema)

clear Element for providers for membership (ASP.NET Settings Schema)

ActiveDirectoryMembershipProvider

System.Configuration

System.Web.Configuration

Concepts

ASP.NET Configuration Overview

ASP.NET Web Server Controls and Browser Capabilities

Securing ASP.NET Configuration

ASP.NET Configuration Scenarios

Other Resources

Managing Users by Using Membership

ASP.NET Configuration Files

ASP.NET Configuration Settings

General Configuration Settings (ASP.NET)

ASP.NET Configuration API