Skip to content

Latest commit

 

History

History
131 lines (91 loc) · 5.11 KB

README.md

File metadata and controls

131 lines (91 loc) · 5.11 KB
Raw

Flask-pyoidc

PyPI codecov.io Build Status

This Flask extension provides simple OpenID Connect authentication, by using pyoidc. Currently only "Code Flow") is supported.

Usage

Provider and client configuration

Both static and dynamic provider configuration discovery, as well as static and dynamic client registration, is supported. The different modes of provider configuration can be combined with any of the client registration modes.

Dynamic provider configuration

To use a provider which supports dynamic discovery it suffices to specify the issuer URL:

auth = OIDCAuthentication(issuer='https://op.example.com')

Static provider configuration

To use a provider not supporting dynamic discovery, the static provider configuration can be specified:

provider_config = {
    'issuer': 'https://op.example.com',
    'authorization_endpoint': 'https://op.example.com/authorize',
    'token_endpoint': 'https://op.example.com/token',
    'userinfo_endpoint': 'https://op.example.com/userinfo'
}
auth = OIDCAuthentication(provider_configuration_info=provider_config)

See the OpenID Connect specification for more information about the provider metadata.

Static client registration

If you have already registered a client with the provider all client registration information can be specified:

client_info = {
    'client_id': 'cl41ekfb9j',
    'client_secret': 'm1C659wLipXfUUR50jlZ',

}
auth = OIDCAuthentication(client_registration_info=client_info)

Note: The redirect URIs registered with the provider MUST include <application_url>/redirect_uri, where <application_url> is the URL for the Flask application.

Dynamic client registration

If no client_id is specified in the client_registration_info constructor parameter, the library will try to dynamically register a client with the specified provider.

Protect an endpoint by authentication

To add authentication to one of your endpoints use the oidc_auth decorator:

import flask
from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/')
@auth.oidc_auth
def index():
    return jsonify(id_token=flask.session['id_token'], access_token=flask.session['access_token'],
                   userinfo=flask.session['userinfo'])

This extension will place three things in the session if they are received from the provider:

User logout

To support user logout use the oidc_logout decorator:

@app.route('/logout')
@auth.oidc_logout
def logout():
    return 'You\'ve been successfully logged out!'

This extension also supports RP-Initiated Logout, if the provider allows it.

Specify the error view

If an OAuth error response is received, either in the authentication or token response, it will be passed to the specified error view. An error view is specified by using the error_view decorator:

from flask import jsonify

@auth.error_view
def error(error=None, error_description=None):
 return jsonify({'error': error, 'message': error_description})

The function specified as the error view MUST accept two parameters, error and error_description, which corresponds to the OIDC/OAuth error parameters.

If no error view is specified a generic error message will be displayed to the user.

Configuration

The application using this extension MUST set the following builtin configuration values of Flask:

  • SERVER_NAME (MUST be the same as <flask_url> if using static client registration)
  • SECRET_KEY (this extension relies on Flask sessions, which requires SECRET_KEY)

You may also configure the way Flask sessions handles the user session:

  • PERMANENT_SESSION (added by this extension; makes the session cookie expire after a configurable length of time instead of being tied to the browser session)
  • PERMANENT_SESSION_LIFETIME (the lifetime of a permanent session)

See the Flask documentation for an exhaustive list of configuration options.

Example

Have a look at the example Flask app in app.py for an idea of how to use it.