Skip to content

Commit afeaa6d

Browse files
authored
Merge pull request #265 from microsoftgraph/isvargasmsft-updatesToReadMe
Update Getting started instructions
2 parents 5c440e3 + 4e0b617 commit afeaa6d

1 file changed

Lines changed: 48 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 48 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,21 +19,62 @@ pip install msgraph-sdk
1919

2020
Register your application by following the steps at [Register your app with the Microsoft Identity Platform](https://docs.microsoft.com/graph/auth-register-app-v2).
2121

22-
### 2.2 Initialize a GraphServiceClient object
22+
### 2.2 Select and create an authentication provider
2323

24-
You must create **GraphServiceClient** object to make requests against the service. To create a new instance of this class, you need to provide credentials and scopes, which can authenticate requests to Microsoft Graph.
24+
To start writing code and making requests to the Microsoft Graph service, you need to set up an authentication provider. This object will authenticate your requests to Microsoft Graph. For authentication, the Microsoft Graph Python SDK supports both sync and async credential classes from Azure Identity. Which library to choose depends on the type of application you are building.
2525

2626
> **Note**: For authentication we support both `sync` and `async` credential classes from `azure.identity`. Please see the azure identity [docs](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity?view=azure-python) for more information.
2727
28+
The easiest way to filter this decision is by looking at the permissions set you'd use. Microsoft Graph supports 2 different types of permissions: delegated and application permissions:
29+
- Application permissions are used when you don’t need a user to login to your app, but the app will perform tasks on its own and run in the background.
30+
- Delegated permissions, also called scopes, are used when your app requires a user to login and interact with data related to this user in a session.
31+
32+
The following table lists common libraries by permissions set.
33+
| MSAL library | Permissions set | Common use case |
34+
|---|---|---|
35+
| [ClientSecretCredential](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.aio.clientsecretcredential?view=azure-python&preserve-view=true) | Application permissions | Daemon apps or applications running in the background without a signed-in user. |
36+
| [DeviceCodeCredential](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.devicecodecredential?view=azure-python) | Delegated permissions | Enviroments where authentication is triggered in one machine and completed in another e.g in a cloud server. |
37+
| [InteractiveBrowserCredentials](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.interactivebrowsercredential?view=azure-python) | Delegated permissions | Environments where a browser is available and the user wants to key in their username/password. |
38+
| [AuthorizationCodeCredentials](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.authorizationcodecredential?view=azure-python) | Delegated permissions | Usually for custom customer applications where the frontend calls the backend and waits for the authorization code at a particular url. |
39+
40+
You can also use [EnvironmentCredential](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.environmentcredential?view=azure-python), [DefaultAzureCredential](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python), [OnBehalfOfCredential](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.onbehalfofcredential?view=azure-python), or any other [Azure Identity library](https://learn.microsoft.com/en-us/python/api/overview/azure/identity-readme?view=azure-python#credential-classes).
41+
42+
Once you've picked an authentication library, we can initiate the authentication provider in your app. The following example uses ClientSecretCredential with application permissions.
43+
```python
44+
import asyncio
45+
46+
from azure.identity.aio import ClientSecretCredential
47+
48+
credential = ClientSecretCredential("tenantID",
49+
"clientID",
50+
"clientSecret")
51+
scopes = ['https://graph.microsoft.com/.default']
52+
```
53+
54+
The following example uses DeviceCodeCredentials with delegated permissions.
55+
```python
56+
import asyncio
57+
58+
from azure.identity import DeviceCodeCredential
59+
60+
credential = DeviceCodeCredential("client_id",
61+
"tenant_id")
62+
graph_scopes = ['User.Read', 'Calendars.ReadWrite.Shared']
63+
```
64+
65+
### 2.3 Initialize a GraphServiceClient object
66+
67+
You must create **GraphServiceClient** object to make requests against the service. To create a new instance of this class, you need to provide credentials and scopes, which can authenticate requests to Microsoft Graph.
68+
2869
```py
2970
# Example using async credentials and application access.
3071
from azure.identity.aio import ClientSecretCredential
3172
from msgraph import GraphServiceClient
3273

3374
credential = ClientSecretCredential(
34-
tenant_id='TENANT_ID',
35-
client_id='CLIENT_ID',
36-
client_secret='CLIENT_SECRET',
75+
'TENANT_ID',
76+
'CLIENT_ID',
77+
'CLIENT_SECRET',
3778
)
3879
scopes = ['https://graph.microsoft.com/.default']
3980
client = GraphServiceClient(credentials=credential, scopes=scopes)
@@ -47,8 +88,8 @@ from azure.identity import DeviceCodeCredential
4788
from msgraph import GraphServiceClient
4889

4990
credential=DeviceCodeCredential(
50-
client_id='CLIENT_ID',
51-
tenant_id='TENANT_ID',
91+
'CLIENT_ID',
92+
'TENANT_ID',
5293
)
5394
scopes = ['User.Read', 'Mail.Read']
5495
client = GraphServiceClient(credentials=credential, scopes=scopes)

0 commit comments

Comments
 (0)