From 800be6551926e3bc06d154a7d2fd3800228c96d0 Mon Sep 17 00:00:00 2001 From: Ulysse Carion Date: Tue, 28 May 2024 10:28:43 -0700 Subject: [PATCH] Update README with Python-flavored examples of implementing SAML (#7) --- README.md | 149 +++++++++++++++++++----------------------------------- 1 file changed, 51 insertions(+), 98 deletions(-) diff --git a/README.md b/README.md index c19a8a2..e160c38 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ -# SSOReady Python Library +# SSOReady-Python -[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-SDK%20generated%20by%20Fern-brightgreen)](https://github.com/fern-api/fern) +`ssoready` is a Python SDK for the SSOReady API. -The SSOReady Python Library provides convenient access to the SSOReady API from -applications written in Python. +SSOReady is a set of open-source dev tools for implementing Enterprise SSO. You +can use SSOReady to add SAML support to your product this afternoon, for free, +forever. You can think of us as an open source alternative to products like +Auth0 or WorkOS. -The library includes type definitions for all request and response fields, and +This library includes type definitions for all request and response fields, and offers both synchronous and asynchronous clients powered by `httpx`. ## Installation @@ -20,125 +22,76 @@ poetry add ssoready ## Usage -Simply import `SSOReady` and start making calls to our API. +For full documentation, check out https://ssoready.com/docs. -```python -from ssoready.client import SSOReady - -client = SSOReady( - api_key="YOUR_API_KEY", # defaults to SSOREADY_API_KEY -) - -client.saml.redeem_access_code( - saml_access_code="saml_access_code_94d90b43a2027a9084bfc792", -) -``` +At a super high level, all it takes to add SAML to your product is to: -## Async Client +1. Sign up on [app.ssoready.com](https://app.ssoready.com) for free +2. From your login page, call `get_saml_redirect_url` when you want a user to sign in with SAML +3. Your user gets redirected back to a callback page you choose, e.g. `your-app.com/ssoready-callback?saml_access_code=...`. You + call `redeem_saml_access_code` with the `saml_access_code` and log them in. -The SDK also exports an async client so that you can make non-blocking -calls to our API. +Import and construct a SSOReady client like this: ```python -from ssoready.client import AsyncSSOReady - -client = AsyncSSOReady( - api_key="YOUR_API_KEY", -) +from ssoready.client import SSOReady -async def main() -> None: - await client.saml.redeem_access_code( - saml_access_code="saml_access_code_94d90b43a2027a9084bfc792", - ) -asyncio.run(main()) +client = SSOReady() # loads your API key from the env var SSOREADY_API_KEY +# or +client = SSOReady(api_key="ssoready_sk_...") ``` -## Exception Handling - -All errors thrown by the SDK will be subclasses of [`ApiError`](./src/schematic/core/api_error.py). +Calling the `get_saml_redirect_url` endpoint looks like this: ```python -import ssoready - -try: - client.saml.redeem_access_code( - saml_access_code="saml_access_code_94d90b43a2027a9084bfc792", - ) -except ssoready.core.ApiError as e: # Handle all errors - print(e.status_code) - print(e.body) +# this is how you implement a "Sign in with SSO" button +redirect_url = client.get_saml_redirect_url( + # the ID of the organization/workspace/team (whatever you call it) + # you want to log the user into + organization_external_id="..." +).redirect_url + +# redirect the user to `redirect_url`... ``` -## Advanced - -### Timeouts - -By default, requests time out after 60 seconds. You can configure this with a -timeout option at the client or request level. +And using `redeem_saml_access_code` looks like this: ```python -from ssoready.client import SSOReady +# this goes in your handler for POST /ssoready-callback +redeem_result = client.saml.redeem_saml_access_code(saml_access_code="saml_access_code_...") -client = SSOReady( - ..., - # All timeouts are 20 seconds - timeout=20.0, -) +email = redeem_result.email +organization_external_id = redeem_result.organization_external_id -# Override timeout for a specific method -client.saml.redeem_access_code(..., { - timeout_in_seconds=20.0 -}) +# log the user in as `email` inside `organizationExternalId`... ``` -### Retries - -The SDK is instrumented with automatic retries with exponential backoff. A request will be -retried as long as the request is deemed retriable and the number of retry attempts has not grown larger -than the configured retry limit (default: 2). - -A request is deemed retriable when any of the following HTTP status codes is returned: - -- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) -- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) -- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors) - -Use the `max_retries` request option to configure this behavior. - -```python -client.saml.redeem_access_code(..., { - max_retries=1 -}) -``` +Check out [the quickstart](https://ssoready.com/docs) for the details spelled +out more concretely. The whole point of SSOReady is to make enterprise SSO super +obvious and easy. -### Custom HTTP client +## Async Client -You can override the httpx client to customize it for your use-case. Some common use-cases -include support for proxies and transports. +You an also use asyncio with this SDK. Do so by using `AsyncSSOReady` instead of +`SSOReady`. ```python -import httpx +from ssoready.client import AsyncSSOReady -from ssoready.client import SSOReady +client = AsyncSSOReady() -client = SSOReady(..., - http_client=httpx.Client( - proxies="http://my.test.proxy.example.com", - transport=httpx.HTTPTransport(local_address="0.0.0.0"), - ), -) +async def main() -> None: + await client.saml.get_redirect_url(organization_external_id="...") + +asyncio.run(main()) ``` -## Beta status - -This SDK is in beta, and there may be breaking changes between versions without a major version update. -Therefore, we recommend pinning the package version to a specific version in your package.json file. -This way, you can install the same version each time without breaking changes unless you are -intentionally looking for the latest version. +All methods available on the sync `SSOReady` client are also available on +`AsyncSSOReady`. ## Contributing -While we value open-source contributions to this SDK, this library is generated programmatically. -Additions made directly to this library would have to be moved over to our generation code, -otherwise they would be overwritten upon the next generated release. Feel free to open a -PR as a proof of concept, but know that we will not be able to merge it as-is. +Issues and PRs are more than welcome. Be advised that this library is largely +autogenerated from +[`ssoready/fern-config`](https://github.com/ssoready/fern-config). Most code +changes ultimately need to be made there, not on this repo.