Help:Toolforge/My first Flask OAuth tool
Overview
Python webservices are used by many existing tools. Python is a high-level, interpreted programming language with many available libraries for making webservices and integrating with MediaWiki.
This stub webservice is designed to get a sample Python application installed onto Toolforge as quickly as possible. The application is written using the Flask framework.
The guide will teach you how to:
- Create a new tool
- Run a Python 3 WSGI webservice on Kubernetes
- Allow webservice visitors to authenticate via OAuth v1 using their Wikimedia unified account
Getting started
Prerequisites
Skills
- Basic knowledge of Python
- Basic knowledge of SSH
- Basic knowledge of the Unix command line
- Familiarity with OAuth (v1) terminology would be nice but not required
Accounts
Step-by-step guide
- Step 1: Create a new tool account
- Step 2: Create a basic Flask WSGI webservice
- Step 3: Add a configuration file
- Step 4: Add support for OAuth1 authentication
Step 1: Create a new tool account
- Follow the Toolforge quickstart guide to create a Toolforge tool and SSH into Toolforge.
- For the examples in this tutorial,
<TOOL NAME>
is used to indicate places where your unique tool name is used in another command.
- For the examples in this tutorial,
- Run
$ become <TOOL NAME>
to change to the tool user.
Step 2: Create a basic Flask WSGI webservice
- What is Flask?
Flask is a popular web development framework for Python.
How to create a basic Flask WSGI webservice
- Create the $HOME/www/python/src directory for your application
$ mkdir -p $HOME/www/python/src
- Create a Python virtual environment for the application's external library dependencies
The virtual environment allows the tool to install Python libraries locally without needing a Toolforge administrator's help. The default webservice
configuration will automatically load libraries from $HOME/www/python/venv
.
The webservice will run on Kubernetes. A Kubernetes shell is required to create the virtual environment.
This will ensure that the version of Python the virtual environment uses matches the version of Python used by the Kubernetes runtime.
$ webservice --backend=kubernetes python3.11 shell
If you don't see a command prompt, try pressing enter.
$ python3 -m venv $HOME/www/python/venv
$ source $HOME/www/python/venv/bin/activate
$ pip install --upgrade pip
Downloading/unpacking pip from [...]
[...]
Successfully installed pip
Cleaning up...
If you run python3 -m venv $HOME/www/python/venv
and get an error beginning with "The virtual environment was not created successfully because ensurepip is not available.", you didn't run the first command (the "webservice" one) first.
- Add Flask to the virtual environment
Note: It is Python best practice to keep track of library dependencies in a file checked into version control. The traditional way is arequirements.txt
file, which can be generated by running pip freeze > requirements.txt
. A more modern way is to use a dependencies list in the project table of a pyproject.toml file [1] What's important is that you have a reproducible way to build your virtual env from scratch.
$ cat > $HOME/www/python/src/requirements.txt << EOF
flask
EOF
$ pip install -r $HOME/www/python/src/requirements.txt
Collecting flask (from -r www/python/src/requirements.txt (line 1))
[...]
Successfully installed [...]
The initial virtual environment is now set-up. Exit out of the Kubernetes shell and return to the SSH session on the bastion.
$ exit
- Create a 'hello world' WSGI application
# -*- coding: utf-8 -*-
#
# This file is part of the Toolforge flask WSGI tutorial
#
# Copyright (C) 2017 Bryan Davis and contributors
#
# This program is free software: you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
# more details.
#
# You should have received a copy of the GNU General Public License along
# with this program. If not, see <http://www.gnu.org/licenses/>.
import flask
app = flask.Flask(__name__)
@app.route('/')
def index():
return 'Hello World!'
Note: The 'Hello World!' file above starts with a license header that places it under the GPLv3+ license.
Code on Toolforge should always be licensed under an Open Source Initiative (OSI) approved license. See the Right to fork policy for more information on this Toolforge policy.
- Start the webservice
$ webservice --backend=kubernetes python3.11 start
Starting webservice.
Once the webservice is started, navigate to https://<TOOL NAME>.toolforge.org/
in your web browser, and see a 'Hello World!' message. It might take a few minutes until it is reachable.
Notes
Toolforge uses a uWSGI configuration designed to make it easy to deploy a typical Python webservice. This configuration uses a 'convention over configuration' design with the following expectations:
- The application will have a WSGI entry point in
$HOME/www/python/src/app.py
in a variable namedapp
. - Python libraries will be loaded from a virtualenv located in
$HOME/www/python/venv
. - Logs will be written to
$HOME/uwsgi.log
- Expected file layout
$HOME
├─ uwsgi.log
└─ www
└─ python
├─ src
│ └─ app.py
└─ venv
Troubleshooting
If there is an error when the webservice is started, look in $HOME/uwsgi.log
and $HOME/error.log
for an explanation.
One Unix utility to use for this is tail
, which will display lines from the end of a file:
$ tail -n 50 $HOME/uwsgi.log
$ tail -n 50 $HOME/error.log
Step 3: Add a configuration file
The application will eventually need some configuration data like OAuth secrets or passwords. These should not be hard coded into the Python files, because the secrets and passwords will be visible once the source code is made public.
There are many different ways to separate code from configuration, but the most straight forward when using Flask is to keep the configuration in a file that can be parsed easily, and then add it to the app.config
object that Flask provides.
How to add a configuration file
- Read configuration from a file
In this tutorial, a TOML file is used to hold secrets. TOML is a nice choice, because it has a simple syntax, is easy for humans to read, supports both comments and complex values like lists and dictionaries, and Python versions 3.11 and later have built-in support for parsing them.
Update the $HOME/www/python/src/app.py
file to read configuration from a config.toml
file in the same directory and get the greeting from the configuration file:
# -*- coding: utf-8 -*-
#
# This file is part of the Toolforge Flask + OAuth WSGI tutorial
#
# Copyright (C) 2017 Bryan Davis and contributors
#
# This program is free software: you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
# more details.
#
# You should have received a copy of the GNU General Public License along
# with this program. If not, see <http://www.gnu.org/licenses/>.
import flask
import os
import tomllib
app = flask.Flask(__name__)
# Load configuration from TOML file
__dir__ = os.path.dirname(__file__)
with open(os.path.join(__dir__, 'config.toml'), 'rb') as f:
app.config.update(tomllib.load(f))
@app.route('/')
def index():
return app.config['GREETING']
A configuration file is now required or the application will produce an error. Eventually, secrets will be included in this file. The file's permissions should be changed so that only the tool user can read it.
$ touch $HOME/www/python/src/config.toml
$ chmod u=rw,go= $HOME/www/python/src/config.toml
$ cat > $HOME/www/python/src/config.toml << EOF
GREETING = "Goodnight moon!"
EOF
Now restart the webservice:
$ webservice restart
Restarting webservice...
Once the webservice has restarted, navigate to https://<TOOL NAME>.toolforge.org/
in your web browser and see the new 'Goodnight moon!' message.
Troubleshooting
If there is an error, look in $HOME/uwsgi.log
and $HOME/error.log
for an explanation.
Step 4: Add support for OAuth authentication
OAuth is a safe mechanism for authenticating a Wikimedia user in the application. For the basics, read more about OAuth on mediawiki.org.
How to add mwoauth to the virtual environment
mwoauth library is used to handle most of the complexity of making OAuth requests to MediaWiki.
$ webservice --backend=kubernetes python3.11 shell
If you don't see a command prompt, try pressing enter.
$ source $HOME/www/python/venv/bin/activate
$ cat >> $HOME/www/python/src/requirements.txt << EOF
mwoauth
EOF
$ pip install -r $HOME/www/python/src/requirements.txt
Requirement already satisfied: flask [...]
Collecting mwoauth (from -r req.txt (line 3))
[...]
Successfully installed [...]
$ exit
- Update the application code
Here is our new $HOME/www/python/src/app.py
file:
www/python/src/app.py |
---|
$HOME/www/python/src/app.py # -*- coding: utf-8 -*-
#
# This file is part of the Toolforge Flask + OAuth WSGI tutorial
#
# Copyright (C) 2017 Bryan Davis and contributors
#
# This program is free software: you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
# more details.
#
# You should have received a copy of the GNU General Public License along
# with this program. If not, see <http://www.gnu.org/licenses/>.
import flask
import mwoauth
import os
import tomllib
app = flask.Flask(__name__)
# Load configuration from TOML file
__dir__ = os.path.dirname(__file__)
with open(os.path.join(__dir__, 'config.toml'), 'rb') as f:
app.config.update(tomllib.load(f))
@app.route('/')
def index():
greeting = app.config['GREETING']
username = flask.session.get('username', None)
return flask.render_template(
'index.html', username=username, greeting=greeting)
@app.route('/login')
def login():
"""Initiate an OAuth login.
Call the MediaWiki server to get request secrets and then redirect the
user to the MediaWiki server to sign the request.
"""
consumer_token = mwoauth.ConsumerToken(
app.config['CONSUMER_KEY'], app.config['CONSUMER_SECRET'])
try:
redirect, request_token = mwoauth.initiate(
app.config['OAUTH_MWURI'], consumer_token)
except Exception:
app.logger.exception('mwoauth.initiate failed')
return flask.redirect(flask.url_for('index'))
else:
flask.session['request_token'] = dict(zip(
request_token._fields, request_token))
return flask.redirect(redirect)
@app.route('/oauth-callback')
def oauth_callback():
"""OAuth handshake callback."""
if 'request_token' not in flask.session:
flask.flash(u'OAuth callback failed. Are cookies disabled?')
return flask.redirect(flask.url_for('index'))
consumer_token = mwoauth.ConsumerToken(
app.config['CONSUMER_KEY'], app.config['CONSUMER_SECRET'])
try:
access_token = mwoauth.complete(
app.config['OAUTH_MWURI'],
consumer_token,
mwoauth.RequestToken(**flask.session['request_token']),
flask.request.query_string)
identity = mwoauth.identify(
app.config['OAUTH_MWURI'], consumer_token, access_token)
except Exception:
app.logger.exception('OAuth authentication failed')
else:
flask.session['access_token'] = dict(zip(
access_token._fields, access_token))
flask.session['username'] = identity['username']
return flask.redirect(flask.url_for('index'))
@app.route('/logout')
def logout():
"""Log the user out by clearing their session."""
flask.session.clear()
return flask.redirect(flask.url_for('index'))
|
The new app.py
uses the Jinja template system that is built into Flask rather than the bare strings that were used in the 'hello world' version. One reason for this is that Jinja will automatically escape strings. This is important in any application that will be serving data gathered from a user or even a database to protect against security vulnerabilities like cross-site scripting.
By default Flask will look for templates in the $HOME/www/python/src/templates
directory.
$ mkdir $HOME/www/python/src/templates
$ edit $HOME/www/python/src/templates/index.html
<!DOCTYPE HTML>
<html>
<head>
<title>My first Flask OAuth tool</title>
</head>
<body>
{% if username %}
<p>Hello {{ username }}!</p>
<p><a href="{{ url_for('logout') }}">logout</a></p>
{% else %}
<p>{{ greeting }}</p>
<p><a href="{{ url_for('login') }}">login</a></p>
{% endif %}
</body>
</html>
- Update the configuration to add OAuth secrets
Add new configuration values to $HOME/www/python/src/config.toml
file to go with the new code.
- Register a new OAuth consumer.
- As callback URL, use:
https://<TOOL NAME>.toolforge.org/oauth-callback
- As contact e-mail address, use the e-mail address linked to your Wikimedia unified account.
- Keep the default grant settings ('Request authorization for specific permissions.' with just 'Basic rights' selected)
- You will be able to use your own account before the consumer has been approved.
- Copy the consumer token and secret token values that are generated. These are needed for the config.toml file.
A secret key for securely signing the session cookie and other security related needs must also be present in the config.toml file.
$ cat >> $HOME/www/python/src/config.toml << EOF
SECRET_KEY = "$(python3 -c "import secrets; print(secrets.token_urlsafe(48))")"
OAUTH_MWURI = "https://meta.wikimedia.org/w/index.php"
CONSUMER_KEY = "the 'consumer token' value from your OAuth consumer registration"
CONSUMER_SECRET = "the 'secret token' value from your OAuth consumer registration"
EOF
- Restart the webservice
$ webservice restart
Restarting webservice...
Once the webservice has restarted, navigate to https://<TOOL NAME>.toolforge.org/
in your web browser to see the new landing page.
Try using the login and logout links to test out the OAuth integration.
Additional troubleshooting
bash: webservice: command not found
- Check shell prompt.
- If it ends in
@interactive $
, you are inside a Kubernetes shell (webservice --backend=kubernetes python3.11 shell
).- The
webservice
command is only available on the Toolforge bastions.
- The
- Type
exit
to leave the Kubernetes shell and return to the bastion.
Error: An error occurred in the OAuth protocol: Invalid signature
- Double check the values set for
CONSUMER_KEY
andCONSUMER_SECRET
Get more debugging output from Flask
- Add
Debug = True
toconfig.toml
- Check
uwsgi.log
for more information.
Note: This needs a webservice restart
to take effect.
toolsws.tool.InvalidToolException: Tool username should begin with tools.
- Run
become <TOOL NAME>
to change to the tool user.
Next Steps
Now that your Flask OAuth tool is set-up here are some next steps to consider:
- Use the OAuth token data stored in
flask.session['access_token']
to make API calls as the authorized user. - Explore the mwclient library to make interacting with the MediaWiki Action API easier.
- Publish your source code in a git repository.
- Add a co-maintainer.
- Create a description page for your tool.
- Use the toolforge library to set a nice user agent.
- If possible, run the tool on your local system as well (clone the source code repository, install dependencies, run
FLASK_APP=app.py FLASK_ENV=development flask run
). In development mode (which you should never run on Toolforge!), Flask offers some additional conveniences, such as automatic reloading of source files on save or an in-browser debugger on errors.
Communication and support
Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:
- Chat in real time in the IRC channel #wikimedia-cloud connect or the bridged Telegram group
- Discuss via email after you have subscribed to the cloud@ mailing list
- Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
- Read the News wiki page
Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself
Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)