Skip to content

Commit

Permalink
Update README with Python-flavored examples of implementing SAML (#7)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ucarion
ucarion authored May 28, 2024
1 parent a618de5 commit 800be65
Showing 1 changed file with 51 additions and 98 deletions.
149 changes: 51 additions & 98 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.

0 comments on commit 800be65

Please sign in to comment.