The .NET Developer's Guide to Directory Services Programming

by Kaplan, Joe; Dunn, Ryan

• ISBN13: 9780321350176
• ISBN10: 0321350170
• Edition: 1st
• Format: Paperback
• Copyright: 2006-05-08
• Publisher: Addison-Wesley Professional

Summary

The first book on programming to directory services using .NET, one of the least-understood aspects of .NET application development.

Author Biography

Joe Kaplan works in Accenture’s internal IT organization, building enterprise applications using the .NET Framework. He specializes in directory services programming, for which he has been recognized as a Microsoft MVP. An industry veteran of more than thirteen years, he also thrives on working with the development community and solving real-world problems.

Ryan Dunn of Avanade is a .NET developer and architect with experience in a wide range of industries and technologies. He has consulted on a number of projects to integrate clients’ applications with Active Directory and ADAM. Ryan is a Microsoft MVP for ASP.NET, though he currently focuses primarily on directory services. Ryan can be reached on the Web in the ASP.NET forums or through his blog at http://dunnry.com/blog.

Table of Contents

Listings	xv
Tables	xix
Foreword	xxi
Preface	xxiii
Acknowledgments	xxix
About the Authors	xxxi
PART I Fundamentals	1	(344)
Introduction to LDAP and Active Directory	3	(24)
A Brief History of Directory Services	3	(1)
Definition of LDAP	4	(1)
Definition of Active Directory	5	(2)
Domain	6	(1)
Domain Tree	6	(1)
Forest	6	(1)
Domain Controller	6	(1)
Global Catalog	7	(1)
Definition of ADAM	7	(4)
Comparing ADAM with Active Directory	8	(3)
LDAP Basics	11	(16)
LDAP Distinguished Names	11	(3)
Naming Contexts	14
Schema Basics	13	(7)
LDAP Protocol and API Basics	20	(5)
LDAP Controls	25	(2)
Introduction to .NET Directory Services Programming	27	(26)
.NET Directory Services Programming Landscape	27	(2)
Native Directory Services Programming Landscape	29	(3)
Native LDAP	29	(1)
The Net* APIs	29	(1)
The Ds* Active Directory APIs	30	(1)
Active Directory Service Interfaces (ADSI)	30	(2)
System.DirectoryServices Overview	32	(8)
Class Overview	33	(3)
ADSI Providers	36	(1)
Other Useful ADSI Interfaces	37	(3)
System.DirectoryServices.ActiveDirectory Overview	40	(3)
Class Overview	40	(3)
System.DirectoryServices.Protocols Overview	43	(6)
Overall Design	44	(1)
How Is it Organized?	45	(4)
Selecting the Right Technology	49	(4)
The Argument against Using activeds.dll Directly via COM Interop	50	(3)
Binding and CRUD Operations with DirectoryEntry	53	(56)
Property and Method Overview	54	(8)
Constructors	54	(1)
Properties	54	(4)
Methods	58	(4)
Binding to the Directory	62	(36)
Binding Syntax	62	(2)
ADSI Path Anatomy	64	(15)
Providing Credentials	79	(2)
Username Syntaxes in Active Directory and ADAM	81	(2)
Username Syntaxes in ADAM	83	(1)
AuthenticationTypes Explained	84	(8)
Binding to RootDSE	92	(3)
ADSI Connection Caching Explained	95	(3)
Directory CRUD Operations	98	(11)
Reading Attributes of Directory Objects	99	(1)
Modifying Attributes of Directory Objects	100	(1)
Creating Directory Objects	100	(2)
Deleting Directory Objects	102	(3)
Moving and Renaming Directory Objects	105	(4)
Searching with the DirectorySearcher	109	(40)
LDAP Searching Overview	109	(2)
LDAP Searches in ADSI	110	(1)
LDAP Searches in System.DirectoryServices	110	(1)
DirectorySearcher Overview	111	(4)
DirectorySearcher Properties	111	(2)
Methods	113	(1)
Related Classes	114	(1)
The Basics of Searching	115	(3)
Deciding Where to Search	115	(2)
Controlling Depth of Search with SearchScope	117	(1)
Building LDAP Filters	118	(18)
Basic Syntax	119	(1)
Filter Types	120	(3)
Reserved Characters in Values	123	(1)
Specifying Comparison Values in Search Filters	124	(9)
Bitwise Operations	133	(2)
Ambiguous Name Resolution	135	(1)
Controlling the Content of Search Results	136	(3)
Specifying Attribute Data to Be Returned	137	(1)
Limiting the Number of Results to Return with the SizeLimit Property	138	(1)
Executing the Query and Enumerating Results	139	(4)
Finding a Single Object with FindOne	139	(2)
Getting Multiple Results with FindAll	141	(1)
Enumerating the Results	142	(1)
Returning Many Results with Paged Searches	143	(3)
Enabling Paging	144	(1)
Choosing an Appropriate Page Size	145	(1)
Using the ServerPageTimeLimit	145	(1)
Caching Result Sets	146	(1)
Sorting Search Results	146	(3)
Advanced LDAP Searches	149	(44)
Administrative Limits Governing Active Directory and ADAM	150	(2)
Understanding Searching Timeouts	152	(2)
Precedence of Timeouts	152	(1)
Nonpaged Searches	153	(1)
Paged Searches	154	(1)
Optimizing Search Performance	154	(4)
Choosing the Right Search Root	155	(1)
Choosing the Right Scope	155	(1)
Creating Efficient Queries	156	(2)
Turn Caching Off When Possible	158	(1)
Searching the Global Catalog	158	(3)
Important Considerations for Using the Global Catalog	159	(1)
Binding Syntax for the Global Catalog	159	(2)
Chasing Referrals	161	(1)
Virtual List View Searches	162	(7)
Offset versus Target Searches	163	(1)
Using the DirectoryVirtualListView Class	164	(2)
Searching by Offset	166	(1)
Searching by String	167	(2)
Searching for Deleted Objects	169	(2)
Reasons to Search for Deleted Objects	171	(1)
Directory Synchronization Queries	171	(7)
Limitations on Search Root and Scope	172	(1)
Permissions	172	(1)
Filter	173	(1)
Attributes	173	(1)
DirSync Samples	174	(4)
Using Attribute Scope Query	178	(3)
Extended DN Queries	181	(2)
Reading Security Descriptors with Security Masks	183	(2)
Asynchronous Searches	185	(8)
Creating an Asynchronous Search	186	(7)
Reading and Writing LDAP Attributes	193	(54)
Basics of Reading Attribute Values	193	(2)
The Basic Design	194	(1)
Key Differences between the Value Collections	195	(1)
Collection Class Usage	195	(4)
Getting Single Values	195	(1)
Checking for Null Values	196	(2)
Checking for Multiple Values	198	(1)
Using the Value Property	198	(1)
Understanding the ADSI Property Cache	199	(1)
Flushing Changes Back to the Directory	200	(1)
LDAP Data Types in .NET	200	(6)
ADSI Schema Mapping Mechanism	206	(7)
Schema Caching	208	(5)
.NET Attribute Value Conversion	213	(1)
Data-Type Conversion with the DirectoryEntry Family	213	(1)
Data-Type Conversion with the DirectorySearcher Family	213	(1)
Why the Big Deal?	214	(1)
Standard Data Types	214	(1)
Binary Data Conversion	215	(1)
COM Interop Data Types	216	(13)
Approaches for COM Interop	217	(1)
LargeInteger Values	217	(5)
DN-With-Binary	222	(3)
Reading Security Descriptors	225	(4)
Syntactic versus Semantic Conversion	229	(1)
Dealing with Attributes with Many Values	230	(4)
How to Use Range Retrieval in SDS	231	(3)
Basics of Writing Attribute Values	234	(7)
Setting Initial Values	235	(1)
Clearing an Attribute	236	(1)
Replacing an Existing Attribute Value	237	(1)
Adding and Removing Values from Multivalued Attributes	237	(1)
Attribute Modification Summary	237	(4)
Writing COM Interop Types	241	(6)
Writing LargeInteger Values	241	(1)
Writing DN-With-Binary	242	(1)
Writing Security Descriptors	243	(4)
Active Directory and ADAM Schema	247	(26)
Schema Extension Best Practices	247	(4)
Read All of Microsoft's Documentation Carefully	248	(1)
Register OIDs for New Classes and Attributes	248	(1)
Manage OID Namespaces Thoughtfully	249	(1)
Practice on ADAM Instances	250	(1)
Set the schemalDGUID Attribute	250	(1)
Use Company-Specific Prefixes on IdapDisplayNames	251	(1)
Choosing an Object Class	251	(2)
Choosing Attribute Syntaxes	253	(3)
String Data	253	(1)
Date/Time Values	254	(1)
Numeric Data	255	(1)
Binary Data	255	(1)
Boolean Data	255	(1)
Object Identifiers	255	(1)
Foreign Keys	255	(1)
Other Data Types	256	(1)
Modeling One-to-Many and Many-to-Many Relationships	256	(5)
Link Value Pairs	257	(1)
DN Syntax Attribute Best Practices	258	(3)
Search Flags and Indexing	261	(3)
searchFlags	261	(2)
systemFlags	263	(1)
Techniques for Extending the Schema	264	(2)
Discovering Schema Information at Runtime	266	(7)
Using Constructed Attributes	269	(2)
Reading Schema Objects Directly	271	(2)
Security in Directory Services Programming	273	(52)
Binding and Delegation	274	(26)
Types of Binds	274	(2)
Performing a Secure Bind	276	(2)
Windows Security Contexts	278	(3)
Single Hops, Double Hops, and Delegation	281	(4)
Discovering Remote Security Information at Runtime	285	(2)
Guidance for Using SDS with ASP.NET	287	(9)
Serverless Binding and ASP.NET	296	(1)
Binding with ADAM	296	(2)
Binding and Other Directories	298	(1)
Securing the Simple Bind	298	(1)
Client Certificate Authentication	299	(1)
Binding Features Not Supported by SDS/ADSI	299	(1)
Directory Object Permissions in Active Directory and ADAM	300	(15)
.NET 2.0 Object Security Model	300	(2)
Reading Security Descriptors	302	(2)
Changing Security Descriptors	304	(6)
.NET 1.x Interop Model	310	(5)
Code Access Security	315	(10)
CAS Encounters of the First Kind	316	(1)
The Relevance to SDS	316	(1)
SDS in Partial Trust Scenarios in .NET 2.0	317	(2)
The Problem	319	(1)
Configuring DirectoryServicesPermission for Use with Partial Trust	320	(1)
Partial Trust in .NET 1.x	321	(4)
Introduction to the ActiveDirectory Namespace	325	(20)
Working with the DirectoryContext Class	326	(6)
General Usage	326	(2)
Examples of Using DirectoryContext	328	(4)
Locating Domain Controllers	332	(7)
How the Domain Controller Locator Works	332	(1)
Using the Locator Service	333	(1)
Enumerating All Domain Controllers	334	(1)
Advanced Locator Features	334	(2)
DsGetDcName under the Hood	336	(2)
Applications for Locating Domain Controllers	338	(1)
Understanding the Active Directory RPC APIs	339	(1)
Useful Shortcuts for Developers	339	(6)
Active Directory Shortcuts	341	(1)
ADAM Shortcuts	342	(3)
PART II Practical Applications	345	(88)
User Management	347	(50)
Finding Users	347	(4)
Finding Users in ADAM	349	(2)
Creating Users	351	(2)
Managing User Account Features	353	(23)
Managing Basic User Account Properties in Active Directory	353	(4)
Managing Basic User Account Properties in ADAM	357	(3)
Determining Domain-Wide Account Policies	360	(2)
Determining Password Expiration	362	(8)
Determining Last Logon	370	(3)
Determining Account Lockout	373	(3)
Managing Passwords for Active Directory Users	376	(10)
Password Management Complications	377	(1)
Understanding Password Policy and Security	377	(1)
Understanding the Underlying ADSI Methods	378	(3)
Error Handling with the Invoke Method in .NET	381	(1)
Recommendations for Successful Password Modification Operations	382	(1)
Why Can't We Do LDAP Password Modifications Directly in SDS?	383	(1)
SDS.P to the Rescue	383	(3)
Managing Passwords for ADAM Users	386	(3)
Programming Differences When Setting ADAM Passwords	387	(2)
Determining User Group Membership in Active Directory and ADAM	389	(8)
Retrieving the User's Token Groups	390	(1)
Technique #1: Using an LDAP Search	391	(2)
Technique #2: Using DsCrackNames	393	(1)
Technique #3: Using the Sidldentifier and IdentityReference Classes	394	(1)
Retrieving tokenGroups from ADAM	395	(2)
Group Management	397	(20)
Creating Groups in Active Directory and ADAM	397	(3)
Manipulating Group Membership	400	(3)
Expanding Group Membership	403	(6)
Using .NET Version 2.0	404	(3)
Using .NET Version 1.1	407	(2)
Primary Group Membership	409	(4)
Foreign Security Principals	413	(4)
Authentication	417	(16)
Authentication Using SDS	418	(6)
Active Directory Authentication	420	(2)
ADAM Authentication	422	(2)
Authentication Using SDS.P	424	(4)
Authentication Using SSPI	428	(3)
Discovering the Cause of Authentication Failures	431	(2)
PART III Appendixes	433	(22)
A. Three Approaches to COM Interop with ADSI	435	(8)
The Standard Method	435	(1)
Advantages	436	(1)
Disadvantages	436	(1)
The Reflection Method	437	(2)
Advantages	439	(1)
Disadvantages	439	(1)
Handcrafted COM Interop Declarations	439	(1)
Advantages	440	(1)
Disadvantages	440	(3)
B. LDAP Tools for Programmers	443	(6)
LDP	443	(2)
ADSI Edit	445	(1)
Active Directory Users and Computers	445	(1)
LDIFDE	446	(1)
ADFind/ADMod	447	(1)
BeaverTail LDAP Browser	447	(1)
Softerra LDAP Browser	448	(1)
C. Troubleshooting and Help	449	(6)
Error 0x8007203A: ``The server is not operational.''	449	(1)
Error 0x8007052E: ``Login Failure: unknown user name or bad password.''	450	(1)
Error 0x80072020: ``An operations error occurred.''	450	(1)
Error 0x80072030: ``There is no such object on the server.''	451	(1)
Error 0x8007202F: ``A constraint violation occurred.''	451	(1)
Error 0x80072035: ``The server is unwilling to process the request.''	452	(1)
Error 0x80070005: ``General access denied error.''	452	(1)
InvalidOperationException from DirectorySearcher	452	(1)
Getting Help	453	(2)
Index	455

