0
# Directory Services
1

2
Complete Azure Active Directory management through Microsoft Graph API including users, groups, applications, devices, and organizational relationships. Provides comprehensive identity and access management capabilities for enterprise environments.
3

4
## Capabilities
5

6
### User Management
7

8
Complete user lifecycle management including creation, updates, deletion, and property management with support for user profiles, authentication methods, and organizational relationships.
9

10
```python { .api }
11
class User:
12
    """Azure AD user entity with comprehensive profile and management capabilities."""
13
    
14
    # Core Properties
15
    id: str
16
    display_name: str
17
    mail: str
18
    user_principal_name: str
19
    given_name: str
20
    surname: str
21
    mobile_phone: str
22
    office_location: str
23
    preferred_language: str
24
    job_title: str
25
    department: str
26
    company_name: str
27
    account_enabled: bool
28
    creation_type: str
29
    
30
    def get(self) -> 'User':
31
        """
32
        Retrieve user information from Azure AD.
33
        
34
        Returns:
35
            User: Updated user object with current data
36
        """
37
    
38
    def update(self) -> 'User':
39
        """
40
        Update user properties in Azure AD.
41
        
42
        Returns:
43
            User: Updated user object
44
        """
45
    
46
    def delete(self) -> None:
47
        """Delete user from Azure AD."""
48
    
49
    def change_password(self, current_password: str, new_password: str) -> None:
50
        """
51
        Change user's password.
52
        
53
        Args:
54
            current_password (str): Current password
55
            new_password (str): New password
56
        """
57
    
58
    def revoke_sign_in_sessions(self) -> None:
59
        """Revoke all user sign-in sessions."""
60
    
61
    # Navigation Properties
62
    @property
63
    def manager(self) -> 'User':
64
        """User's manager."""
65
    
66
    @property
67
    def direct_reports(self) -> 'UserCollection':
68
        """Users who report to this user."""
69
    
70
    @property
71
    def member_of(self) -> 'GroupCollection':
72
        """Groups the user is a member of."""
73
    
74
    @property
75
    def owned_devices(self) -> 'DeviceCollection':
76
        """Devices owned by the user."""
77
    
78
    @property
79
    def registered_devices(self) -> 'DeviceCollection':
80
        """Devices registered by the user."""
81

82
class UserCollection:
83
    """Collection of Azure AD users with query and management capabilities."""
84
    
85
    def get(self) -> 'UserCollection':
86
        """Retrieve collection of users."""
87
    
88
    def filter(self, expression: str) -> 'UserCollection':
89
        """
90
        Filter users by OData expression.
91
        
92
        Args:
93
            expression (str): OData filter expression
94
            
95
        Returns:
96
            UserCollection: Filtered collection
97
        """
98
    
99
    def select(self, properties: List[str]) -> 'UserCollection':
100
        """
101
        Select specific properties to retrieve.
102
        
103
        Args:
104
            properties (List[str]): Property names to select
105
            
106
        Returns:
107
            UserCollection: Collection with selected properties
108
        """
109
    
110
    def top(self, count: int) -> 'UserCollection':
111
        """
112
        Limit results to top N users.
113
        
114
        Args:
115
            count (int): Maximum number of users to return
116
            
117
        Returns:
118
            UserCollection: Limited collection
119
        """
120
    
121
    def get_by_id(self, user_id: str) -> User:
122
        """
123
        Get user by ID.
124
        
125
        Args:
126
            user_id (str): User's object ID
127
            
128
        Returns:
129
            User: User object
130
        """
131
    
132
    def add(self, user_creation_info: Dict[str, Any]) -> User:
133
        """
134
        Create new user.
135
        
136
        Args:
137
            user_creation_info (Dict): User properties for creation
138
            
139
        Returns:
140
            User: Created user object
141
        """
142
```
143

144
### Group Management
145

146
Comprehensive group management including security groups, distribution lists, Microsoft 365 groups, and group membership operations with support for dynamic membership rules.
147

