Flask-Principal Documentation

Once you have defined a Permission, you can protect views or specific blocks of code using the .require() method. This method can be used as a decorator for Flask routes or as a context manager within a function.

from flask import Flask, Response
from flask_principal import Principal, Permission, RoleNeed

app = Flask(__name__)
principals = Principal(app)

# Define a permission requiring the 'admin' role
admin_permission = Permission(RoleNeed('admin'))

# Option 1: Protect a view with a decorator
@app.route('/admin')
@admin_permission.require()
def do_admin_index():
    return Response('Only if you are an admin')

# Option 2: Protect a block of code with a context manager
@app.route('/articles')
def do_articles():
    with admin_permission.require():
        return Response('Only if you are admin')

from flask import Flask, Response
from flask_principal import Principal, Permission, RoleNeed

app = Flask(__name__)

# load the extension
principals = Principal(app)

# Create a permission with a single Need, in this case a RoleNeed.
admin_permission = Permission(RoleNeed('admin'))

# protect a view with a principal for that need
@app.route('/admin')
@admin_permission.require()
def do_admin_index():
    return Response('Only if you are an admin')

# this time protect with a context manager
@app.route('/articles')
def do_articles():
    with admin_permission.require():
        return Response('Only if you are admin')

User information providers should connect to the identity-loaded signal. This signal is triggered when an identity is loaded, allowing you to attach additional data (like roles or specific resource permissions) to the identity.provides set.

from flask_principal import identity_loaded, RoleNeed, UserNeed

@identity_loaded.connect_via(app)
def on_identity_loaded(sender, identity):
    # Attach the user object to the identity
    identity.user = current_user

    # Add specific Needs to the identity's 'provides' set
    if hasattr(current_user, 'id'):
        identity.provides.add(UserNeed(current_user.id))

    if hasattr(current_user, 'roles'):
        for role in current_user.roles:
            identity.provides.add(RoleNeed(role.name))

@identity_loaded.connect_via(app)
def on_identity_loaded(sender, identity):
    # Set the identity user object
    identity.user = current_user

    # Add the UserNeed to the identity
    if hasattr(current_user, 'id'):
        identity.provides.add(UserNeed(current_user.id))

    # Assuming the User model has a list of roles, update the
    # identity with the roles that the user provides
    if hasattr(current_user, 'roles'):
        for role in current_user.roles:
            identity.provides.add(RoleNeed(role.name))

For fine-grained access (e.g., 'only the author can edit this post'), create custom Need objects and a Permission class that encapsulates the logic for a specific resource ID. You then populate the identity.provides set during the identity_loaded phase.

1. Define a Need: Use a namedtuple or similar to represent the resource and action.
2. Define a Permission: A class that takes a resource ID and creates the corresponding Need.
3. Populate Identity: In the identity_loaded handler, add the user's specific resource permissions to identity.provides.
4. Check Permission: Use permission.can() in your view logic.

from collections import namedtuple
from flask_principal import identity_loaded, Permission, RoleNeed, UserNeed

# 1. Define the Need
BlogPostNeed = namedtuple('blog_post', ['method', 'value'])
EditBlogPostNeed = partial(BlogPostNeed, 'edit')

# 2. Define the Permission class
class EditBlogPostPermission(Permission):
    def __init__(self, post_id):
        need = EditBlogPostNeed(str(post_id))
        super().__init__(need)

# 3. Populate Identity with user's specific post permissions
@identity_loaded.connect_via(app)
def on_identity_loaded(sender, identity):
    if hasattr(current_user, 'posts'):
        for post in current_user.posts:
            identity.provides.add(EditBlogPostNeed(str(post.id)))

# 4. Use in a view
@app.route('/posts/<post_id>', methods=['PUT', 'PATCH'])
def edit_post(post_id):
    permission = EditBlogPostPermission(post_id)
    if permission.can():
        return render_template('edit_post.html')
    abort(403)

@app.route('/posts/<post_id>', methods=['PUT', 'PATCH'])
def edit_post(post_id):
    permission = EditBlogPostPermission(post_id)

    if permission.can():
        # Save the edits ...
        return render_template('edit_post.html')

    abort(403)  # HTTP Forbidden

Authentication providers should trigger the identity-changed signal to notify Flask-Principal that a user's authentication status has changed. This allows the system to update the current Identity.

• On Login: Send an Identity object containing the user's ID.
• On Logout: Send an AnonymousIdentity object and manually clear any Flask-Principal related keys from the session.

from flask_principal import Identity, AnonymousIdentity, identity_changed

# On successful login
identity_changed.send(current_app._get_current_object(), identity=Identity(user.id))

# On logout
for key in ('identity.name', 'identity.auth_type'):
    session.pop(key, None)
identity_changed.send(current_app._get_current_object(), identity=AnonymousIdentity())

# Tell Flask-Principal the identity changed
identity_changed.send(current_app._get_current_object(),
                        identity=Identity(user.id))

# ... later in logout ...

# Remove session keys set by Flask-Principal
for key in ('identity.name', 'identity.auth_type'):
    session.pop(key, None)

# Tell Flask-Principal the user is anonymous
identity_changed.send(current_app._get_current_object(),
                        identity=AnonymousIdentity())