Flask-SAML Documentation

Transcription

1 Flask-SAML Documentation Release Florian Rüchel Oct 20, 2020

2

3 Contents 1 Installation Quickstart Advanced Configuration Change User Storage Error Handling Changing the Route Prefix Change the Default Redirect API Extension Signals Recipes Integration with Flask Principal Links 11 Index 13 i

4 ii

5 Flask-SAML Documentation, Release This neat Flask extension provides you with an easy way to integrate SAML into your Flask web app. Contents 1

6 Flask-SAML Documentation, Release Contents

7 CHAPTER 1 Installation Beyond installing the library (e.g. pip install flask_saml) you need to have xmlsec1 installed, e.g. for Ubuntu: apt-get install xmlsec1 1.1 Quickstart import flask import flask_saml app = flask.flask( name ) app.config.update({ 'SECRET_KEY': 'soverysecret', 'SAML_METADATA_URL': ' }) flask_saml.flasksaml(app) Let s go step by step. The SECRET_KEY is required by the default session storage (see Change User Storage if you would like to use a different mechanism to manage sessions). SAML_METADATA_URL is a URL that contains the SAML metadata which configures the whole app. Warning: The metadata URL should be a HTTPS URL as an untrusted source for metadata will allow an attacker to log in as any user they like. The extension also sets up the following routes: /saml/logout/: Log out from the application. This is where users go if they click on a Logout button. /saml/sso/: Log in through SAML. 3

8 Flask-SAML Documentation, Release /saml/acs/: After /saml/sso/ has sent you to your IdP it sends you back to this path. Also your IdP might provide direct login without needing the /saml/sso/ route. In general you don t need to worry about this too much. Sending users to login and logout is as simple as calling flask.url_for('login') and flask.url_for('logout') using Flasks flask.url_for() method. Note: To send the user back to a specific URL after a login, provide the next parameter: flask.url_for('login', next=' Be advised that only things that belong to the correct domain and port will be accepted. Also, there is currently no support for a redirect after a logout. Now that we have the basics covered, let s go over some finer details in case you wish to tweak some of the bits. This might already cover everything you need but in case you want to tweak the configuration check out Advanced Configuration. 4 Chapter 1. Installation

9 CHAPTER 2 Advanced Configuration 2.1 Change User Storage The default implementation will just store the user in a session. Alternatively, you can use whatever method your prefer. To realise this, the extension provides two functions you can implement. You can either implement all or none of them since they work hand in hand. 1. The login signal: Once a user successfully authenticated, the extension sends the user data over via the saml_authenticated signal. 2. The logout signal: When a user logs out, this signal must make sure all data relating to that users session are cleared. The signal saml_log_out is sent. Here s what the default implementation does: def _session_login(sender, subject, attributes, auth): flask.session['saml'] = { 'subject': subject, 'attributes': attributes, } def _session_logout(sender): flask.session.clear() Assuming the same configuration as above, we can create the extension like this: app.config['saml_use_sessions'] = False ext = flask_saml.flasksaml(app) flask_saml.saml_authenticated.connect(_session_login, app) flask_saml.saml_log_out.connect(_session_logout, app) As you can see, the _session_login function receives a subject and attributes for the user. In addition an auth object is provided. In most cases you will only need the subject which is the unique identifier for the user 5

10 Flask-SAML Documentation, Release (for example an ) and the attributes which contains all the SAML attributes. These were both received from the auth object which can be used for more advanced operations. 2.2 Error Handling Ocassionally, errors will happen during login. If you don t do anything they will go into the void and they are not very useful there. So let s hook into the saml_error signal! Any time an error happens, this function gets the exception thrown by the PySAML2 library. Here is what a simple Flask app might do with def on_saml_error(sender, exception): flask.flash(exception.args[0], 'error') This uses Flask s flashing mechanism but what you do with them is really up to you. We just send them your way and don t worry about it too much. 2.3 Changing the Route Prefix Maybe you think /saml is a stupid prefix (because /teddybear make more sense in your opinion) or you have a collision. So change the prefix: app.config['saml_prefix'] = '/teddybear' flask_saml.flasksaml(app) 2.4 Change the Default Redirect By default the user is redirected to /. If you would rather have a different landing page, then that s totally possible: app.config['saml_default_redirect'] = '/dashboard' So now on both logout and login, this is your default. Remember, for login you can always provide the next parameter to specify where the user should go after a successful login. 2.5 API Extension class flask_saml.flasksaml(app=none, debug=false) The extension class. Refer to the documentation on its usage. Parameters app The flask.flask app. debug (bool) Enable debug mode for the extension. 6 Chapter 2. Advanced Configuration

11 Flask-SAML Documentation, Release Signals flask_saml.saml_authenticated Signal sent when the user has successfully authenticated. Receives three parameters: subject, attributes and auth. auth is the actual saml.response.authnresponse from which both subject and attributes were extracted. Can be used to override the default session implementation as described in Change User Storage. flask_saml.saml_log_out Signal sent when the user has logged out. Delete all authentication references, such as clearing the session to ensure the user has no further access to the application. No parameters. Used together with saml_authenticated to override default session implementation. flask_saml.saml_error Signal sent when an error ocurred. Receives instance of exception thrown when trying to log in user. See Error Handling for more details API 7

12 Flask-SAML Documentation, Release Chapter 2. Advanced Configuration

13 CHAPTER 3 Recipes 3.1 Integration with Flask Principal Flask Principal allows you do manage your user authentication information and permissions. Flask SAML nicely by combining its own signal-based approach with that of Flask Principal. This recipe shows a basic implementation of that. Note: Don t forget to update the metadata URL to your SAML provider or this code won t work. You might also need to update the port parameter depending on your SAML IdP configuration. import flask import flask_principal import flask_saml app = flask.flask( name ) principals = flask_principal.principal(app) app.config.update({ 'SECRET_KEY': 'soverysecret', 'SAML_METADATA_URL': ' }) saml = flask_saml.flasksaml(app) # Create a permission with a single Need, in this case a RoleNeed. admin_permission = flask_principal.permission(flask_principal.roleneed('admin')) # # Connect SAML & Principal def on_saml_authenticated(sender, subject, attributes, auth): # We have a logged in user, inform Flask-Principal (continues on next page) 9

14 Flask-SAML Documentation, Release flask_principal.identity_changed.send( flask.current_app._get_current_object(), identity=get_identity(), ) (continued from previous def on_saml_logout(sender): # Let Flask-Principal know the user is gone flask_principal.identity_changed.send( flask.current_app._get_current_object(), identity=get_identity(), ) # This provides the users' identity in the def get_identity(): if 'saml' in flask.session: return flask_principal.identity(flask.session['saml']['subject']) else: return def on_identity_loaded(sender, identity): # If authenticated, you're an admin - yay! if not isinstance(identity, flask_principal.anonymousidentity): identity.provides.add(flask_principal.roleneed('admin')) # protect a view with a principal for def do_admin_index(): return flask.response('only if you are an admin') # this time protect with a context def do_articles(): with admin_permission.require(): return flask.response('only if you are def handle_permission_denied(error): deny = 'Permission Denied', 403 redirect = flask.redirect(flask.url_for('login', next=flask.request.url)) if isinstance(flask.g.identity, flask_principal.anonymousidentity): return redirect else: return deny if name == ' main ': app.run(port=8000, debug=true) 10 Chapter 3. Recipes

15 CHAPTER 4 Links Source Code: Documentation: Package on PyPI: 11

16 Flask-SAML Documentation, Release Chapter 4. Links

17 Index F FlaskSAML (class in flask_saml), 6 S saml_authenticated (in module flask_saml), 7 saml_error (in module flask_saml), 7 saml_log_out (in module flask_saml), 7 13