Merge branch 'master' into update_azure_oauth

Author: sfirke

.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
     runs-on: ubuntu-22.04
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     env:
       SQLALCHEMY_DATABASE_URI:
         postgresql+psycopg2://pguser:pguserpassword@127.0.0.1:15432/app
@@ -141,7 +141,7 @@ jobs:
     runs-on: ubuntu-22.04
     strategy:
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.10", "3.13"]
     env:
       SQLALCHEMY_DATABASE_URI: |
         mysql+mysqldb://mysqluser:mysqluserpassword@127.0.0.1:13306/app?charset=utf8mb4&binary_prefix=true
@@ -192,7 +192,7 @@ jobs:
     runs-on: ubuntu-22.04
     strategy:
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.10", "3.13"]
     env:
       SQLALCHEMY_DATABASE_URI: |
         mssql+pyodbc://sa:Password_123@localhost:11433/master?driver=FreeTDS

CHANGELOG.rst

@@ -1,6 +1,19 @@
 Flask-AppBuilder ChangeLog
 ==========================
 
+Improvements and Bug fixes on 5.2.0
+-----------------------------------
+
+- feat: add API key authentication support (#2431) [Amin Ghadersohi]
+- ci: add py3.13 to the test matrix (#2419) [jnahmias]
+- feat: Add security model signals for User, Role, and Group CRUD operations (#2432) [Daniel Vaz Gaspar]
+
+Improvements and Bug fixes on 5.1.0
+-----------------------------------
+
+- feat: SAML Authentication (#2426) [Daniel Vaz Gaspar]
+- fix: update user.changed_on when roles are modified (#2423) [alok kumar priyadarshi]
+
 Improvements and Bug fixes on 5.0.2
 -----------------------------------
 

docs/rest_api.rst

@@ -517,6 +517,28 @@ methods::
     class ExampleApi(BaseApi):
         base_permissions = ['can_private']
 
+API Key Authentication
+~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to JWT tokens, FAB supports API key authentication. API keys are long-lived
+Bearer tokens useful for service-to-service communication or automation scripts.
+
+To enable API key authentication, set ``FAB_API_KEY_ENABLED = True`` in your config.
+
+Once enabled, you can use an API key in the same way as a JWT token::
+
+    $ curl http://localhost:8080/api/v1/example/private \
+      -H "Authorization: Bearer sst_<YOUR_API_KEY>"
+
+API keys are distinguished from JWT tokens by their prefix (default: ``sst_``). When the
+``protect()`` decorator receives a request with an API key:
+
+- If the key is **invalid**, the endpoint returns HTTP **401 Unauthorized**.
+- If the key is valid but the user **lacks permission**, the endpoint returns HTTP **403 Forbidden**.
+- If the key is valid and the user **has permission**, the request proceeds normally.
+
+The OpenAPI spec for protected endpoints lists both ``jwt`` and ``api_key`` as valid security
+schemes, so clients can choose either authentication method.
 
 You can create an alternate JWT user loader, this can be useful if you want
 to use an external Authentication provider and map the JWT identity to your

docs/security.rst

@@ -16,6 +16,7 @@ Supported Authentication Types
        It's the web server responsibility to authenticate the user, useful for intranet sites, when the server (Apache, Nginx)
        is configured to use kerberos, no need for the user to login with username and password on F.A.B.
 :OAUTH: Authentication using OAUTH (v1 or v2). You need to install authlib.
+:SAML: Authentication using SAML 2.0 (e.g., Microsoft Entra ID, Okta, OneLogin). You need to install python3-saml.
 
 .. note::
    **Deprecated Authentication Types (Removed in Flask-AppBuilder 5.0+)**
@@ -31,15 +32,16 @@ The session is preserved and encrypted using Flask-Login.
 Authentication Methods
 ----------------------
 
-You can choose one from 4 authentication methods. Configure the method to be used
+You can choose one from 5 authentication methods. Configure the method to be used
 on the **config.py** (when using the create-app, or following the proposed app structure). First the
 configuration imports the constants for the authentication methods::
 
     from flask_appbuilder.security.manager import (
         AUTH_DB,
         AUTH_LDAP,
         AUTH_OAUTH,
-        AUTH_REMOTE_USER
+        AUTH_REMOTE_USER,
+        AUTH_SAML,
     )
 
 Next you will use the **AUTH_TYPE** key to choose the type::
@@ -438,6 +440,138 @@ Therefore, you can send tweets, post on the users Facebook, retrieve the user's
 Take a look at the `example <https://github.com/dpgaspar/Flask-AppBuilder/tree/master/examples/oauth>`_
 to get an idea of a simple use for this.
 
+Authentication: SAML
+--------------------
+
+This method will authenticate users via SAML 2.0 identity providers such as
+Microsoft Entra ID (formerly Azure AD), Okta, OneLogin, etc.
+
+.. note:: To use SAML you need to install `python3-saml <https://github.com/SAML-Toolkits/python3-saml>`_:
+   ``pip install flask-appbuilder[saml]``
+
+Configure your SAML providers and SP settings in **config.py**::
+
+    AUTH_TYPE = AUTH_SAML
+
+    # registration configs
+    AUTH_USER_REGISTRATION = True
+    AUTH_USER_REGISTRATION_ROLE = "Public"
+
+    # Sync roles at login from SAML assertion
+    AUTH_ROLES_SYNC_AT_LOGIN = True
+
+    # Map SAML group names to FAB roles
+    AUTH_ROLES_MAPPING = {
+        "admins": ["Admin"],
+        "users": ["Public"],
+    }
+
+    # SAML Identity Providers
+    SAML_PROVIDERS = [
+        {
+            "name": "entra_id",
+            "icon": "fa-microsoft",
+            "idp": {
+                "entityId": "https://sts.windows.net/<TENANT_ID>/",
+                "singleSignOnService": {
+                    "url": "https://login.microsoftonline.com/<TENANT_ID>/saml2",
+                    "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
+                },
+                "singleLogoutService": {
+                    "url": "https://login.microsoftonline.com/<TENANT_ID>/saml2",
+                    "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
+                },
+                "x509cert": "<IDP_CERTIFICATE_BASE64>",
+            },
+            "attribute_mapping": {
+                "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "email",
+                "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname": "first_name",
+                "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname": "last_name",
+                "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name": "username",
+                "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups": "role_keys",
+            },
+        },
+    ]
+
+    # Global SAML Service Provider configuration
+    SAML_CONFIG = {
+        "strict": True,
+        "debug": False,
+        "sp": {
+            "entityId": "https://myapp.example.com/saml/metadata/",
+            "assertionConsumerService": {
+                "url": "https://myapp.example.com/saml/acs/",
+                "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
+            },
+            "singleLogoutService": {
+                "url": "https://myapp.example.com/saml/slo/",
+                "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
+            },
+            "NameIDFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+            "x509cert": "",
+            # "privateKey": "",
+        },
+        "security": {
+            "nameIdEncrypted": False,
+            "authnRequestsSigned": False,
+            "logoutRequestSigned": False,
+            "logoutResponseSigned": False,
+            "signMetadata": False,
+            "wantMessagesSigned": False,
+            "wantAssertionsSigned": True,
+            "wantAssertionsEncrypted": False,
+            "wantNameId": True,
+            "wantNameIdEncrypted": False,
+            "wantAttributeStatement": True,
+        },
+    }
+
+Each SAML provider entry has the following keys:
+
+:name: A unique name for the identity provider.
+:icon: A Font Awesome icon class for the login button.
+:idp: The IdP SAML metadata (entityId, SSO/SLO URLs, and signing certificate).
+:attribute_mapping: Maps SAML assertion attribute names (left) to FAB user fields (right).
+    Supported FAB fields: ``username``, ``email``, ``first_name``, ``last_name``, ``role_keys``.
+
+The ``SAML_CONFIG`` dict holds the global Service Provider settings. The ``sp`` section defines
+your application's SAML endpoints. These URLs must match what you configure on the IdP side.
+
+SAML Endpoints
+~~~~~~~~~~~~~~
+
+The following endpoints are automatically registered:
+
+- ``/login/`` — Login page with IdP selection (or auto-redirect for single IdP)
+- ``/login/<idp>`` — Initiate SSO with a specific IdP
+- ``/saml/acs/`` — Assertion Consumer Service (receives SAML responses)
+- ``/saml/slo/`` — Single Logout endpoint
+- ``/saml/metadata/`` — SP metadata XML (configure this URL on your IdP)
+
+SAML Role Mapping
+~~~~~~~~~~~~~~~~~
+
+You can map SAML group claims to FAB roles, just like with OAuth and LDAP::
+
+    AUTH_ROLES_MAPPING = {
+        "admins": ["Admin"],
+        "users": ["User"],
+    }
+
+    AUTH_ROLES_SYNC_AT_LOGIN = True
+
+    PERMANENT_SESSION_LIFETIME = 1800
+
+The ``role_keys`` field in ``attribute_mapping`` defines which SAML attribute contains the
+user's group memberships.
+
+You can also use JMESPath expressions for dynamic role assignment::
+
+    AUTH_USER_REGISTRATION_ROLE_JMESPATH = "role_keys[0]"
+
+Take a look at the `SAML example <https://github.com/dpgaspar/Flask-AppBuilder/tree/master/examples/saml>`_
+
+
 Authentication: Rate limiting
 -----------------------------
 
@@ -448,6 +582,47 @@ The rate can be changed by adjusting ``AUTH_RATE_LIMIT`` to, for example, ``1 pe
 at the `documentation <https://flask-limiter.readthedocs.io/en/stable/>`_ of Flask-Limiter for more options and
 examples.
 
+Authentication: API Keys
+------------------------
+
+FAB supports API key authentication as an alternative to JWT tokens. API keys are long-lived
+credentials that can be used for service-to-service communication or automation.
+
+**Enabling API Key Authentication**
+
+Set the following in your config::
+
+    FAB_API_KEY_ENABLED = True
+
+**Creating API Keys**
+
+API keys are managed through the ``SecurityManager``. You can create keys programmatically::
+
+    from flask import current_app
+
+    sm = current_app.appbuilder.sm
+    api_key = sm.create_api_key(user=user, name="my-service-key")
+
+The returned key string should be stored securely -- it cannot be retrieved again after creation.
+
+**Using API Keys**
+
+Pass the API key as a Bearer token in the ``Authorization`` header::
+
+    $ curl http://localhost:8080/api/v1/example/private \
+      -H "Authorization: Bearer sst_<YOUR_API_KEY>"
+
+API keys use the same permission system as regular users. The key inherits the roles and
+permissions of the user it belongs to.
+
+**Configuration Options**
+
+The following configuration options are available:
+
+- ``FAB_API_KEY_ENABLED`` -- Set to ``True`` to enable API key authentication (default: ``False``).
+- ``FAB_API_KEY_PREFIXES`` -- List of prefixes that identify API keys vs JWT tokens
+  (default: ``["sst_"]``).
+
 Role based
 ----------
 
@@ -849,6 +1024,9 @@ F.A.B. uses a different user view for each authentication method
 
 :UserDBModelView: For database auth method
 :UserLDAPModelView: For LDAP auth method
+:UserOAuthModelView: For OAuth auth method
+:UserRemoteUserModelView: For Remote User auth method
+:UserSAMLModelView: For SAML auth method
 
 You can extend or create from scratch your own, and then tell F.A.B. to use them instead, by overriding their
 correspondent lower case properties on **SecurityManager** (just like on the given example).
@@ -882,6 +1060,7 @@ If you're using:
 :AUTH_LDAP: Extend UserLDAPModelView
 :AUTH_REMOTE_USER: Extend UserRemoteUserModelView
 :AUTH_OAUTH: Extend UserOAuthModelView
+:AUTH_SAML: Extend UserSAMLModelView
 
 So using AUTH_DB::
 
@@ -956,6 +1135,8 @@ Note that this is for AUTH_DB, so if you're using:
 :AUTH_DB: Override userdbmodelview
 :AUTH_LDAP: Override userldapmodelview
 :AUTH_REMOTE_USER: Override userremoteusermodelview
+:AUTH_OAUTH: Override useroauthmodelview
+:AUTH_SAML: Override usersamlmodelview
 
 Finally (as shown on the previous example) tell F.A.B. to use your SecurityManager class, so when initializing
 **AppBuilder** (on __init__.py)::

examples/saml/app.py

@@ -0,0 +1,8 @@
+"""Example Flask-AppBuilder application with SAML / Entra ID authentication."""
+
+from app import create_app
+
+app = create_app()
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=5000, debug=True)

examples/saml/app/__init__.py

@@ -0,0 +1,19 @@
+import logging
+
+from flask import Flask
+
+from .extensions import appbuilder, db
+
+
+logging.basicConfig(format="%(asctime)s:%(levelname)s:%(name)s:%(message)s")
+logging.getLogger().setLevel(logging.INFO)
+
+
+def create_app() -> Flask:
+    app = Flask(__name__)
+    app.config.from_object("config")
+    with app.app_context():
+        db.init_app(app)
+        appbuilder.init_app(app, db.session)
+        db.create_all()
+    return app

examples/saml/app/extensions.py

@@ -0,0 +1,5 @@
+from flask_appbuilder import AppBuilder
+from flask_appbuilder.utils.legacy import get_sqla_class
+
+db = get_sqla_class()()
+appbuilder = AppBuilder()