From a9b9876820344b0b1cd9630d859900b5fc37e3ba Mon Sep 17 00:00:00 2001 From: cs4alhaider Date: Sat, 9 Nov 2024 22:01:53 +0300 Subject: [PATCH 1/4] Clarify OpenID base URL usage in Docker environments --- fastapi_keycloak_middleware/setup.py | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/fastapi_keycloak_middleware/setup.py b/fastapi_keycloak_middleware/setup.py index 3926947..547ddb3 100644 --- a/fastapi_keycloak_middleware/setup.py +++ b/fastapi_keycloak_middleware/setup.py @@ -30,6 +30,7 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments | None = None, add_exception_response: bool = True, add_swagger_auth: bool = False, + openId_base_url: str | None = None, swagger_auth_scopes: typing.List[str] | None = None, swagger_auth_pkce: bool = True, swagger_scheme_name: str = "keycloak-openid", @@ -66,6 +67,22 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments :param add_swagger_auth: Whether to add OpenID Connect authentication to the OpenAPI schema. Defaults to False. :type add_swagger_auth: bool, optional + :param openId_base_url: Base URL for the OpenID Connect configuration that will be used + by the Swagger UI. This parameter allows you to specify a different base URL than + the one in keycloak_configuration.url. This is particularly useful in Docker + container scenarios where the internal and external URLs differ. + + For example, inside a Docker container network, Keycloak's OpenID configuration + endpoint might be available at: + http://host.docker.internal:8080/auth/realms/master/.well-known/openid-configuration + + However, external clients like Swagger UI cannot resolve host.docker.internal. + In this case, you would set: + - keycloak_configuration.url = "http://host.docker.internal:8080" (for internal communication) + - openId_base_url = "http://localhost:8080" (for Swagger UI access) + + If not specified, defaults to using keycloak_configuration.url. + :type openId_base_url: str, optional :param swagger_auth_scopes: Scopes to use for the Swagger UI authentication. Defaults to ['openid', 'profile']. :type swagger_auth_scopes: typing.List[str], optional @@ -117,7 +134,7 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments if add_swagger_auth: suffix = "/.well-known/openid-configuration" security_scheme = OpenIdConnect( - openIdConnectUrl=f"{keycloak_configuration.url}realms/{keycloak_configuration.realm}{suffix}", + openIdConnectUrl=f"{openId_base_url or keycloak_configuration.url}/realms/{keycloak_configuration.realm}{suffix}", scheme_name=swagger_scheme_name, auto_error=False, ) From d3392dc4becd2be94a30318056bd9fbbf2c9d75d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 9 Nov 2024 19:19:39 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- fastapi_keycloak_middleware/setup.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/fastapi_keycloak_middleware/setup.py b/fastapi_keycloak_middleware/setup.py index 547ddb3..fed5e7d 100644 --- a/fastapi_keycloak_middleware/setup.py +++ b/fastapi_keycloak_middleware/setup.py @@ -67,22 +67,22 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments :param add_swagger_auth: Whether to add OpenID Connect authentication to the OpenAPI schema. Defaults to False. :type add_swagger_auth: bool, optional - :param openId_base_url: Base URL for the OpenID Connect configuration that will be used - by the Swagger UI. This parameter allows you to specify a different base URL than - the one in keycloak_configuration.url. This is particularly useful in Docker + :param openId_base_url: Base URL for the OpenID Connect configuration that will be used + by the Swagger UI. This parameter allows you to specify a different base URL than + the one in keycloak_configuration.url. This is particularly useful in Docker container scenarios where the internal and external URLs differ. - For example, inside a Docker container network, Keycloak's OpenID configuration + For example, inside a Docker container network, Keycloak's OpenID configuration endpoint might be available at: http://host.docker.internal:8080/auth/realms/master/.well-known/openid-configuration - However, external clients like Swagger UI cannot resolve host.docker.internal. + However, external clients like Swagger UI cannot resolve host.docker.internal. In this case, you would set: - keycloak_configuration.url = "http://host.docker.internal:8080" (for internal communication) - openId_base_url = "http://localhost:8080" (for Swagger UI access) If not specified, defaults to using keycloak_configuration.url. - :type openId_base_url: str, optional + :type openId_base_url: str, optional :param swagger_auth_scopes: Scopes to use for the Swagger UI authentication. Defaults to ['openid', 'profile']. :type swagger_auth_scopes: typing.List[str], optional From 96278225eb17eb691cd207b68a50ea4e03781f78 Mon Sep 17 00:00:00 2001 From: cs4alhaider Date: Sat, 9 Nov 2024 22:36:20 +0300 Subject: [PATCH 3/4] adding docs --- docs/usage.rst | 3 ++- fastapi_keycloak_middleware/setup.py | 17 ++++++++++------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index ea66300..917e4ae 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -220,8 +220,9 @@ separate client is then configured using the :code:`swagger_client_id` paramete add_swagger_auth=True ) -There are three more parameters that can be used to customize the Swagger UI integration: +There are four more parameters that can be used to customize the Swagger UI integration: +* :code:`swagger_openId_base_url` - The base URL for the OpenID Connect configuration that will be used by the Swagger UI. It is explained in this :issue:`65`. This parameter allows you to specify a different base URL than the one in keycloak_configuration.url. This is particularly useful in Docker container scenarios where the internal and external URLs differ. Defaults to using the keycloak_configuration.url. * :code:`swagger_auth_scopes` - The scopes that should be selected by default when hitting the Authorize button in Swagger UI. Defaults to :code:`['openid', 'profile']` * :code:`swagger_auth_pkce` - Whether to use PKCE for the Swagger UI client. Defaults to :code:`True`. It is recommended to use Authorization Code Flow with PKCE for public clients instead of implicit flow. In Keycloak, this flow is called "Standard flow" * :code:`swagger_scheme_name` - The name of the OpenAPI security scheme. Usually there is no need to change this. diff --git a/fastapi_keycloak_middleware/setup.py b/fastapi_keycloak_middleware/setup.py index 547ddb3..97740f4 100644 --- a/fastapi_keycloak_middleware/setup.py +++ b/fastapi_keycloak_middleware/setup.py @@ -30,7 +30,7 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments | None = None, add_exception_response: bool = True, add_swagger_auth: bool = False, - openId_base_url: str | None = None, + swagger_openId_base_url: str | None = None, swagger_auth_scopes: typing.List[str] | None = None, swagger_auth_pkce: bool = True, swagger_scheme_name: str = "keycloak-openid", @@ -67,7 +67,7 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments :param add_swagger_auth: Whether to add OpenID Connect authentication to the OpenAPI schema. Defaults to False. :type add_swagger_auth: bool, optional - :param openId_base_url: Base URL for the OpenID Connect configuration that will be used + :param swagger_openId_base_url: Base URL for the OpenID Connect configuration that will be used by the Swagger UI. This parameter allows you to specify a different base URL than the one in keycloak_configuration.url. This is particularly useful in Docker container scenarios where the internal and external URLs differ. @@ -78,11 +78,13 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments However, external clients like Swagger UI cannot resolve host.docker.internal. In this case, you would set: - - keycloak_configuration.url = "http://host.docker.internal:8080" (for internal communication) - - openId_base_url = "http://localhost:8080" (for Swagger UI access) + - keycloak_configuration.url: + -- "http://host.docker.internal:8080" (for internal communication) + - swagger_openId_base_url: + -- "http://localhost:8080" (for Swagger UI access) If not specified, defaults to using keycloak_configuration.url. - :type openId_base_url: str, optional + :type swagger_openId_base_url: str, optional :param swagger_auth_scopes: Scopes to use for the Swagger UI authentication. Defaults to ['openid', 'profile']. :type swagger_auth_scopes: typing.List[str], optional @@ -132,9 +134,10 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments # Add OpenAPI schema if add_swagger_auth: - suffix = "/.well-known/openid-configuration" + suffix = ".well-known/openid-configuration" + openId_base_url = swagger_openId_base_url or keycloak_configuration.url security_scheme = OpenIdConnect( - openIdConnectUrl=f"{openId_base_url or keycloak_configuration.url}/realms/{keycloak_configuration.realm}{suffix}", + openIdConnectUrl=f"{openId_base_url}/realms/{keycloak_configuration.realm}/{suffix}", scheme_name=swagger_scheme_name, auto_error=False, ) From e5c5768cff7e25cd2388845610798591632d2a92 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 9 Nov 2024 19:38:54 +0000 Subject: [PATCH 4/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- fastapi_keycloak_middleware/setup.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/fastapi_keycloak_middleware/setup.py b/fastapi_keycloak_middleware/setup.py index 5174b7c..c68912d 100644 --- a/fastapi_keycloak_middleware/setup.py +++ b/fastapi_keycloak_middleware/setup.py @@ -67,9 +67,9 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments :param add_swagger_auth: Whether to add OpenID Connect authentication to the OpenAPI schema. Defaults to False. :type add_swagger_auth: bool, optional - :param swagger_openId_base_url: Base URL for the OpenID Connect configuration that will be used - by the Swagger UI. This parameter allows you to specify a different base URL than - the one in keycloak_configuration.url. This is particularly useful in Docker + :param swagger_openId_base_url: Base URL for the OpenID Connect configuration that will be used + by the Swagger UI. This parameter allows you to specify a different base URL than + the one in keycloak_configuration.url. This is particularly useful in Docker container scenarios where the internal and external URLs differ. For example, inside a Docker container network, Keycloak's OpenID configuration @@ -78,13 +78,13 @@ def setup_keycloak_middleware( # pylint: disable=too-many-arguments However, external clients like Swagger UI cannot resolve host.docker.internal. In this case, you would set: - - keycloak_configuration.url: + - keycloak_configuration.url: -- "http://host.docker.internal:8080" (for internal communication) - - swagger_openId_base_url: + - swagger_openId_base_url: -- "http://localhost:8080" (for Swagger UI access) If not specified, defaults to using keycloak_configuration.url. - :type swagger_openId_base_url: str, optional + :type swagger_openId_base_url: str, optional :param swagger_auth_scopes: Scopes to use for the Swagger UI authentication. Defaults to ['openid', 'profile']. :type swagger_auth_scopes: typing.List[str], optional