148
```python { .api }
149
class Group:
150
    """Azure AD group entity with membership and settings management."""
151
    
152
    # Core Properties
153
    id: str
154
    display_name: str
155
    description: str
156
    mail: str
157
    mail_nickname: str
158
    group_types: List[str]
159
    security_enabled: bool
160
    mail_enabled: bool
161
    visibility: str
162
    
163
    def get(self) -> 'Group':
164
        """
165
        Retrieve group information from Azure AD.
166
        
167
        Returns:
168
            Group: Updated group object
169
        """
170
    
171
    def update(self) -> 'Group':
172
        """
173
        Update group properties.
174
        
175
        Returns:
176
            Group: Updated group object
177
        """
178
    
179
    def delete(self) -> None:
180
        """Delete group from Azure AD."""
181
    
182
    def add_member(self, user_id: str) -> None:
183
        """
184
        Add user to group.
185
        
186
        Args:
187
            user_id (str): User's object ID
188
        """
189
    
190
    def remove_member(self, user_id: str) -> None:
191
        """
192
        Remove user from group.
193
        
194
        Args:
195
            user_id (str): User's object ID
196
        """
197
    
198
    def add_owner(self, user_id: str) -> None:
199
        """
200
        Add group owner.
201
        
202
        Args:
203
            user_id (str): User's object ID
204
        """
205
    
206
    def remove_owner(self, user_id: str) -> None:
207
        """
208
        Remove group owner.
209
        
210
        Args:
211
            user_id (str): User's object ID
212
        """
213
    
214
    # Navigation Properties
215
    @property
216
    def members(self) -> 'DirectoryObjectCollection':
217
        """Group members (users, groups, service principals)."""
218
    
219
    @property
220
    def owners(self) -> 'DirectoryObjectCollection':
221
        """Group owners."""
222
    
223
    @property
224
    def team(self) -> 'Team':
225
        """Associated Microsoft Teams team (for Microsoft 365 groups)."""
226

227
class GroupCollection:
228
    """Collection of Azure AD groups with query and management capabilities."""
229
    
230
    def get(self) -> 'GroupCollection':
231
        """Retrieve collection of groups."""
232
    
233
    def filter(self, expression: str) -> 'GroupCollection':
234
        """
235
        Filter groups by OData expression.
236
        
237
        Args:
238
            expression (str): OData filter expression
239
            
240
        Returns:
241
            GroupCollection: Filtered collection
242
        """
243
    
244
    def get_by_id(self, group_id: str) -> Group:
245
        """
246
        Get group by ID.
247
        
248
        Args:
249
            group_id (str): Group's object ID
250
            
251
        Returns:
252
            Group: Group object
253
        """
254
    
255
    def add(self, group_creation_info: Dict[str, Any]) -> Group:
256
        """
257
        Create new group.
258
        
259
        Args:
260
            group_creation_info (Dict): Group properties for creation
261
            
262
        Returns:
263
            Group: Created group object
264
        """
265
```
266

267
### Application Management
268

269
Azure AD application registration and service principal management with support for API permissions, secrets, certificates, and application settings.
270

