Support non-Azure OpenID providers

ISAR validates access tokens against Azure Entra ID, with the discovery
document URL derived from AZURE_TENANT_ID. Add ISAR_OPENID_CONFIG_URL to
read it from anywhere else instead, so ISAR can be pointed at a Keycloak
realm for local development, for the armada integration tests, or for a
deployment outside Azure.

SingleTenantAzureAuthorizationCodeBearer does not accept an
openid_config_url argument, so the base class is used directly when the
override is set. Issuer validation stays enabled either way; the
expected issuer is taken from the discovery document. The scheme is also
extracted into a factory, since a module-level constant built at import
time cannot be tested without reloading the module.

ISAR_OPENID_SCOPE names the scope Swagger requests. Entra derives a
token's audience from the requested scope, which is why the scope was
built as "api://<client id>/user_impersonation". Other providers
decouple the two: a Keycloak scope named "isar-api" yields the audience
"isar-test". Validation is unaffected -- the expected audience is still
AZURE_CLIENT_ID. ISAR_OPENAPI_AUTHORIZATION_URL and ISAR_OPENAPI_TOKEN_URL
likewise keep Swagger's Authorize button off login.microsoftonline.com.

Also pin the audience shapes ISAR accepts. fastapi-azure-auth declares
"aud" as a plain string, so the array form permitted by RFC 7519 is
rejected with an opaque 401 after signature validation succeeds, and
there is no injection point for a different user model. Entra never
emits the array form; other providers can. The constraint is handled
where tokens are minted, and asserted here so that a dependency upgrade
lifting it is noticed rather than silently relied upon.

Document all of this in the README, and correct its claim that
authentication is disabled by default. It has defaulted to enabled since
the setting was introduced.

Author: oysand

README.md

@@ -270,22 +270,51 @@ option in the dictionary.
 
 ## API authentication
 
-The API has an option to include user authentication. This can be enabled by setting the environment variable
+The API validates OAuth2 access tokens. Authentication is controlled by
 
 ```
 ISAR_AUTHENTICATION_ENABLED = true
 ```
 
-By default, the `local` storage module is used and API authentication is disabled. If using Azure Blob Storage a set of
-environment variables must be available which gives access to an app registration that may use the storage account.
-Enabling API authentication also requires the same environment variables. The required variables are
+which is **enabled by default**; set it to `false` to turn authentication off.
+
+A token is accepted when its issuer matches the configured OpenID provider, its audience equals
+`ISAR_AZURE_CLIENT_ID`, its signature and lifetime are valid, and it carries the role named by
+`ISAR_REQUIRED_ROLE` (default `Mission.Control`) in a top-level `roles` claim.
+
+### Azure Entra ID (default)
+
+Requires an app registration, configured through
 
 ```
-AZURE_CLIENT_ID
-AZURE_TENANT_ID
-AZURE_CLIENT_SECRET
+ISAR_AZURE_CLIENT_ID
+ISAR_AZURE_TENANT_ID
 ```
 
+The same app registration is used for Azure Blob Storage, which additionally needs the bare
+`AZURE_CLIENT_ID`, `AZURE_TENANT_ID` and `AZURE_CLIENT_SECRET` variables that
+`EnvironmentCredential` reads.
+
+### Any other OpenID Connect provider
+
+Setting `ISAR_OPENID_CONFIG_URL` points ISAR at a different provider — for example a Keycloak
+realm, whether for local development or for a deployment outside Azure:
+
+```
+ISAR_OPENID_CONFIG_URL = http://localhost:8080/realms/robotics/.well-known/openid-configuration
+ISAR_AZURE_CLIENT_ID   = isar-test          # the expected audience
+ISAR_OPENID_SCOPE      = isar-api           # the scope Swagger requests
+ISAR_OPENAPI_AUTHORIZATION_URL = http://localhost:8080/realms/robotics/protocol/openid-connect/auth
+ISAR_OPENAPI_TOKEN_URL         = http://localhost:8080/realms/robotics/protocol/openid-connect/token
+```
+
+Issuer validation stays enabled; the expected issuer is read from the discovery document. The
+last three variables only affect Swagger's "Authorize" button.
+
+The provider must emit `nbf` and a `ver` claim of `"1.0"` or `"2.0"`, place roles in a flat
+top-level `roles` array, and issue `aud` as a **single string** rather than the array form that
+RFC 7519 also permits.
+
 ## MQTT communication
 
 ISAR is able to publish parts of its internal state to topics on an MQTT broker whenever they change. 

