.. SPDX-FileCopyrightText: 2024 Univention GmbH .. .. SPDX-License-Identifier: AGPL-3.0-only .. _component-identity-provider: Identity Provider ================= This section gives an overview of the *Identity Provider* in Univention Nubus for Kubernetes, its functions, components, and their relationships to each other. .. seealso:: :ref:`interfaces-identity-provider` in interfaces and protocols section for information about incoming and outgoing interfaces. :ref:`deployment-identity-provider` in deployment view section for information about Docker images, Kubernetes pods, and Helm Charts used for deployment. :ref:`overview-components-identity-provider` in the components overview section for information about purpose and tasks. Wikipedia: `Identity Provider `_ for general information about the term *Identity Provider*. .. _component-identity-provider-sso: Single sign-on / single sign-out -------------------------------- This section describes the parts that the *Identity Provider* provides for single sign-on and single sign-out functionality. :numref:`component-identity-provider-sso-figure` gives an overview of the single sign-on and single sign-out components and their relationships. .. _component-identity-provider-sso-figure: .. figure:: /images/Functional_component_Identity_Provider_SSO.* :target: ../_images/Functional_component_Identity_Provider_SSO.svg :alt: Keycloak as part of Identity Provider offers single sign-on / sign-out :width: 500px Keycloak as part of the *Identity Provider* provides single sign-on / sign-out *Keycloak* manages the single sign-on (SSO) service, represented by the *Single Sign-On / Single Sign-Out* ArchiMate application service. From an architectural perspective, this service contains the implementation in Keycloak that's responsible for supporting single sign-on. It also provides the following specializations: * *Single Sign-On / Sign-Out through SAML* * *Single Sign-On / Sign-Out through OpenID Connect* The specializations are responsible for the :term:`SAML` and :term:`OpenID Connect` ArchiMate application interfaces, which you can also find in the :ref:`interfaces-external-perspective` section and the :ref:`interfaces-identity-provider` section. They provide the behavior behind the interfaces and handle the authentication requests within Keycloak. :numref:`component-identity-provider-sso-servings-figure` shows which application components use single sign-on. Within Nubus for Kubernetes, the following functional components use single sign-on: * *Portal Service* uses SAML. * *Intercom Service* and *Authorization Service* use OpenID Connect. * *Authorization Service* uses OAuth 2.0. In addition, any third-party application that isn't part of Nubus for Kubernetes can also use any of the single sign-on implementations supported by Keycloak. .. _component-identity-provider-sso-servings-figure: .. figure:: /images/Functional_component_Identity_Provider_SSO_servings.* :target: ../_images/Functional_component_Identity_Provider_SSO_servings.svg :alt: Application components that use single sign-on provided by Keycloak Application components that use single sign-on provided by Keycloak .. seealso:: `SSO protocols `_ in :cite:t:`keycloak-latest` for information about the SSO protocols supported by Keycloak. .. _component-identity-provider-identity-store: Identity Store -------------- *Keycloak* federates an OpenLDAP server as identity store. The *Identity Store and Directory Service* functional component provides such an LDAP server. It's also part of Nubus for Kubernetes. :numref:`component-identity-provider-identity-store-figure` shows the relationship between *Keycloak* using LDAP as storage for identity data. Keycloak retrieves identities from the *Identity Store and Directory Service* through LDAP and caches them in its own database. Keycloak doesn't store the identities and merely accesses them through LDAP. For more information about the *Identity Store and Directory Service*, see :ref:`overview-components-identity-store`. .. _component-identity-provider-identity-store-figure: .. figure:: /images/Functional_component_Identity_Provider_identity_store.* :target: ../_images/Functional_component_Identity_Provider_identity_store.svg :alt: The Identity Provider uses the Identity Store and Directory Manager as storage for identity data. :width: 650px The *Identity Provider* uses the *Identity Store and Directory Manager* as storage for identity data. .. _component-identity-provider-keycloak-extensions: Keycloak Extensions ------------------- The *Keycloak Extensions* belong to the *Identity Provider*. They're a preview feature and activated in Nubus for Kubernetes by default. They enhance Keycloak with additional functionality required by Nubus for Kubernetes. The *Keycloak Extensions* consist of the following application components: * *Keycloak Proxy* * *Keycloak Handler* Together, they provide the following functionality: * Brute force protection * New device notification The following sections describe the functionality in detail. .. seealso:: :external+uv-nubus-kubernetes-operation:ref:`conf-keycloak-extensions` in :cite:t:`uv-nubus-kubernetes-operation` for information about how to deactivate features from the *Keycloak Extensions*. .. _component-identity-provider-keycloak-extensions-brute-force-protection: Brute force protection ~~~~~~~~~~~~~~~~~~~~~~ Brute force protection implements measures to prevent unauthorized users from gaining access to Nubus. The *Keycloak Extensions* identify a client by its IP address and fingerprint. They record unsuccessful sign-in attempts. After a configurable number of sign-in attempts, a captcha appears on the user sign-in page. After further unsuccessful sign-in attempts by the client, the *Keycloak Extensions* add the IP address and the fingerprint to a block list and block further sign-in attempts for a configurable period of time. Keycloak has a feature for brute force protection. However, it doesn't consider a client's IP address or a browser fingerprint, only the username. This means that attackers could try password combinations and lock an account. And the legitimate user can't sign in then, because of the locked account. Brute force protection in Nubus prevents this behavior. :numref:`component-identity-provider-keycloak-extensions-brute-force-protection-figure` shows how *Keycloak Proxy* and *Keycloak Handler* contribute functionality to the brute force protection. The *Keycloak Proxy* forwards the HTTP requests. .. _component-identity-provider-keycloak-extensions-brute-force-protection-figure: .. figure:: /images/Functional_component_Identity_Provider_Keycloak_extensions_Brute_Force_Protection.* :target: ../_images/Functional_component_Identity_Provider_Keycloak_extensions_Brute_Force_Protection.svg :alt: Brute force protection functionality provided by the Keycloak Extensions Brute force protection functionality provided by the *Keycloak Extensions* The following list shows the specific purpose of each concept in the figure: Monitor Keycloak log for sign-in attempts It streams the Keycloak log file that records the sign-in attempts. It decides when a client meets the conditions of the sign-in block list. Maintain sign-in block list It adds and prunes entries to the sign-in block list using the *TCP to SQL database* application interface. The *Sign-in block list* data object is the data exchange element to the functionality in the *Keycloak Proxy*. Monitor for previous failed sign-in attempts It reads the block list and decides when the JavaScript fingerprint and the captcha appear on the sign-in page. Captcha and Fingerprint injection to sign-form It's the main behavioral part of the *Keycloak Proxy*. During HTTP request forwarding, it validates, if a client is on the block list. Then, depending on the settings, it injects the JavaScript fingerprint or a captcha into the sign-in form. Or it blocks the client's access altogether. User sign-in page Keycloak is responsible for delivering a sign-in page to the user. Depending on the *Brute Force Protection* status, this page may have extensions as described before. The database section in :numref:`component-identity-provider-keycloak-extensions-brute-force-protection-figure` shows the role of the database for the brute force protection. In :program:`PostgreSQL`, there's a dedicated database for the *Keycloak Extensions*. And this database has a table for the sign-in block list that realizes the *Sign-in block list* data object. .. _component-identity-provider-keycloak-extensions-new-device-notification: New device notification ~~~~~~~~~~~~~~~~~~~~~~~ When a user signs in through the sign-in page, the *Identity Provider* identifies clients based on their IP address and browser fingerprint. *Keycloak* records successful sign-ins. If a user signs in from a device unknown to the *Identity Provider*, the *Identity Provider* notifies the user with an email and sends the notification to the email address defined in the user account. :numref:`component-identity-provider-keycloak-extensions-new-device-notification-figure` shows how *Keycloak Proxy* and *Keycloak Handler* contribute functionality to the new device notification. .. _component-identity-provider-keycloak-extensions-new-device-notification-figure: .. figure:: /images/Functional_component_Identity_Provider_Keycloak_extensions_New_Device_Notification.* :target: ../_images/Functional_component_Identity_Provider_Keycloak_extensions_New_Device_Notification.svg :alt: New device notification functionality provided by the Keycloak Extensions New device notification functionality provided by the *Keycloak Extensions* The following list shows the specific purpose of each ArchiMate concept in the figure: Track sign-in attempts Based on the browser fingerprint and the IP address, the *Keycloak Proxy* tracks sign-in attempts. It uses the *Device Fingerprints* data object to store known device fingerprints. New Device Notification It reads the known device fingerprints from the *Device Fingerprints* data object and compares them to the fingerprint of the sign-in process. If the fingerprint is unknown, the *Keycloak Handler* triggers the email notification using *Send notification email to user*. Send notification email to user It sends a notification email to the user's email address, informing them of a successful sign-in from an unknown device. The database section in :numref:`component-identity-provider-keycloak-extensions-new-device-notification-figure` shows the role of the database for the new device notification. In :program:`PostgreSQL`, there's a dedicated database for the *Keycloak Extensions*. And this database has a table for the device fingerprints which realizes the *Device Fingerprints* data object.