271
```python { .api }
272
class Application:
273
    """Azure AD application registration with configuration and credential management."""
274
    
275
    # Core Properties
276
    id: str
277
    app_id: str
278
    display_name: str
279
    description: str
280
    sign_in_audience: str
281
    publisher_domain: str
282
    homepage: str
283
    identifier_uris: List[str]
284
    reply_urls: List[str]
285
    required_resource_access: List[Dict[str, Any]]
286
    
287
    def get(self) -> 'Application':
288
        """
289
        Retrieve application information.
290
        
291
        Returns:
292
            Application: Updated application object
293
        """
294
    
295
    def update(self) -> 'Application':
296
        """
297
        Update application properties.
298
        
299
        Returns:
300
            Application: Updated application object
301
        """
302
    
303
    def delete(self) -> None:
304
        """Delete application registration."""
305
    
306
    def add_password(self, display_name: str, end_date_time: str = None) -> Dict[str, str]:
307
        """
308
        Add client secret to application.
309
        
310
        Args:
311
            display_name (str): Secret display name
312
            end_date_time (str, optional): Expiration date (ISO 8601)
313
            
314
        Returns:
315
            Dict containing secretText and keyId
316
        """
317
    
318
    def remove_password(self, key_id: str) -> None:
319
        """
320
        Remove client secret from application.
321
        
322
        Args:
323
            key_id (str): Secret key ID
324
        """
325
    
326
    def add_key(self, key_credential: Dict[str, Any]) -> None:
327
        """
328
        Add certificate key to application.
329
        
330
        Args:
331
            key_credential (Dict): Certificate key credential
332
        """
333
    
334
    def remove_key(self, key_id: str, proof: str) -> None:
335
        """
336
        Remove certificate key from application.
337
        
338
        Args:
339
            key_id (str): Key ID
340
            proof (str): Proof of possession token
341
        """
342

343
class ApplicationCollection:
344
    """Collection of Azure AD applications with query and management capabilities."""
345
    
346
    def get(self) -> 'ApplicationCollection':
347
        """Retrieve collection of applications."""
348
    
349
    def filter(self, expression: str) -> 'ApplicationCollection':
350
        """
351
        Filter applications by OData expression.
352
        
353
        Args:
354
            expression (str): OData filter expression
355
            
356
        Returns:
357
            ApplicationCollection: Filtered collection
358
        """
359
    
360
    def get_by_id(self, app_id: str) -> Application:
361
        """
362
        Get application by ID.
363
        
364
        Args:
365
            app_id (str): Application object ID
366
            
367
        Returns:
368
            Application: Application object
369
        """
370
    
371
    def add(self, app_creation_info: Dict[str, Any]) -> Application:
372
        """
373
        Create new application registration.
374
        
375
        Args:
376
            app_creation_info (Dict): Application properties for creation
377
            
378
        Returns:
379
            Application: Created application object
380
        """
381

382
class ServicePrincipal:
383
    """Service principal entity representing application instance in tenant."""
384
    
385
    # Core Properties
386
    id: str
387
    app_id: str
388
    display_name: str
389
    service_principal_type: str
390
    account_enabled: bool
391
    app_role_assignment_required: bool
392
    publisher_name: str
393
    
394
    def get(self) -> 'ServicePrincipal':
395
        """
396
        Retrieve service principal information.
397
        
398
        Returns:
399
            ServicePrincipal: Updated service principal object
400
        """
401
    
402
    def update(self) -> 'ServicePrincipal':
403
        """
404
        Update service principal properties.
405
        
406
        Returns:
407
            ServicePrincipal: Updated service principal object
408
        """
409
    
410
    def delete(self) -> None:
411
        """Delete service principal."""
412
    
413
    # Navigation Properties
414
    @property
415
    def app_role_assignments(self) -> 'AppRoleAssignmentCollection':
416
        """App role assignments for this service principal."""
417
    
418
    @property
419
    def oauth2_permission_grants(self) -> 'OAuth2PermissionGrantCollection':
420
        """OAuth2 permission grants for this service principal."""
421
```
422

423
### Device Management
424

425
Azure AD device registration and management with support for device compliance, configuration, and lifecycle operations.
426

