ActiveDirectoryMembershipProvider Class
TOC
Collapse the table of content
Expand the table of content

ActiveDirectoryMembershipProvider Class

 

Manages storage of membership information for an ASP.NET application in Active Directory and Active Directory Application Mode servers.

Namespace:   System.Web.Security
Assembly:  System.Web (in System.Web.dll)

System.Object
  System.Configuration.Provider.ProviderBase
    System.Web.Security.MembershipProvider
      System.Web.Security.ActiveDirectoryMembershipProvider

[DirectoryServicesPermissionAttribute(SecurityAction.LinkDemand, 
	Unrestricted = true)]
[DirectoryServicesPermissionAttribute(SecurityAction.InheritanceDemand, 
	Unrestricted = true)]
public class ActiveDirectoryMembershipProvider : MembershipProvider

NameDescription
System_CAPS_pubmethodActiveDirectoryMembershipProvider()

Creates a new instance of the ActiveDirectoryMembershipProvider class.

NameDescription
System_CAPS_pubpropertyApplicationName

The name of the application using the custom membership provider.(Overrides MembershipProvider.ApplicationName.)

System_CAPS_pubpropertyCurrentConnectionProtection

Gets the current level of security being used to protect communications with the server.

System_CAPS_pubpropertyDescription

Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs).(Inherited from ProviderBase.)

System_CAPS_pubpropertyEnablePasswordReset

Gets a value indicating whether the ActiveDirectoryMembershipProvider instance is configured to allow users to reset their passwords.(Overrides MembershipProvider.EnablePasswordReset.)

System_CAPS_pubpropertyEnablePasswordRetrieval

Gets a value indicating whether the user's password can be retrieved from the Active Directory data store. This property always returns false.(Overrides MembershipProvider.EnablePasswordRetrieval.)

System_CAPS_pubpropertyEnableSearchMethods

Gets a value indicating whether search-oriented ActiveDirectoryMembershipProvider methods are available.

System_CAPS_pubpropertyMaxInvalidPasswordAttempts

Gets the number of failed answer attempts a user is allowed for the password-reset question.(Overrides MembershipProvider.MaxInvalidPasswordAttempts.)

System_CAPS_pubpropertyMinRequiredNonAlphanumericCharacters

Gets the minimum number of special characters that must be present in a valid password.(Overrides MembershipProvider.MinRequiredNonAlphanumericCharacters.)

System_CAPS_pubpropertyMinRequiredPasswordLength

Gets the minimum length required for a password.(Overrides MembershipProvider.MinRequiredPasswordLength.)

System_CAPS_pubpropertyName

Gets the friendly name used to refer to the provider during configuration.(Inherited from ProviderBase.)

System_CAPS_pubpropertyPasswordAnswerAttemptLockoutDuration

Get the length of time for which a user account is locked out after the user makes too many bad password-answer attempts.

System_CAPS_pubpropertyPasswordAttemptWindow

Gets the time window during which consecutive failed attempts to provide a valid password or a valid password answer are tracked.(Overrides MembershipProvider.PasswordAttemptWindow.)

System_CAPS_pubpropertyPasswordFormat

Gets a value indicating the format of passwords in the Active Directory data store.(Overrides MembershipProvider.PasswordFormat.)

System_CAPS_pubpropertyPasswordStrengthRegularExpression

Gets the regular expression used to evaluate a password.(Overrides MembershipProvider.PasswordStrengthRegularExpression.)

System_CAPS_pubpropertyRequiresQuestionAndAnswer

Gets a value indicating whether the membership provider is configured to require a password question and answer when creating a user.(Overrides MembershipProvider.RequiresQuestionAndAnswer.)

System_CAPS_pubpropertyRequiresUniqueEmail

Gets a value indicating whether an e-mail address stored on the Active Directory server must be unique.(Overrides MembershipProvider.RequiresUniqueEmail.)

NameDescription
System_CAPS_pubmethodChangePassword(String, String, String)

Changes the password for the specified user.(Overrides MembershipProvider.ChangePassword(String, String, String).)

System_CAPS_pubmethodChangePasswordQuestionAndAnswer(String, String, String, String)

Updates the password question and answer for a user in the Active Directory store.(Overrides MembershipProvider.ChangePasswordQuestionAndAnswer(String, String, String, String).)

System_CAPS_pubmethodCreateUser(String, String, String, String, String, Boolean, Object, MembershipCreateStatus)
System_CAPS_protmethodDecryptPassword(Byte[])

Decrypts an encrypted password.(Inherited from MembershipProvider.)

System_CAPS_pubmethodDeleteUser(String, Boolean)

Removes a user's membership information from the Active Directory data store.(Overrides MembershipProvider.DeleteUser(String, Boolean).)

System_CAPS_protmethodEncryptPassword(Byte[])

