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.
- The login signal: Once a user successfully authenticated, the extension
sends the user data over via the
saml_authenticated
signal. - 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
andauth
.auth
is the actualsaml.response.AuthnResponse
from which bothsubject
andattributes
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.