427
```python { .api }
428
class Device:
429
    """Azure AD registered device with management and compliance capabilities."""
430
    
431
    # Core Properties
432
    id: str
433
    device_id: str
434
    display_name: str
435
    operating_system: str
436
    operating_system_version: str
437
    device_version: int
438
    device_metadata: str
439
    device_category: str
440
    device_ownership: str
441
    enrollment_type: str
442
    is_compliant: bool
443
    is_managed: bool
444
    on_premises_last_sync_date_time: str
445
    trust_type: str
446
    management_type: str
447
    
448
    def get(self) -> 'Device':
449
        """
450
        Retrieve device information.
451
        
452
        Returns:
453
            Device: Updated device object
454
        """
455
    
456
    def update(self) -> 'Device':
457
        """
458
        Update device properties.
459
        
460
        Returns:
461
            Device: Updated device object
462
        """
463
    
464
    def delete(self) -> None:
465
        """Delete device registration."""
466
    
467
    # Navigation Properties
468
    @property
469
    def registered_owners(self) -> 'DirectoryObjectCollection':
470
        """Users who are registered owners of the device."""
471
    
472
    @property
473
    def registered_users(self) -> 'DirectoryObjectCollection':
474
        """Users who are registered users of the device."""
475

476
class DeviceCollection:
477
    """Collection of Azure AD devices with query and management capabilities."""
478
    
479
    def get(self) -> 'DeviceCollection':
480
        """Retrieve collection of devices."""
481
    
482
    def filter(self, expression: str) -> 'DeviceCollection':
483
        """
484
        Filter devices by OData expression.
485
        
486
        Args:
487
            expression (str): OData filter expression
488
            
489
        Returns:
490
            DeviceCollection: Filtered collection
491
        """
492
    
493
    def get_by_id(self, device_id: str) -> Device:
494
        """
495
        Get device by ID.
496
        
497
        Args:
498
            device_id (str): Device object ID
499
            
500
        Returns:
501
            Device: Device object
502
        """
503
```
504

505
### Directory Objects
506

507
Base directory object functionality providing common operations for all Azure AD objects including users, groups, applications, and service principals.
508

509
```python { .api }
510
class DirectoryObject:
511
    """Base class for all Azure AD directory objects."""
512
    
513
    # Core Properties
514
    id: str
515
    deleted_date_time: str
516
    
517
    def get(self) -> 'DirectoryObject':
518
        """
519
        Retrieve directory object information.
520
        
521
        Returns:
522
            DirectoryObject: Updated object
523
        """
524
    
525
    def delete(self) -> None:
526
        """Delete directory object."""
527
    
528
    def restore(self) -> 'DirectoryObject':
529
        """
530
        Restore deleted directory object.
531
        
532
        Returns:
533
            DirectoryObject: Restored object
534
        """
535
    
536
    def check_member_groups(self, group_ids: List[str]) -> List[str]:
537
        """
538
        Check if object is member of specified groups.
539
        
540
        Args:
541
            group_ids (List[str]): Group object IDs to check
542
            
543
        Returns:
544
            List[str]: Group IDs where object is a member
545
        """
546
    
547
    def get_member_groups(self, security_enabled_only: bool = False) -> List[str]:
548
        """
549
        Get groups the object is a member of.
550
        
551
        Args:
552
            security_enabled_only (bool): Return only security-enabled groups
553
            
554
        Returns:
555
            List[str]: Group object IDs
556
        """
557
    
558
    def get_member_objects(self, security_enabled_only: bool = False) -> List[str]:
559
        """
560
        Get all groups and directory roles the object is a member of.
561
        
562
        Args:
563
            security_enabled_only (bool): Return only security-enabled objects
564
            
565
        Returns:
566
            List[str]: Object IDs of groups and roles
567
        """
568

569
class DirectoryObjectCollection:
570
    """Collection of directory objects with query capabilities."""
571
    
572
    def get(self) -> 'DirectoryObjectCollection':
573
        """Retrieve collection of directory objects."""
574
    
575
    def filter(self, expression: str) -> 'DirectoryObjectCollection':
576
        """
577
        Filter objects by OData expression.
578
        
579
        Args:
580
            expression (str): OData filter expression
581
            
582
        Returns:
583
            DirectoryObjectCollection: Filtered collection
584
        """
585
    
586
    def get_by_ids(self, ids: List[str], types: List[str] = None) -> 'DirectoryObjectCollection':
587
        """
588
        Get directory objects by their IDs.
589
        
590
        Args:
591
            ids (List[str]): Object IDs to retrieve
592
            types (List[str], optional): Object types to filter by
593
            
594
        Returns:
595
            DirectoryObjectCollection: Retrieved objects
596
        """
597
```
598

599
## Usage Examples
600

601
### User Operations
602