Encrypts a password.(Inherited from MembershipProvider.)

System_CAPS_protmethodEncryptPassword(Byte[], MembershipPasswordCompatibilityMode)

Encrypts the specified password using the specified password-compatibility mode.(Inherited from MembershipProvider.)

System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodFindUsersByEmail(String, Int32, Int32, Int32)

Returns a collection of membership users from the Active Directory data store based on the user's e-mail address.(Overrides MembershipProvider.FindUsersByEmail(String, Int32, Int32, Int32).)

System_CAPS_pubmethodFindUsersByName(String, Int32, Int32, Int32)

Returns a collection of users from the Active Directory data store based on the user name.(Overrides MembershipProvider.FindUsersByName(String, Int32, Int32, Int32).)

System_CAPS_pubmethodGeneratePassword()

Generates a random password.

System_CAPS_pubmethodGetAllUsers(Int32, Int32, Int32)

Gets a collection of all the users stored in an Active Directory data source.(Overrides MembershipProvider.GetAllUsers(Int32, Int32, Int32).)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetNumberOfUsersOnline()

Throws a NotSupportedException exception in all cases.(Overrides MembershipProvider.GetNumberOfUsersOnline().)

System_CAPS_pubmethodGetPassword(String, String)

Returns the password of the specified user from the database. The ActiveDirectoryMembershipProvider class does not support this method.(Overrides MembershipProvider.GetPassword(String, String).)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodGetUser(Object, Boolean)

Gets the membership user information associated with the specified user key.(Overrides MembershipProvider.GetUser(Object, Boolean).)

System_CAPS_pubmethodGetUser(String, Boolean)

Gets the membership user information associated with the specified user name.(Overrides MembershipProvider.GetUser(String, Boolean).)

System_CAPS_pubmethodGetUserNameByEmail(String)

Gets the user name associated with the specified e-mail address.(Overrides MembershipProvider.GetUserNameByEmail(String).)

System_CAPS_pubmethodInitialize(String, NameValueCollection)

Initializes the ActiveDirectoryMembershipProvider instance with the property values from the application's configuration files. This method is not intended to be called from your code.(Overrides ProviderBase.Initialize(String, NameValueCollection).)

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_protmethodOnValidatingPassword(ValidatePasswordEventArgs)

Raises the ValidatingPassword event if an event handler has been defined.(Inherited from MembershipProvider.)

System_CAPS_pubmethodResetPassword(String, String)

Resets a user's password to a new, automatically generated password.(Overrides MembershipProvider.ResetPassword(String, String).)

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

System_CAPS_pubmethodUnlockUser(String)

Clears a lock so that a membership user can be validated.(Overrides MembershipProvider.UnlockUser(String).)

System_CAPS_pubmethodUpdateUser(MembershipUser)

Updates information about a user in the Active Directory data store.(Overrides MembershipProvider.UpdateUser(MembershipUser).)

System_CAPS_pubmethodValidateUser(String, String)

Verifies that the specified user name and password exist in the Active Directory data store.(Overrides MembershipProvider.ValidateUser(String, String).)

NameDescription
System_CAPS_pubeventValidatingPassword

Occurs when a user is created, a password is changed, or a password is reset.(Inherited from MembershipProvider.)

This class is used by the Membership and MembershipUser classes to provide membership services for an ASP.NET application using an Active Directory (AD) or Active Directory Application Mode (ADAM) server.

System_CAPS_noteNote

Using an ADAM server requires specific configuration. For more information, see the ADAM Configuration section below.

System_CAPS_security Security Note

The ActiveDirectoryMembershipProvider instance works only in the full-trust policy default configuration of ASP.NET. In order to use the ActiveDirectoryMembershipProvider instance at any partial-trust level, either you must make changes to the appropriate trust policy file for your application or you must create a "sandbox" assembly that is deployed in the GAC.

The ActiveDirectoryMembershipProvider class requires unrestricted DirectoryServicesPermission permission to run. This permission is not added to any of the partial-trust policy files supplied with ASP.NET. Although adding the DirectoryServicesPermission permission to a partial-trust policy file will enable use of the ActiveDirectoryMembershipProvider class, doing so makes the System.DirectoryServices namespace classes available to any code running in your ASP.NET pages. This option is not recommended for any Web servers that need to run in a secure, locked-down mode.

As an alternative, you can create a "sandbox" assembly that calls the ActiveDirectoryMembershipProvider class. This assembly can contain either a wrapper class that forwards method calls to the ActiveDirectoryMembershipProvider class or a class that derives from the ActiveDirectoryMembershipProvider class. In either case, the wrapper class must assert unrestricted DirectoryServicesPermission permission. Deploy the sandbox assembly in the GAC and mark the assembly with the AllowPartiallyTrustedCallersAttribute (APTCA) attribute. This will enable your partially trusted ASP.NET code to call your wrapper class, and since the wrapper class internally asserts the unrestricted DirectoryServicesPermission permission, your wrapper class will be able to successfully call the provider

