Skip to content

Commit ef893e0

Browse files
sam-munckesam-muncke
committed
Address comments on docs
1 parent 8dc10af commit ef893e0

1 file changed

Lines changed: 42 additions & 33 deletions

File tree

‎examples/ConnectedAccounts.md‎

Lines changed: 42 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -6,51 +6,52 @@ The Connect Accounts feature uses the Auth0 My Account API to allow users to lin
66
>DPoP sender token constraining is not yet supported in this SDK. My Account API can be configured to support it (default behaviour) but must not be configured to require it.
77
88

9-
When using Connected Accounts, Auth0 acquires tokens from upstream Identity Providers (like Google) and stores them in a secure [Token Vault](https://auth0.com/docs/secure/tokens/token-vault). These tokens can then be used to access third-party APIs (like Google Calendar) on behalf of the user.
9+
When using [Connected Accounts for Token Vault](https://auth0.com/docs/secure/tokens/token-vault/connected-accounts-for-token-vault), Auth0 acquires tokens from upstream Identity Providers (like Google) and stores them in a secure [Token Vault](https://auth0.com/docs/secure/tokens/token-vault). These tokens can then be used to access third-party APIs (like Google Calendar) on behalf of the user.
1010

1111
The tokens in the Token Vault are then accessible to [Applications](https://auth0.com/docs/get-started/applications) configured in Auth0. The application can issue requests to Auth0 to retrieve the tokens from the Token Vault and use them to access the third-party APIs.
1212

1313
This is particularly useful for applications that require access to different resources on behalf of a user, like AI Agents.
1414

15-
## Configure the SDK
15+
## Pre-requisites
16+
Connected Account functionality makes use of the Auth0 [My Account API] (https://auth0.com/docs/manage-users/my-account-api) and [Multiple Resource Refresh Tokens (MRRT)](https://auth0.com/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token). To use this functionality in this SDK you must first ensure that you first [activate My Account API](https://auth0.com/docs/manage-users/my-account-api#activate-the-my-account-api) on your Auth0 tenant and enable access for you client Application. You must also [configure MRRT](https://auth0.com/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token/configure-and-implement-multi-resource-refresh-token#configure-applications-for-mrrt) on your client application's refresh token policies to allow access to the My Account audience (`https://{yourDomain}/me/`) for the `create:me:connected_accounts` scope as well as any other APIs and scopes you intend to access in your application.
1617

17-
The Auth0 client Application must be configured to use refresh tokens and [MRRT (Multiple Resource Refresh Tokens)](https://auth0.com/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token) since we will use the refresh token grant to get Access Tokens for the My Account API in addition to the API we are calling.
18+
## Configure the SDK
1819

1920
```python
2021
server_client = ServerClient(
2122
domain="YOUR_AUTH0_DOMAIN",
2223
client_id="YOUR_CLIENT_ID",
2324
client_secret="YOUR_CLIENT_SECRET",
2425
secret="YOUR_SECRET",
25-
authorization_params={
26-
"redirect_uri":"YOUR_CALLBACK_URL",
27-
"audience": "YOUR_API_IDENTIFIER"
28-
}
26+
2927
)
3028
```
3129

3230
## Login to the application
3331

34-
Use the login methods to authenticate to the application and get a refresh and access token for the API.
32+
Use the login methods to authenticate to the application and get a refresh token in order to use MRRT to call the My Account API. If you are also intending to authorize access to any custom API, you may optionally specify an audience and any relevant scopes but you must at a minimum include the `offline_access` scope to ensure you obtain a refresh token.
3533

3634
```python
37-
# Login specifying any scopes for the Auth0 API
38-
35+
# Login to authenticate your aplication, optionally specifying any scopes for your Auth0 API
3936
authorization_url = await server_client.start_interactive_login(
4037
{
38+
"redirect_uri": "CALLBACK_URL",
4139
"authorization_params": {
42-
# must include offline_access to obtain a refresh token
43-
"scope": "openid profile email offline_access"
40+
# optional
41+
"audience": "https://custom-api.com",
42+
# must include at least offline_access to obtain a refresh token
43+
"scope": "offline_access openid profile email read:foo"
4444
}
4545
},
4646
store_options={"request": request, "response": response}
4747
)
48+
```
49+
Redirect user to the provided url, after authenticating with Auth0, the user will be returned to the provided `CALLBACK_URL` with additional `state` and `code` query parameters. In the handler for this callback, complete the interactive login passing the full callback url (including any query parameters).
4850

49-
# redirect user
50-
51+
```python
5152
# handle redirect
5253
result = await server_client.complete_interactive_login(
53-
callback_url,
54+
full_callback_url,
5455
store_options={"request": request, "response": response}
5556
)
5657
```
@@ -59,49 +60,57 @@ result = await server_client.complete_interactive_login(
5960

6061
Start the flow using the `start_connect_account` method to redirect the user to the third-party Identity Provider to connect their account.
6162

62-
The `authorization_params` is used to pass additional parameters required by the third-party IdP
63+
The `authorization_params` is used to pass additional parameters required by the third-party IdP.
64+
65+
The `scopes` parameter is used to override the scopes requested from the third-party IdP. By default, if no `scopes` parameter is provided, Auth0 will request any scopes configured in the connection settings through the Auth0 Management API/Dashboard.
66+
6367
The `app_state` parameter allows you to pass custom state (for example, a return URL) that is later available when the connect process completes.
6468

6569
```python
6670

6771
connect_url = await self.client.start_connect_account(
6872
ConnectAccountOptions(
69-
connection="CONNECTION", # e.g. google-oauth2
70-
redirect_uri="YOUR_CALLBACK_URL"
71-
app_state= {
73+
connection="google-oauth2",
74+
redirect_uri="CALLBACK_URL"
75+
app_state= {
7276
"returnUrl":"SOME_URL"
7377
}
74-
scopes= [
78+
scopes= [
7579
# scopes to passed to the third-party IdP
7680
"openid",
77-
"email",
78-
"profile"
79-
"offline_access"
81+
"https://www.googleapis.com/auth/calendar.freebusy",
82+
"https://www.googleapis.com/auth/calendar.readonly"
8083
]
8184
authorization_params= {
82-
# additional auth parameters to be sent to the third-party IdP e.g.
83-
"login_hint": "user123",
84-
"resource": "some_resource"
85+
# additional auth parameters to be sent to the third-party IdP
86+
"login_hint": "jdoe@example.org"
8587
}
86-
),
88+
),
8789
store_options={"request": request, "response": response}
8890
)
8991
```
9092

91-
Using the url returned, redirect the user to the third-party Identity Provider to complete any required authorization. Once authorized, the user will be redirected back to the provided `redirect_uri` with a `connect_code` and `state` parameter.
93+
Using the url returned, redirect the user to the third-party Identity Provider to complete any required authorization. Once authorized, the user will be redirected back to the provided `CALLBACK_URL` with a `connect_code` and `state` parameter. The `CALLBACK_URL` provided may be the same that is used for the interative login or it may be distinct. However if the same endpoint is used, the handler should be able distinguish between a login callback vs a connect accounts callback (typically via the presence of the `code` and `connect_code` parameter respectively).
9294

9395
## Complete the account connection
9496

95-
Call the `complete_connect_account` method using the full callback url returned from the third-party IdP to complete the connected account flow. This method extracts the connect_code from the URL, completes the connection, and returns the response data (including any `app_state` you passed originally).
97+
In the callback handler, call the `complete_connect_account` method using the full callback url returned from the third-party IdP to complete the connected account flow. This method extracts the connect_code from the URL, completes the connection, and returns the response data (including any `app_state` you passed originally).
9698

9799
```python
98100
complete_response = await self.client.complete_connect_account(
99-
url= callback_url,
100-
store_options=store_options
101+
url= connect_account_full_callback_url,
102+
store_options={"request": request, "response": response}
101103
)
102104
```
103105

104106
>[!NOTE]
105-
>The `callback_url` must include the necessary parameters (`state` and `connect_code`) that Auth0 sends upon successful authentication.
107+
>The `callback_url` must include the necessary parameters (`state` and `connect_code`) that Auth0 sends upon successful authorization.
108+
109+
You can now call the API with your access token and the API can use [Access Token Exchange with Token Vault](https://auth0.com/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault) to get tokens from the Token Vault to access third-party APIs on behalf of the user.
106110

107-
You can now call the API with your access token and the API can use [Access Token Exchange with Token Vault](https://auth0.com/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault) to get tokens from the Token Vault to access third-party APIs on behalf of the user.
111+
```python
112+
access_token_for_google = await server_client.get_access_token_for_connection(
113+
{ "connection": "google-oauth2" },
114+
store_options=store_options
115+
)
116+
```

0 commit comments

Comments
 (0)