diff --git a/README.md b/README.md index d0cefb7..78e32f7 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ pip install auth0-server-python If you’re using Poetry: ```shell -poetry install auth0-server-python +poetry add auth0-server-python ``` ### 2. Create the Auth0 SDK client @@ -39,8 +39,8 @@ auth0 = ServerClient( client_id='', client_secret='', secret='', - authorization_params= { - redirect_uri: '', + authorization_params={ + "redirect_uri": '', } ) ``` @@ -82,8 +82,10 @@ app = FastAPI() @app.get("/auth/login") -async def login(request: Request): - authorization_url = await auth0.start_interactive_login() +async def login(request: Request, response: Response): + authorization_url = await auth0.start_interactive_login( + store_options={"request": request, "response": response} + ) return RedirectResponse(url=authorization_url) ``` @@ -98,8 +100,11 @@ Here is an example of what this would look like in FastAPI, with `redirect_uri` ```python @app.get("/auth/callback") -async def callback(request: Request): - result = await auth0.complete_interactive_login(str(request.url)) +async def callback(request: Request, response: Response): + result = await auth0.complete_interactive_login( + str(request.url), + store_options={"request": request, "response": response} + ) # Store session or set cookies as needed return RedirectResponse(url="/") ``` diff --git a/examples/ConfigureStore.md b/examples/ConfigureStore.md index 5afeadf..e3a6305 100644 --- a/examples/ConfigureStore.md +++ b/examples/ConfigureStore.md @@ -23,8 +23,13 @@ Each store implements `set`, `get`, and `delete`. The `StateStore` adds an optio When you **start** or **complete** an Auth0 flow, you can pass a `store_options` dictionary with extra data (like the FastAPI `Request` and `Response`) that the store can use for reading/writing cookies. For example: ```python +from auth0_server_python.auth_types import StartInteractiveLoginOptions + store_options = {"request": request, "response": response} -await auth_client.start_login(app_state={"return_to": "/profile"}, store_options=store_options) +await server_client.start_interactive_login( + StartInteractiveLoginOptions(app_state={"return_to": "/profile"}), + store_options=store_options +) ``` ## 2.Stateless Store (All Data in Cookies) ### When to Use It @@ -84,7 +89,7 @@ When users log in: @app.get("/auth/login") async def login(request: Request, response: Response): store_options = {"request": request, "response": response} - redirect_url = await request.app.state.auth_client.start_login( + redirect_url = await request.app.state.auth_client.start_interactive_login( store_options=store_options ) return RedirectResponse(url=redirect_url) @@ -395,7 +400,7 @@ Often you need `request` and `response` objects to set or clear cookies. In your @app.get("/auth/login") async def login(request: Request, response: Response): store_options = {"request": request, "response": response} - auth_url = await auth_client.start_login( + auth_url = await server_client.start_interactive_login( store_options=store_options ) return RedirectResponse(auth_url) @@ -405,8 +410,8 @@ Likewise for logout or completing the login callback: @app.get("/auth/callback") async def callback(request: Request, response: Response): store_options = {"request": request, "response": response} - session_data = await auth_client.complete_login( - str(request.url), + session_data = await server_client.complete_interactive_login( + str(request.url), store_options=store_options ) ... diff --git a/examples/InteractiveLogin.md b/examples/InteractiveLogin.md index 9635647..cead99e 100644 --- a/examples/InteractiveLogin.md +++ b/examples/InteractiveLogin.md @@ -11,7 +11,7 @@ This guide covers how to customize the authorization parameters, pass custom app Interactive login begins by configuring a redirect_uri—the URL Auth0 will use to send the user back after authentication. For example, when instantiating your core `ServerClient`: ```python -from auth_server.server_client import ServerClient +from auth0_server_python.auth_server.server_client import ServerClient server_client = ServerClient( domain="YOUR_AUTH0_DOMAIN", @@ -50,13 +50,17 @@ server_client = ServerClient( ### Dynamic Configuration Per Call You can also override or add parameters when calling `start_interactive_login()`: ```python -authorization_url = await server_client.start_interactive_login({ - "authorization_params": { - "scope": "openid profile email", - "audience": "urn:custom:api", - "foo": "bar" # arbitrary custom parameter - } -}) +from auth0_server_python.auth_types import StartInteractiveLoginOptions + +authorization_url = await server_client.start_interactive_login( + StartInteractiveLoginOptions( + authorization_params={ + "scope": "openid profile email", + "audience": "urn:custom:api", + "foo": "bar" # arbitrary custom parameter + } + ) +) ``` > [!NOTE] > Any parameter specified here will override the corresponding global configuration. @@ -66,10 +70,12 @@ authorization_url = await server_client.start_interactive_login({ The `app_state` parameter allows you to pass custom state (for example, a return URL) that is later available when the login process completes. ```python +from auth0_server_python.auth_types import StartInteractiveLoginOptions + # Start interactive login with custom app state: -authorize_url = await server_client.start_interactive_login({ - "app_state": {"returnTo": "http://localhost:3000/dashboard"} -}) +authorize_url = await server_client.start_interactive_login( + StartInteractiveLoginOptions(app_state={"returnTo": "http://localhost:3000/dashboard"}) +) # Later, after completing login: result = await server_client.complete_interactive_login(callback_url) @@ -83,10 +89,12 @@ print(result.get("app_state").get("returnTo")) # Should output: http://localhos To enable PAR, simply set the flag in your interactive login options. When enabled, the SDK will send an HTTP POST request with the authorization parameters to the PAR endpoint (retrieved from OIDC metadata) and use the returned `request_uri` to build the final authorization URL. ```python +from auth0_server_python.auth_types import StartInteractiveLoginOptions + # Enable PAR dynamically for a login call: -authorization_url = await server_client.start_interactive_login({ - "pushed_authorization_requests": True -}) +authorization_url = await server_client.start_interactive_login( + StartInteractiveLoginOptions(pushed_authorization_requests=True) +) ``` >[!IMPORTANT] > Using PAR requires that your Auth0 tenant is configured to support it. Refer to Auth0's documentation for details. @@ -96,22 +104,22 @@ authorization_url = await server_client.start_interactive_login({ When using PAR, you can also supply Rich Authorization Request details by including an `authorization_details` field in the `authorization_params`: ```python import json +from auth0_server_python.auth_types import StartInteractiveLoginOptions -authorization_url = await server_client.start_interactive_login({ - "pushed_authorization_requests": True, - "authorization_params": { - "authorization_details": json.dumps([{ - "type": "your_type", - "additional_field": "value" - }]) - } -}) +authorization_url = await server_client.start_interactive_login( + StartInteractiveLoginOptions( + pushed_authorization_requests=True, + authorization_params={ + "authorization_details": json.dumps([{ + "type": "your_type", + "additional_field": "value" + }]) + } + ) +) ``` After completing the interactive login, the SDK will expose the `authorization_details` in the result: ```python -import json - -authorization_url = await server_client.start_interactive_login({ result = await server_client.complete_interactive_login(callback_url) print(result.get("authorization_details")) ``` @@ -122,7 +130,7 @@ print(result.get("authorization_details")) Most methods in the SDK accept a second argument called `store_options`. This dictionary should include the HTTP Request and Response objects (or equivalent) that the store uses to manage cookies and session data. ```python store_options = {"request": request, "response": response} -authorization_url = await server_client.start_interactive_login({}, store_options=store_options) +authorization_url = await server_client.start_interactive_login(store_options=store_options) ``` This enables the SDK to correctly read and set cookies for session management. diff --git a/examples/RetrievingData.md b/examples/RetrievingData.md index 88fb610..97f3528 100644 --- a/examples/RetrievingData.md +++ b/examples/RetrievingData.md @@ -5,7 +5,7 @@ The SDK's `get_user()` can be used to retrieve the current logged-in user: ```python -user = await serverClient.get_user(); +user = await serverClient.get_user() ``` ### Passing Store Options @@ -27,7 +27,7 @@ Read more above in [Configuring the Store](./ConfigureStore.md). The SDK's `get_session()` can be used to retrieve the current session data: ```python -session = await serverClient.get_session(); +session = await serverClient.get_session() ``` ### Passing Store Options @@ -185,7 +185,7 @@ access_token_for_google = await server_client.get_access_token_for_connection(co ``` - `connection`: The connection for which an access token should be retrieved, e.g. `google-oauth2` for Google. -- `loginHint`: Optional login hint to inform which connection account to use, can be useful when multiple accounts for the connection exist for the same user. +- `login_hint`: Optional login hint to inform which connection account to use, can be useful when multiple accounts for the connection exist for the same user. The SDK will cache the token internally, and return it from the cache when not expired. When no token is found in the cache, or the token is expired, calling `get_access_token_for_connection()` will call Auth0 to retrieve a new token and update the cache.