You must create a connectionStrings Element (ASP.NET Settings Schema) entry in the Web.config file that identifies the Active Directory server, Active Directory domain, or ADAM application partition to use. The provider will only operate at domain scope, or in a subscope within a domain. The following table lists allowed connection strings and the scope used.

Connection string

Scope

LDAP://<domain or server>:[port]

Port number is optional for ADAM and not needed for Active Directory.

The provider runs against the specified domain or server. With AD, user creation and deletion is done in the default users container. All other operations, including any search methods, will be rooted at the default naming context for the domain.

If the connection string specifies an Active Directory domain rather than a specific server and the EnablePasswordReset property is true, the ActiveDirectoryMembershipProvider instance will always connect to the server with the PDC role for the domain to ensure that password changes take effect and are available when the ValidateUser method is called.

This connection string is not allowed when using ADAM, and will throw a NotSupportedException.

LDAP://<domain or server>:[port]/<container dn>

Port number is optional for ADAM and not needed for Active Directory.

The provider runs against the specified domain or server. User creation and deletion is only done in the specified container. All other operations, including any search methods, perform subtree searches rooted at the container.

For ADAM servers, the container specifies the root of an application partition, or a container within an application partition.

We recommend that the connection string define a specific container to improve performance.

The ActiveDirectoryMembershipProvider instance maps directory attributes to ActiveDirectoryMembershipUser properties. Default attributes are used if no attribute mapping is done in the Web.config file. For more information on attribute mappings, see the individual properties in the ActiveDirectoryMembershipUser class documentation.

The following table lists the ActiveDirectoryMembershipUser properties and their default attribute mappings.

System_CAPS_security Security Note

The ActiveDirectoryMembershipProvider class does not explicitly check that provider attributes are not mapped to core attributes of the user object in the directory. You must ensure that sensitive information from the directory is not exposed through mapped attributes.

Property

Default directory attribute

Can be mapped?

ProviderUserKey

securityIdentifier

No

UserName

userPrincipalName

Yes, but must be either userPrincipalName or sAMAccountName

Comment

comment

No

CreationDate

whenCreated

No

Email

mail

Yes, but must be a single-valued attribute of type Unicode String.

LastActivityDate

n/a

Not supported by ActiveDirectoryMembershipProvider.

LastLoginDate

n/a

Not supported by ActiveDirectoryMembershipProvider.

LastPasswordChangedDate

pwdLastSet

No

PasswordQuestion

none

Yes, but must be a single-valued attribute of type Unicode String.

IsApproved

User-Account-Control (AD)

mDS-UserAccountDisabled (ADAM)

No

IsLockedOut

computed from lockoutTime and the AD lockout duration (AD on Windows 2000)

msDS-User-Account-Control-Computed (AD on Windows Server 2003)

msDS-User-Account-Control-Computed (ADAM)

No

LastLockoutDate

If user is locked out due to too many bad password attempts, the lockout time attribute is returned.

If user is locked out due to too many bad password answer attempts, the value stored in the attribute defined by attributeMapFailedPasswordAnswerLockoutTime is returned.

If user is locked out due to both a bad password and too many bad password attempts, the most recent date/time value is returned.

If the account is not locked out, return 1/1/1754 for SQL compatibility.

No

When both the RequiresQuestionAndAnswer and EnablePasswordReset properties are true, the ActiveDirectoryMembershipProvider class supports password-reset security by requiring the user to answer a predetermined question. To support the question and answer, you must set the following configuration attributes using the add Element for providers for membership (ASP.NET Settings Schema) in the application configuration file.

Configuration attribute

Attribute type

attributeMapPasswordQuestion

Must be a single-valued attribute of type Unicode String.

attributeMapPasswordAnswer

Must be a single-valued attribute of type Unicode String.

attributeMapFailedPasswordAnswerCount

Must be a single-valued attribute of type Integer.

attributeMapFailedPasswordAnswerTime

Must be a single-valued attribute of type Large Integer/Interval.

attributeMapFailedPasswordAnswerLockoutTime

Must be a single-valued attribute of type Large Integer/Interval.

For more information on using password-reset security, see the RequiresQuestionAndAnswer property.

When the ActiveDirectoryMembershipProvider class is used to connect to an Active Directory or an Active Directory Application Mode (ADAM) server, the connectionProtection attribute that is set using the add Element for providers for membership (ASP.NET Settings Schema) in the application configuration file may restrict the types of operations the ActiveDirectoryMembershipProvider class can perform over the connection. The connectionProtection attribute also determines the methods the ActiveDirectoryMembershipProvider instance will use to create the connection to the Active Directory or ADAM server.