src/isar/apis/security/authentication.py

@@ -4,6 +4,7 @@
 from fastapi import Depends
 from fastapi.security.base import SecurityBase
 from fastapi_azure_auth import SingleTenantAzureAuthorizationCodeBearer
+from fastapi_azure_auth.auth import AzureAuthorizationCodeBearerBase
 from fastapi_azure_auth.exceptions import InvalidAuthHttp
 from fastapi_azure_auth.user import User
 from pydantic import BaseModel
@@ -21,13 +22,55 @@ def __init__(self) -> None:
         self.scheme_name = "No Security"
 
 
-azure_scheme = SingleTenantAzureAuthorizationCodeBearer(
-    app_client_id=settings.AZURE_CLIENT_ID,
-    tenant_id=settings.AZURE_TENANT_ID,
-    scopes={
-        f"api://{settings.AZURE_CLIENT_ID}/user_impersonation": "user_impersonation",
-    },
-)
+def build_azure_scheme() -> AzureAuthorizationCodeBearerBase:
+    """
+    Build the security scheme used to validate access tokens.
+
+    By default this is a single tenant Azure Entra ID scheme. If
+    ``settings.OPENID_CONFIG_URL`` is set, the OpenID Connect discovery document is
+    read from that URL instead, which allows ISAR to be pointed at a different
+    OpenID provider, such as a Keycloak realm used for local development and by the
+    integration tests.
+
+    ``SingleTenantAzureAuthorizationCodeBearer`` does not accept an
+    ``openid_config_url`` argument, so the base class is used directly in that case.
+    Issuer validation remains enabled either way; the expected issuer is taken from
+    the discovery document.
+
+    The expected audience is ``settings.AZURE_CLIENT_ID`` regardless of provider. Note
+    that the *scope* a caller requests need not resemble the audience it yields: Entra
+    derives the audience from the scope, whereas an OpenID provider such as Keycloak
+    maps a freely named scope onto an audience. ``settings.OPENID_SCOPE`` therefore
+    overrides the scope advertised to Swagger without affecting validation.
+
+    Returns
+    -------
+    AzureAuthorizationCodeBearerBase
+        The configured security scheme.
+    """
+    scope_name: str = (
+        settings.OPENID_SCOPE or f"api://{settings.AZURE_CLIENT_ID}/user_impersonation"
+    )
+    scopes: dict[str, str] = {scope_name: scope_name.rsplit("/", maxsplit=1)[-1]}
+
+    if settings.OPENID_CONFIG_URL:
+        return AzureAuthorizationCodeBearerBase(
+            app_client_id=settings.AZURE_CLIENT_ID,
+            tenant_id=settings.AZURE_TENANT_ID,
+            scopes=scopes,
+            openid_config_url=settings.OPENID_CONFIG_URL,
+            openapi_authorization_url=settings.OPENAPI_AUTHORIZATION_URL,
+            openapi_token_url=settings.OPENAPI_TOKEN_URL,
+        )
+
+    return SingleTenantAzureAuthorizationCodeBearer(
+        app_client_id=settings.AZURE_CLIENT_ID,
+        tenant_id=settings.AZURE_TENANT_ID,
+        scopes=scopes,
+    )
+
+
+azure_scheme: AzureAuthorizationCodeBearerBase = build_azure_scheme()
 
 
 async def validate_has_role(user: User = Depends(azure_scheme)) -> None:

src/isar/config/settings.py