Excerpts

We wrote this book with the vision that it would be the definitive guide for helping developers leverage directory services from Active Directory and Active Directory/Application Mode (ADAM) in their .NET applications. Even though version 1.0 of the .NET Framework shipped in 2001 with a namespace called System.DirectoryServices (SDS) for doing this kind of work, the resources available to developers using these technologies have lagged behind. This is the book that we fervently wished we had back when we were first developing software for Active Directory. It was an idea that took a little while to come to fruition: Perhaps a bit of our back story will help to frame our perspective. Ryan was working at a very large professional services firm that was selling off its consulting services capabilities. As part of the separation, a new IT infrastructure needed to be created. It fell to Ryan to figure out how to automate HR data feeds to provision Active Directory accounts and how to manage all of it with only a skeleton crew and a few custom apps. This was in the .NET version 1.0 beta 2 timeframe and .NET seemed promising. Separately, but in an eerily similar vein, Joe was working in the IT organization of a large professional services firm that was contemplating a massive email system migration from a popular groupware platform to Microsoft's Exchange 2000 Server. Exchange works on top of Active Directory, and Joe was asked to help out on the integration project between Active Directory and the groupware system's directory. Both projects required a heavy dose of directory services magic to tie the systems together and migrate from the competing platforms. The applications were not simple scripts, but complex systems and web applications requiring a more in-depth approach. But as we began to wade into the code, we noticed there were quite a few rough edges to be sorted out. Exactly how do we make the Lightweight Directory Access Protocol (LDAP) code work correctly in ASP.NET? What were all of those flags used for? How do we make these objects behave the way we expect? How do we extend the schema to accommodate our own custom business logic? Naturally, we went to the web-based message boards and newsgroups seeking advice, but found very little. Some people had some of the answers if we translated their logic from scripts or C++ programs, but more people were asking than answering. With hard work and sometimes-fortuitous chance, we eventually pieced it together, but it was far more difficult than it needed to be. Flash forward to 2006: The .NET Framework has matured significantly, with a milestone 2.0 release, and so has the .NET development community. Books and resources abound for just about every topic you could imagine. However, directory services programming still remains obscure and confusing. This lack of guidance is somewhat ironic given that the enterprise directory continues to gain prominence in the organization. It is no longer just the province of a team of administrators writing scripts. It has become a key source of data for many full-scale applications, with some even building complex identity life cycle management processes on top of it. We stuck around the message boards, and over the last several years, we worked actively in the online development community to help developers of all stripes solve their directory services development problems. We know from our work in the community that there tends to be a lot of confusion on how best to leverage what became of Active Directory Service Interfaces (ADSI) in the new managed model of System.DirectoryServices . We took the most common problems that developers wrestle with in this space and tried to address them in turn. By the time you finish reading this book, we hope that your directory services programming will be much more