The following table shows the effect of the connectionProtection attribute when connecting to an Active Directory.

connectionProtection setting

Effect

None

The ActiveDirectoryMembershipProvider class will connect to an Active Directory, with these restrictions.

Secure

The ActiveDirectoryMembershipProvider class will attempt to connect to Active Directory using SSL. If SSL fails, a second attempt to connect to Active Directory using sign-and-seal will be made. If both attempts fail, the ActiveDirectoryMembershipProvider instance will throw a ProviderException exception.

Both process credentials and explicit credentials are supported.

The following table shows the effect of the connectionProtection attribute when connecting to an ADAM server.

connectionProtection setting

Effect

None

The ActiveDirectoryMembershipProvider class will connect to an ADAM server, with this restriction.

  • Any method that sets passwords will fail unless you explicitly configure the ADAM server to allow passwords to be sent and changed over an insecure connection.

Both process credentials and explicit credentials are supported.

Secure

The ActiveDirectoryMembershipProvider class will attempt to connect to the ADAM server using SSL. If a connection cannot be made, the ActiveDirectoryMembershipProvider instance will throw a ProviderException exception.

Both process credentials and explicit credentials are supported.

When using an ADAM server, the ADAM instance must contain a schema that defines the User class. You can import the User class with an LDIF import of the MS-User.ldf file available in the ADAM install directory.

The ActiveDirectoryMembershipProvider class will work with an ADAM server configured to use the default network ports. The following table shows the defaults expected for the ADAM server.

connectionProtection setting

Expected ADAM port

None

389

Secure

636

If your ADAM server is not using the default ports, see article Q817583, "Active Directory Services does not request secure authorization over an SSL connection," in the Microsoft Knowledge Base.

The following code examples show the Web.config file for an ASP.NET application configured to use an ActiveDirectoryMembershipProvider instance. The first example uses the default mappings for Active Directory attributes, and does not support password-reset security with question-and-answer nor the ability to call search methods. The second example shows all the attribute settings allowed for an ActiveDirectoryMembershipProvider instance.

The first example is a simple configuration file using default mappings for Active Directory attributes.

<configuration>
  <connectionStrings>
    <add name="ADService" connectionString="LDAP://ldapServer/" />
  </connectionStrings>
  <system.web>
    <membership defaultProvider="AspNetActiveDirectoryMembershipProvider">
      <providers>
        <add name="AspNetActiveDirectoryMembershipProvider" 
          type="System.Web.Security.ActiveDirectoryMembershipProvider, 
          System.Web, Version=2.0.3600, Culture=neutral, 
          PublicKeyToken=b03f5f7f11d50a3a" />
      </providers>
    </membership>
  </system.web>
</configuration>

This example shows all of the attribute settings that are available for an instance of ActiveDirectoryMembershipProvider.

<configuration>
  <connectionStrings>
    <add name="ADService" connectionString="LDAP://ldapServer/" />
  </connectionStrings>
  <system.web>
    <membership
      defaultProvider="AspNetActiveDirectoryMembershipProvider">
      <providers>
        <add name="AspNetActiveDirectoryMembershipProvider"
          type="System.Web.Security.ActiveDirectoryMembershipProvider,
          System.Web, Version=1.0.3600, Culture=neutral,
          PublicKeyToken=b03f5f7f11d50a3a"
          connectionStringName="ADService"
          connectionUsername="UserWithAppropriateRights"
          connectionPassword="PasswordForUser"
          connectionProtection="Secure"
          enablePasswordReset="true"
          enableSearchMethods="true"
          requiresQuestionAndAnswer="true"
          applicationName="/"
          description="Default AD connection"
          requiresUniqueEmail="false"
          clientSearchTimeout="30"
          serverSearchTimeout="30"
          attributeMapPasswordQuestion="department"
          attributeMapPasswordAnswer="division"
          attributeMapFailedPasswordAnswerCount="singleIntAttribute"
         attributeMapFailedPasswordAnswerTime="singleLargeIntAttribute"
         attributeMapFailedPasswordAnswerLockoutTime="singleLargeIntAttribute"
          attributeMapEmail = "mail"
          attributeMapUsername = "userPrincipalName"
          maxInvalidPasswordAttempts = "5"
          passwordAttemptWindow = "10"
          passwordAnswerAttemptLockoutDuration = "30"
          minRequiredPasswordLength="7"
          minRequiredNonalphanumericCharacters="1"
          passwordStrengthRegularExpression="
          @\"(?=.{6,})(?=(.*\d){1,})(?=(.*\W){1,})" />
        />
      </providers>
    </membership>
  </system.web>
</configuration>

.NET Framework
Available since 2.0

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show:
© 2016 Microsoft