@@ -122,6 +122,28 @@ class Settings(BaseSettings):
     # ChainedTokenCredential (e.g. "WorkloadIdentity,ClientSecret").
     ALLOWED_AUTH_METHODS: str = Field(default="ClientSecret")
 
+    # Override the OpenID Connect discovery document URL used to validate access
+    # tokens. When unset (the default), the URL is derived from AZURE_TENANT_ID and
+    # points at Azure Entra ID. Set this to point ISAR at a different OpenID
+    # provider, such as the Keycloak realm used for local development and by the
+    # integration tests.
+    OPENID_CONFIG_URL: str | None = Field(default=None)
+
+    # Override the authorization and token URLs advertised in the generated OpenAPI
+    # document, so that Swagger's "Authorize" button does not point at
+    # login.microsoftonline.com when a non-Azure issuer is configured. Only affect
+    # the API documentation; token validation is governed by OPENID_CONFIG_URL.
+    OPENAPI_AUTHORIZATION_URL: str | None = Field(default=None)
+    OPENAPI_TOKEN_URL: str | None = Field(default=None)
+
+    # Override the scope Swagger requests when authorizing. Entra derives a token's
+    # audience from the requested scope, so the default is the Entra-shaped
+    # "api://<client id>/user_impersonation". Other OpenID providers decouple the
+    # two: a Keycloak scope named "isar-api" may yield the audience "isar-test".
+    # Only affects the API documentation; the expected audience is always
+    # AZURE_CLIENT_ID.
+    OPENID_SCOPE: str | None = Field(default=None)
+
     # MQTT username
     # The username and password is set by the MQTT broker and must be known in advance
     # The password should be set as an environment variable "MQTT_PASSWORD"

tests/isar/apis/security/test_authentication.py

@@ -3,6 +3,19 @@
 import jwt
 import pytest
 from fastapi.testclient import TestClient
+from fastapi_azure_auth import SingleTenantAzureAuthorizationCodeBearer
+from fastapi_azure_auth.auth import AzureAuthorizationCodeBearerBase
+from fastapi_azure_auth.user import User
+from pydantic import ValidationError
+from pytest import MonkeyPatch
+
+from isar.apis.security.authentication import build_azure_scheme
+from isar.config.settings import settings
+
+
+def advertised_scopes(scheme: AzureAuthorizationCodeBearerBase) -> dict[str, str]:
+    """Scopes offered by Swagger's Authorize button, for the given scheme."""
+    return scheme.oauth.model.flows.authorizationCode.scopes
 
 
 def stub_access_token() -> str:
@@ -30,3 +43,128 @@ def test_authentication(
         )
 
         assert response.status_code == expected_status_code
