Skip to content

Commit 1e44613

Browse files
rmad17rmad17
committed
Added migration guide for v5 to v6
1 parent 34e21b0 commit 1e44613

1 file changed

Lines changed: 221 additions & 0 deletions

File tree

‎UPGRADING.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# v6 Migration Guide
2+
3+
A guide to migrating the Auth0 Python SDK from v5 to v6.
4+
5+
- [Overall changes](#overall-changes)
6+
- [Breaking changes](#breaking-changes)
7+
- [Federated connections tokensets removed](#federated-connections-tokensets-removed)
8+
- [`federated_connections_access_tokens` field removed](#federated_connections_access_tokens-field-removed)
9+
- [`read:federated_connections_tokens` / `delete:federated_connections_tokens` scopes removed](#readfederated_connections_tokens--deletefederated_connections_tokens-scopes-removed)
10+
- [`ClientSessionTransferDelegationDeviceBindingEnum` narrowed](#clientsessiontransferdelegationdevicebindingenum-narrowed)
11+
- [`ConnectionAttributeIdentifier` split into three types](#connectionattributeidentifier-split-into-three-types)
12+
- [`PhoneProviderProtectionBackoffStrategyEnum` value renamed](#phoneproviderprotectionbackoffstrategyenum-value-renamed)
13+
- [`ListRolesOffsetPaginatedResponseContent` pagination fields now required](#listrolesoffsetpaginatedresponsecontent-pagination-fields-now-required)
14+
- [New features](#new-features)
15+
- [Network ACL: `auth0_managed` field](#network-acl-auth0_managed-field)
16+
- [Organizations: role members endpoint](#organizations-role-members-endpoint)
17+
- [Organizations: third-party client access](#organizations-third-party-client-access)
18+
- [Other additions](#other-additions)
19+
20+
## Overall changes
21+
22+
v6 removes one deprecated Management API surface (federated connections
23+
tokensets) and tightens a handful of generated types to match the current
24+
Auth0 Management API contract. Most applications will only be affected if
25+
they use the specific types or endpoints listed below.
26+
27+
The Authentication API is not affected by this release.
28+
29+
## Breaking changes
30+
31+
### Federated connections tokensets removed
32+
33+
The `users.federated_connections_tokensets` sub-client and its `list`/`delete`
34+
methods have been removed, along with the `FederatedConnectionTokenSet` and
35+
`ConnectionFederatedConnectionsAccessTokens` types. This endpoint is no longer
36+
part of the Auth0 Management API.
37+
38+
```python
39+
# v5
40+
client.users.federated_connections_tokensets.list(id="user_id")
41+
client.users.federated_connections_tokensets.delete(id="user_id", tokenset_id="tokenset_id")
42+
```
43+
44+
```python
45+
# v6
46+
# No replacement — the endpoint has been removed from the Management API.
47+
```
48+
49+
If you depend on this functionality, do not upgrade until you have confirmed
50+
an alternative with Auth0 support.
51+
52+
### `federated_connections_access_tokens` field removed
53+
54+
The optional `federated_connections_access_tokens` field has been removed
55+
from:
56+
57+
- `ConnectionOptionsAzureAd`
58+
- `ConnectionOptionsCommonOidc`
59+
- `ConnectionOptionsGoogleApps`
60+
- `ConnectionPropertiesOptions`
61+
- `UpdateConnectionOptions`
62+
63+
Any code reading or setting this field on the above types will need to
64+
remove that usage; passing it will simply be dropped as an unrecognized
65+
field.
66+
67+
### `read:federated_connections_tokens` / `delete:federated_connections_tokens` scopes removed
68+
69+
These two values are no longer valid members of `OauthScope`. Remove any
70+
references to them when requesting or checking scopes.
71+
72+
### `ClientSessionTransferDelegationDeviceBindingEnum` narrowed
73+
74+
The `"asn"` literal value has been removed. The enum now only accepts `"ip"`:
75+
76+
```python
77+
# v5
78+
ClientSessionTransferDelegationDeviceBindingEnum = typing.Union[typing.Literal["ip", "asn"], typing.Any]
79+
```
80+
81+
```python
82+
# v6
83+
ClientSessionTransferDelegationDeviceBindingEnum = typing.Union[typing.Literal["ip"], typing.Any]
84+
```
85+
86+
If you were setting this value to `"asn"`, update it to `"ip"` — this matches
87+
the current Management API's accepted values.
88+
89+
### `ConnectionAttributeIdentifier` split into three types
90+
91+
`ConnectionAttributeIdentifier` has been removed with no compatibility alias.
92+
It is replaced by three narrower types, one per attribute:
93+
94+
| Attribute field | v5 type | v6 type | Shape |
95+
| --- | --- | --- | --- |
96+
| `EmailAttribute.identifier` | `ConnectionAttributeIdentifier` | `EmailAttributeIdentifier` | `{active?, default_method?: DefaultMethodEmailIdentifierEnum}` |
97+
| `PhoneAttribute.identifier` | `ConnectionAttributeIdentifier` | `PhoneAttributeIdentifier` | `{active?, default_method?: DefaultMethodPhoneNumberIdentifierEnum}` |
98+
| `UsernameAttribute.identifier` | `ConnectionAttributeIdentifier` | `UsernameAttributeIdentifier` | `{active?}` (no `default_method`) |
99+
100+
```python
101+
# v5
102+
from auth0.management.types import ConnectionAttributeIdentifier
103+
104+
identifier = ConnectionAttributeIdentifier(active=True, default_method="email")
105+
```
106+
107+
```python
108+
# v6
109+
from auth0.management.types import EmailAttributeIdentifier
110+
111+
identifier = EmailAttributeIdentifier(active=True, default_method="email")
112+
```
113+
114+
`EmailAttributeIdentifier` has the same shape as the old
115+
`ConnectionAttributeIdentifier` and is a drop-in replacement for code that
116+
was only ever used with `EmailAttribute`. Code using
117+
`ConnectionAttributeIdentifier` with `PhoneAttribute` or `UsernameAttribute`
118+
must switch to `PhoneAttributeIdentifier` or `UsernameAttributeIdentifier`
119+
respectively; `UsernameAttributeIdentifier` does not support
120+
`default_method`.
121+
122+
### `PhoneProviderProtectionBackoffStrategyEnum` value renamed
123+
124+
The `"none"` literal has been replaced with `"default"`:
125+
126+
```python
127+
# v5
128+
PhoneProviderProtectionBackoffStrategyEnum = typing.Union[typing.Literal["exponential", "none"], typing.Any]
129+
```
130+
131+
```python
132+
# v6
133+
PhoneProviderProtectionBackoffStrategyEnum = typing.Union[typing.Literal["exponential", "default"], typing.Any]
134+
```
135+
136+
Replace any use of `"none"` with `"default"`.
137+
138+
### `ListRolesOffsetPaginatedResponseContent` pagination fields now required
139+
140+
`start`, `limit`, and `total` are no longer optional:
141+
142+
```python
143+
# v5
144+
start: typing.Optional[float] = None
145+
limit: typing.Optional[float] = None
146+
total: typing.Optional[float] = None
147+
```
148+
149+
```python
150+
# v6
151+
start: float
152+
limit: float
153+
total: float
154+
```
155+
156+
Deserializing a role-list response that is missing any of these fields now
157+
raises `pydantic.ValidationError` instead of silently defaulting to `None`.
158+
This matches the Management API, which always returns these fields for this
159+
endpoint.
160+
161+
## New features
162+
163+
### Network ACL: `auth0_managed` field
164+
165+
`NetworkAclMatch` gains an optional `auth0_managed: Optional[List[str]]`
166+
field (serialized as `auth0_managed`), available on both the `match` and
167+
`not_match` rule blocks. Use it to reference Auth0-managed lists when
168+
matching or excluding traffic:
169+
170+
```python
171+
from auth0.management.types import NetworkAclMatch
172+
173+
match = NetworkAclMatch(auth_0_managed=["tor-exit-nodes"])
174+
```
175+
176+
The Python attribute is `auth_0_managed`; it serializes to `auth0_managed`
177+
over the wire. Both spellings are accepted as the constructor keyword.
178+
179+
### Organizations: role members endpoint
180+
181+
New sub-clients `organizations.roles` and `organizations.roles.members`
182+
expose `GET /api/v2/organizations/{id}/roles/{role_id}/members`:
183+
184+
```python
185+
for member in client.organizations.roles.members.list(id="org_id", role_id="role_id"):
186+
print(member)
187+
```
188+
189+
This returns a `SyncPager`/`AsyncPager` of `RoleMember`, wrapping
190+
`ListOrganizationRoleMembersResponseContent`.
191+
192+
### Organizations: third-party client access
193+
194+
`create()`/`update()` and all organization response types gain
195+
`third_party_client_access: Optional[OrganizationThirdPartyClientAccessEnum]`
196+
(`Literal["block", "allow"]`), controlling whether third-party clients can
197+
access the organization.
198+
199+
### Other additions
200+
201+
- **Grants**: `UserGrant.organization_id: Optional[str]` (read-only), returned
202+
from `GET /grants`.
203+
- **Connections**: `discovery_url` / `oidc_metadata` are now available on
204+
`samlp` connections (previously OIDC-only), via new `ConnectionsDiscoveryUrl`
205+
/ `ConnectionsOidcMetadata` on `ConnectionPropertiesOptions` and
206+
`UpdateConnectionOptions`.
207+
- **Event Streams**: new event-type values `connection.created`,
208+
`connection.deleted`, `connection.updated` on `EventStreamEventTypeEnum`,
209+
`EventStreamDeliveryEventTypeEnum`, `EventStreamSubscribeEventsEventTypeEnum`,
210+
and `EventStreamTestEventTypeEnum`; new
211+
`EventStreamCloudEventConnection{Created,Deleted,Updated}*` payload types;
212+
and `EventStreamSubscribeEventsResponseContent` extended with the
213+
connection event variants.
214+
- **Token Vault**: new `grants: Optional[List[TokenVaultPrivilegedAccessGrant]]`
215+
on the privileged-access credential/public-key types.
216+
`TokenVaultPrivilegedAccessGrant`: `{connection: str, scopes: List[str]}`.
217+
- **Errors**: new error body types `NotFoundErrorBody`/`NotFoundErrorBodyError`
218+
and `TooManyRequestsErrorBody`/`TooManyRequestsErrorBodyError`.
219+
- **CloudEvent**: `specversion` is now typed as
220+
`EventStreamCloudEventSpecVersionEnum` (`Literal["1.0"]` + `Any` fallback)
221+
instead of `str`, across group/org/user CloudEvent types.

0 commit comments

Comments
 (0)