Client library for accessing GaaP services


Keywords
python
License
MIT-feh
Install
pip install ags_client==0.1.12

Documentation

Accessing GaaP Services Client

Test result

Python package providing a WSGI middleware for accessing GaaP services.

Installation

pip3 install ags_client

Usage

Registration

You will need a client ID and client secret from the GaaP Identity Broker. You can't get these yet, but soon will by emailing us with a brief summary of:

  • who you are
  • what project you're going to be using it on

Quick Start

Flask

For example: given your Flask app is defined in webservice.py in a variable named app, create a file called wsgi.py:

import ags

from webservice import app


app.wsgi_app = ags.Client(app.wsgi_app)

Then start your app with a WSGI server such as Gunicorn or uWSGI. Eg:

gunicorn wsgi:app

Configuration

The middleware looks for certain environment variables for settings. The following variables are REQUIRED:

AGS_CLIENT_ISSUER
The URL of the OIDC identity broker
AGS_CLIENT_ID
The client ID that you have been issued
AGS_CLIENT_SECRET
The client secret that you have been issued
AGS_CLIENT_AUTHENTICATED_PATHS
Comma separated list of paths in your web application that require authentication. May include regular expressions.
AGS_CLIENT_SIGN_OUT_PATH
Path to sign out view in your application - default: sign-out

The following variables are OPTIONAL:

AGS_CLIENT_DEBUG
If set to True, errors will be handled by the Werkzeug debugger. DO NOT USE IN PRODUCTION!
AGS_CLIENT_LOG_PATH
Log to the specified file, in addition to console
AGS_CLIENT_SESSION_COOKIE
The name of the cookie used to store the session ID - default: ags_client_session
AGS_CLIENT_SESSION_SECRET

The secret key use to encrypt the session cookie - default: generates a new secret on start-up

Note

Override this value when deploying across multiple hosts, otherwise sessions may become invalid across requests

The following variables can be used to override defaults, but usually should not be used:

AGS_CLIENT_CALLBACK_PATH
Overrides default OIDC callback path
AGS_CLIENT_FEATURE_FLAG_COOKIE
The name of the cookie used to store the feature flag status - default: ags_client_active
AGS_CLIENT_FEATURE_FLAG_DEFAULT
The default state of the feature flag if the cookie is not set - default: True
AGS_CLIENT_VERIFY_SSL
If False, verification of the broker's SSL certificate is skipped

Usage

When activated, the middleware will intercept requests to the paths specified in the AGS_CLIENT_AUTHENTICATED_PATHS environment variable and perform OpenID Connect authentication before passing the user authentication details on to the wrapped application.

It will also intercept requests to the AGS_CLIENT_SIGN_OUT_PATH and end the session on the identity broker before passing through to the wrapped application.

Activation

The middleware is activated by default, unless the AGS_CLIENT_FEATURE_FLAG_DEFAULT environment variable is set to False.

The middleware is activated or deactivated via a feature flag cookie, which can be toggled by browsing to /toggle-feature/{FLAG}, where {FLAG} is the value of the AGS_CLIENT_FEATURE_FLAG_COOKIE environment variable or the default value ags_client_active.

Support

This source code is provided as-is, with no incident response or support levels. Please log all questions, issues, and feature requests in the Github issue tracker for this repo, and we'll take a look as soon as we can. If you're reporting a bug, then it really helps if you can provide the smallest possible bit of code that reproduces the issue. A failing test is even better!

Contributing

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed
  • Check the issue tracker to make sure someone hasn't already requested and/or contributed the feature
  • Fork the project
  • Start a feature/bugfix branch
  • Commit and push until you are happy with your contribution
  • Make sure your changes are covered by unit tests, so that we don't break it unintentionally in the future.
  • Please don't mess with setup.py, version or history.

Copyright

Copyright © 2016 HM Government (Government Digital Service). See LICENSE for further details.