Metadata-Version: 2.4
Name: oidc-auth-client
Version: 0.1.7
Summary: Add your description here
Author-email: Ole-Jakob Olsen <ole.jakob.olsen@ngi.no>
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.1
Description-Content-Type: text/markdown

# oidc-auth-client

[![Build and Publish](https://github.com/norwegian-geotechnical-institute/oidc-auth-client/actions/workflows/release.yaml/badge.svg)](https://github.com/norwegian-geotechnical-institute/oidc-auth-client/actions/workflows/release.yaml)

Pure python implementation of an [OIDC](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol) client

Dependencies:

- [httpx](https://www.python-httpx.org/)

## Installing

`pip install oidc-auth-client`

## Example usage

### Authorization Code Flow

Use this flow when your application needs to **authenticate a real user**.

It will:

1. Open the user’s browser
2. Redirect them to your identity provider’s login page
3. Wait for the user to authenticate
4. Receive an authorization code
5. Exchange it for an access token

Best for CLIs, desktop apps, and tools acting **on behalf of a user**.

```py
from oidc_auth_client import Config, AuthorizationCode, OidcProvider

config = Config(
    client_id="<your-client-id>",
    oidc_provider=OidcProvider(
        openid_configuration_url="<auth-provider-url>/.well-known/openid-configuration"
    )
)

# Sign in with the identity provider in the opened browser!
access_token = AuthorizationCode(config=config).get_token()
```

### Client Credentials Flow

Use this flow when your application needs to authenticate **as itself, without user interaction**.
The client exchanges its own `client_id` and `client_secret` directly for an access token.

Ideal for:

- Backend services
- Server-to-server APIs
- Cron jobs
- Automated tasks

```py
from oidc_auth_client import ClientCredentials, OidcProvider, TokenCache
from oidc_auth_client.client_credentials import ClientCredentialsConfig

config = ClientCredentialsConfig(
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET,
    oidc_provider=OidcProvider(openid_configuration_url=OPENID_CONFIGURATION_URL),
)

access_token = ClientCredentials(config=config).get_token()
```

#### Token caching between runs

To allow the user to cache the token between usages, configure with a `TokenCache`. Will store the token in plaintext on the users system.

```py
from oidc_auth_client import Config, TokenCache

config = Config(
    # ...
    token_cache=TokenCache(),
)
```

see some example usage in the [examples folder](https://github.com/norwegian-geotechnical-institute/oidc-auth-client/tree/main/examples).

## Contributing

Requirements:

- [uv](https://docs.astral.sh/uv/) ^0.7.22

Setup:

```sh
uv sync
```

Run tests:

```sh
uv run pytest .
```
