Advanced Configuration

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 (for example an e-mail) 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.

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 it:

@flask_saml.saml_error.connect_via(app)
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.

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)

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.

API

Extension

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.