603
```python
604
from office365.graph_client import GraphClient
605

606
client = GraphClient.with_client_secret(client_id, client_secret, tenant)
607

608
# Get all users
609
users = client.users.get().execute_query()
610
for user in users:
611
    print(f"{user.display_name} ({user.user_principal_name})")
612

613
# Get specific user
614
user = client.users.get_by_id("user-object-id").get().execute_query()
615
print(f"User: {user.display_name}, Email: {user.mail}")
616

617
# Filter users by department
618
finance_users = client.users.filter("department eq 'Finance'").get().execute_query()
619

620
# Create new user
621
new_user_info = {
622
    "accountEnabled": True,
623
    "displayName": "John Doe",
624
    "mailNickname": "johndoe",
625
    "userPrincipalName": "johndoe@domain.com",
626
    "passwordProfile": {
627
        "forceChangePasswordNextSignIn": True,
628
        "password": "TempPassword123!"
629
    }
630
}
631
new_user = client.users.add(new_user_info).execute_query()
632

633
# Update user properties
634
user.job_title = "Senior Developer"
635
user.department = "Engineering"
636
user.update().execute_query()
637
```
638

639
### Group Operations
640

641
```python
642
# Get all groups
643
groups = client.groups.get().execute_query()
644

645
# Get specific group
646
group = client.groups.get_by_id("group-object-id").get().execute_query()
647

648
# Create Microsoft 365 group
649
new_group_info = {
650
    "displayName": "Marketing Team",
651
    "description": "Marketing team collaboration group",
652
    "mailNickname": "marketing-team",
653
    "mailEnabled": True,
654
    "securityEnabled": False,
655
    "groupTypes": ["Unified"]
656
}
657
new_group = client.groups.add(new_group_info).execute_query()
658

659
# Add members to group
660
group.add_member("user-object-id")
661
client.execute_query()
662

663
# Get group members
664
members = group.members.get().execute_query()
665
for member in members:
666
    print(f"Member: {member.display_name}")
667
```
668

669
### Application Management
670

671
```python
672
# Get all applications
673
apps = client.applications.get().execute_query()
674

675
# Create new application
676
app_info = {
677
    "displayName": "My API Application",
678
    "signInAudience": "AzureADMyOrg",
679
    "requiredResourceAccess": [
680
        {
681
            "resourceAppId": "00000003-0000-0000-c000-000000000000",  # Microsoft Graph
682
            "resourceAccess": [
683
                {
684
                    "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",  # User.Read
685
                    "type": "Scope"
686
                }
687
            ]
688
        }
689
    ]
690
}
691
new_app = client.applications.add(app_info).execute_query()
692

693
# Add client secret
694
secret = new_app.add_password("My Client Secret").execute_query()
695
print(f"Client Secret: {secret.value.secret_text}")
696
```
697

698
## Types
699

700
```python { .api }
701
from typing import List, Dict, Any, Optional
702

703
class PasswordProfile:
704
    """User password profile configuration."""
705
    
706
    force_change_password_next_sign_in: bool
707
    force_change_password_next_sign_in_with_mfa: bool  
708
    password: str
709

710
class ResourceAccess:
711
    """API permission resource access definition."""
712
    
713
    id: str  # Permission ID
714
    type: str  # "Role" or "Scope"
715

716
class RequiredResourceAccess:
717
    """Required API permissions for application."""
718
    
719
    resource_app_id: str  # Resource application ID (e.g., Microsoft Graph)
720
    resource_access: List[ResourceAccess]  # List of required permissions
721

722
class KeyCredential:
723
    """Certificate key credential for application."""
724
    
725
    key_id: str
726
    type: str  # "AsymmetricX509Cert"
727
    usage: str  # "Verify"
728
    key: bytes  # Certificate public key
729
    display_name: str
730
    start_date_time: str
731
    end_date_time: str
732

733
class PasswordCredential:
734
    """Password credential (client secret) for application."""
735
    
736
    key_id: str
737
    display_name: str
738
    secret_text: str
739
    start_date_time: str
740
    end_date_time: str
741

742
class AppRoleAssignment:
743
    """Application role assignment to user, group, or service principal."""
744
    
745
    id: str
746
    app_role_id: str
747
    principal_id: str
748
    principal_type: str
749
    resource_id: str
750
```