+
+
+class TestBuildAzureScheme:
+    def test_defaults_to_single_tenant_azure_scheme(
+        self, monkeypatch: MonkeyPatch
+    ) -> None:
+        monkeypatch.setattr(settings, "OPENID_CONFIG_URL", None)
+
+        scheme = build_azure_scheme()
+
+        assert isinstance(scheme, SingleTenantAzureAuthorizationCodeBearer)
+        # No override, so the discovery document URL is derived from the tenant ID
+        # and points at Azure Entra ID.
+        assert scheme.openid_config.config_url is None
+        assert scheme.openid_config.tenant_id == settings.AZURE_TENANT_ID
+        assert scheme.app_client_id == settings.AZURE_CLIENT_ID
+
+    def test_openid_config_url_is_honoured(self, monkeypatch: MonkeyPatch) -> None:
+        config_url = (
+            "http://keycloak:8080/realms/robotics/.well-known/openid-configuration"
+        )
+        authorization_url = (
+            "http://keycloak:8080/realms/robotics/protocol/openid-connect/auth"
+        )
+        token_url = "http://keycloak:8080/realms/robotics/protocol/openid-connect/token"
+
+        monkeypatch.setattr(settings, "OPENID_CONFIG_URL", config_url)
+        monkeypatch.setattr(settings, "OPENAPI_AUTHORIZATION_URL", authorization_url)
+        monkeypatch.setattr(settings, "OPENAPI_TOKEN_URL", token_url)
+
+        scheme = build_azure_scheme()
+
+        assert not isinstance(scheme, SingleTenantAzureAuthorizationCodeBearer)
+        assert isinstance(scheme, AzureAuthorizationCodeBearerBase)
+        assert scheme.openid_config.config_url == config_url
+        assert scheme.authorization_url == authorization_url
+        assert scheme.token_url == token_url
+        # The audience is still ISAR's own client ID, and issuer validation stays on.
+        assert scheme.app_client_id == settings.AZURE_CLIENT_ID
+        assert scheme.validate_iss is True
+
+    def test_openapi_urls_fall_back_to_azure_when_unset(
+        self, monkeypatch: MonkeyPatch
+    ) -> None:
+        monkeypatch.setattr(
+            settings,
+            "OPENID_CONFIG_URL",
+            "http://keycloak:8080/realms/robotics/.well-known/openid-configuration",
+        )
+        monkeypatch.setattr(settings, "OPENAPI_AUTHORIZATION_URL", None)
+        monkeypatch.setattr(settings, "OPENAPI_TOKEN_URL", None)
+
+        scheme = build_azure_scheme()
+
+        assert scheme.authorization_url is not None
+        assert settings.AZURE_TENANT_ID in scheme.authorization_url
+
+    def test_scope_defaults_to_the_entra_shaped_scope(
+        self, monkeypatch: MonkeyPatch
+    ) -> None:
+        monkeypatch.setattr(settings, "OPENID_SCOPE", None)
+
+        scheme = build_azure_scheme()
+
+        expected = f"api://{settings.AZURE_CLIENT_ID}/user_impersonation"
+        assert advertised_scopes(scheme) == {expected: "user_impersonation"}
+
+    def test_openid_scope_is_honoured(self, monkeypatch: MonkeyPatch) -> None:
+        # Entra derives a token's audience from the requested scope; Keycloak and
+        # other OpenID providers do not, so the scope must be nameable independently
+        # of AZURE_CLIENT_ID.
+        monkeypatch.setattr(settings, "OPENID_SCOPE", "isar-api")
+
+        scheme = build_azure_scheme()
+
+        assert advertised_scopes(scheme) == {"isar-api": "isar-api"}
+        # Validation is unaffected: the expected audience is still the client ID.
+        assert scheme.app_client_id == settings.AZURE_CLIENT_ID
+
+
+class TestAudienceClaimShape:
+    """Pin the audience shapes ISAR accepts.
+
+    ``fastapi_azure_auth.user.Claims`` declares ``aud`` as a plain ``str``, so a
+    token carrying the array form permitted by RFC 7519 section 4.1.3 is rejected —
+    after signature validation succeeds — with an opaque 401. There is no injection
+    point for a different user model: ``AzureAuthorizationCodeBearerBase.__call__``
+    constructs ``User`` directly.
+
+    Entra never emits the array form, so this has never mattered. Other providers
+    can: Keycloak does so as soon as two audience mappers apply to one token. The
+    constraint is therefore handled where tokens are minted -- exactly one audience
+    mapper per client scope, and never two API scopes in a single token -- and
+    asserted here so that a ``fastapi-azure-auth`` upgrade which lifts the
+    restriction is noticed rather than silently relied upon.
+    """
+
+    def test_string_audience_is_accepted(self) -> None:
+        user = User(
+            aud=settings.AZURE_CLIENT_ID,
+            claims={},
+            access_token="",
+            iss="",
+            sub="",
+            exp=0,
+            iat=0,
+            nbf=0,
+            ver="2.0",
+        )
+
+        assert user.aud == settings.AZURE_CLIENT_ID
+
+    def test_array_audience_is_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            User(
+                aud=[settings.AZURE_CLIENT_ID, "another-audience"],
+                claims={},
+                access_token="",
+                iss="",
+                sub="",
+                exp=0,
+                iat=0,
+                nbf=0,
+                ver="2.0",
+            )