cegalkeystoneauth 0.1.29545
A Python package to handle Keystone tokens
Requires Python: >=3.6

# Introduction

A Python client to use with Cegal Keystone.

# Usage

1. (Optional) Configure logging
2. Define an OidcOptions object
3. Instantiate an OidcClient object passing in the previously created OidcOptions object
   - If you need to select another flow use the OidcFlow enum
4. There is only one method required, use the OidcClient object to call get_access_token()
5. Use the access token returned

You should always call .get_access_token() each time you need to use the token. This method takes care of expiration and renewal.

# Basic Example (should cover most use cases)

```python
import logging
import sys

# Import the OidcClient and OidcOptions
from cegal.keystone_auth import OidcClient, OidcOptions

# Configure logging
logging.getLogger()
logging.basicConfig(
    format="%(asctime)s %(levelname)s %(message)s",
    level=logging.DEBUG,
    stream=sys.stdout,
)

# Create OidcOptions
options = OidcOptions(
    "python_rp",
    OidcClient.KEYSTONE_URL,
    extra_scopes=["scope1"],
    audiences=["api1"],
)
# Instantiate an OidcClient
client = OidcClient(options)
# Each time you need to use the token call .get_access_token()
token = client.get_access_token()

```

# Example using device flow

```python
import logging
import sys
from time import sleep

from cegal.keystone_auth import OidcClient, OidcOptions, OidcFlow

logging.getLogger()
logging.basicConfig(
    format="%(asctime)s %(levelname)s %(message)s",
    level=logging.DEBUG,
    stream=sys.stdout,
)

options = OidcOptions(
    "python_rp",
    OidcClient.KEYSTONE_STG_URL,
    extra_scopes=["portal_api"],
    audiences=["portal_api"],
    oidc_flow=OidcFlow.device_code,
    no_cache=True,
)

client = OidcClient(options)

token = client.get_access_token()
print(token)

```

# Extra scopes and audience

If you are requesting access to APIs then you will need to include these as a list of strings in the extra_scopes OidcOptions arg.\
In Keystone, API scopes are by default associated with an API Resource which will return an audience claim in the access token. You must therefore also supply the API Resource names as the audience when specifying extra_scopes.\
An API Resource can have multiple API scopes and they are not necessarily named the same, so you will need to obtain this information from the person setting up the application in Keystone.

# Customing the authentication landing browser page 

When using interactive login, the library opens an authentication request page at the specified identity server.  This server then requests the user's password (or skips this if the browser has the details) and redirects the browser page back to a local web server with the auth code specified in the URL.   (This way, the auth-code is communicated to the local process without the local server needing any connection to the internet).

By default, the browser upon successful authentication displays a simple message.  You can customize the behaviour by supplying a `page_handler` object in the OidcClient constructor.

The default page handler is in the `cegal.keystone_auth.responses` module.  A more sophisticated example is `TwoStagePageHandler` which redirects back to a different page.   This is designed currently to be used to PythonToolPro to display a 'welcome' page with version details.   Since the page handler is supplied with the auth state (and therefore auth code) the handler can query Keystone for up-to-date version details.

N.b. This API feels very immature;  it obviously *wants* to be a full-fledged http stack with routing, responses and templating etc.

# Developer extras

If you are currently developing something and the client settings are changing often there is a helper method available within the client.\
Call client.destroy_tokens_for_client() and this will clear your client_id's tokens from disk and memory.



# Installing for development

Start a shell in the root of the repository working directory.

Create a venv:

`python -m venv .venv`

Activate it (varies according to OS and shell):

`.venv\Scripts\activate.ps1`

Upgrade pip and setuptools:

```
python -m pip install --upgrade pip
python install --setuptools
pip install -r requirements.txt
```

Install as live development package:

`pip install -e .`

# Tests

Run `pytest` to run all the non-interactive tests.  Those tests requiring user interaction (e.g. a browser, or device-flow login) can be run using `pytest --interactive`

# Devcontainer

This repository includes a devcontainer which can be used within VSCode.  `pytest --interactive` currently will not function correctly:  the browser is launched outside of the container on the developer's machine and the redirect is not able to reach the local server.  A future fix for this might be to include firefox in the devcontainer, set $BROWSER to be firefox, and require an X-server on the developer's machine.