ActiveDirectoryMembershipProvider Class

.NET Framework version 2.0

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

Visibility	Constructor	Parameters
public	ActiveDirectoryMembershipProvider	( )

Visibility	Name	Value Type	Accessibility
public	ApplicationName	String	[ Get , Set ]
public	CurrentConnectionProtection	ActiveDirectoryConnectionProtection	[ Get ]
public	EnablePasswordReset	Boolean	[ Get ]
public	EnablePasswordRetrieval	Boolean	[ Get ]
public	EnableSearchMethods	Boolean	[ Get ]
public	MaxInvalidPasswordAttempts	Int32	[ Get ]
public	MinRequiredNonAlphanumericCharacters	Int32	[ Get ]
public	MinRequiredPasswordLength	Int32	[ Get ]
public	PasswordAnswerAttemptLockoutDuration	Int32	[ Get ]
public	PasswordAttemptWindow	Int32	[ Get ]
public	PasswordFormat	MembershipPasswordFormat	[ Get ]
public	PasswordStrengthRegularExpression	String	[ Get ]
public	RequiresQuestionAndAnswer	Boolean	[ Get ]
public	RequiresUniqueEmail	Boolean	[ Get ]

Visibility	Name	Parameters	Return Type
public	ChangePassword	( String username , String oldPassword , String newPassword )	Boolean
public	ChangePasswordQuestionAndAnswer	( String username , String password , String newPasswordQuestion , String newPasswordAnswer )	Boolean
public	CreateUser	( String username , String password , String email , String passwordQuestion , String passwordAnswer , Boolean isApproved , Object providerUserKey , MembershipCreateStatus& status )	MembershipUser
public	DeleteUser	( String username , Boolean deleteAllRelatedData )	Boolean
public	FindUsersByEmail	( String emailToMatch , Int32 pageIndex , Int32 pageSize , Int32& totalRecords )	MembershipUserCollection
public	FindUsersByName	( String usernameToMatch , Int32 pageIndex , Int32 pageSize , Int32& totalRecords )	MembershipUserCollection
public	GeneratePassword	( )	String
public	GetAllUsers	( Int32 pageIndex , Int32 pageSize , Int32& totalRecords )	MembershipUserCollection
public	GetNumberOfUsersOnline	( )	Int32
public	GetPassword	( String username , String passwordAnswer )	String
public	GetUser	( Object providerUserKey , Boolean userIsOnline )	MembershipUser
public	GetUser	( String username , Boolean userIsOnline )	MembershipUser
public	GetUserNameByEmail	( String email )	String
public	Initialize	( String name , NameValueCollection config )	Void
public	ResetPassword	( String username , String passwordAnswer )	String
public	UnlockUser	( String username )	Boolean
public	UpdateUser	( MembershipUser user )	Void
public	ValidateUser	( String username , String password )	Boolean

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.

NOTE: Using an ADAM server requires specific configuration. See the section ADAM Configuration below for more information.

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 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.

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 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 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. Any method that sets a password will fail. Active Directory requires a secure connection when changing passwords. You must explicitly set the connectionUsername and connectionPassword attributes using the add Element for providers in the application configuration file; otherwise, the ActiveDirectoryMembershipProvider instance will throw a ProviderException exception.
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. For more information about the User class, and other schemas available to import into your ADAM server, see the MSDN article Adding User Classes.

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 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 the attribute settings available for an ActiveDirectoryMembershipProvider instance.

<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"
               attributeMapFailedPassswordAnswerLockoutTime = "singleLargeIntAttribute"
               maxInvalidPasswordAttemps = "5"
               passwordAttemptWindow = "10"
               passwordAnswerAttemptLockoutDuration = "30"
               minRequiredPasswordLength = "7"
               minRequiredNonalphanumericCharacters = "1"
               passwordStrengthRegularExpression = "
               @\"(?=.{6,})(?=(.*\d){1,})(?=(.*\W){1,})" />
            />
         </providers>
      </membership>
   </system.web>
</configuration>

ActiveDirectoryMembershipUser Class

Home Getting Started Web Forms Web Applications ADO.NET ASP/ADO Back to Basics

ActiveDirectoryMembershipProvider Class

ActiveDirectoryMembershipProvider Class Members

Constructors

Properties

Methods

Remarks

Active Directory connections

ADAM Configuration

Example

See Also