OpenID Authentication ====================== Kasm can utilize external authentication providers using OpenID Connect (OIDC). .. warning:: Be mindful when configuring OpenID providers that may configurations that are open to the general public (e.g Google, Github). Any user that can successfully auth with the provider, will have access to the Kasm application. .. image:: /images/oidc/login.png Configuration ------------- OpenID configuration can be found under the Authentication tab in the Admin Navigation Bar. .. table:: :widths: 100 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Property** | **Description** | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Display Name** | This name is displayed on the login page to represent the authentication provider. (e.g :code:`Continue with Github`) | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Logo URL** | A URL to a login logo image for the authentication provider. (e.g :code:`https://github.com/favicon.ico`) | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Enabled** | When checked this configuration will be active. | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Auto Login** | When checked, the user will be automatically navigated to the OIDC provider when they view the login screen. This only applies if a single authentication provider is visible. If this configuration is set, the fixed login page (without redirection) can be accessed via :code:`/#/staticlogin` | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Hostname** | The URL hostname (e.g kasm.example.com) of the deployment. This OIDC config will only be displayed when the deployment is accessed via this URL host name. This allows for a single deployment to service multiple tenants who may need different OIDC configurations. If Default is defined, this config will apply regardless of the host name. | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Default** | If checked this OIDC config will be shown on the login screen of the deployment when access with any hostname, unless another config is defined with the specific hostname. | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Client ID** | The Client ID received from the authentication provider. | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Client Secret** | The Client Secret received from the authentication provider. | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Authorization URL** | The authorization url for the authentication provider. (e.g :code:`https://github.com/login/oauth/authorize`) | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Token URL** | The token url for the authentication provider. (e.g :code:`https://github.com/login/oauth/access_token`) | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **User Info URL** | The user info url for the authentication provider. (e.g :code:`https://api.github.com/user`). This service will be queried if the **Username Attribute** or **Groups Attribute** are no provided by the identity provider in the id or access tokens. | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Scope** | The OIDC Scopes for the authentication provider. Enter one scope per line. e.g: | | | :code:`openid` | | | :code:`email` | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Username Attribute** | The attribute from the authentication provider to use for the username within Kasm (e.g :code:`email`). The system will search the access_token, id_token and user_info api for this property. | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Groups Attribute** | The attribute from the authentication provider to user for group membership mapping within Kasm (e.g :code:`groups`). The system will search the access_token, id_token and user_info api for this property. This field is optional, but if defined, authentication will fail if the group attribute is not found. | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Debug** | When checked, the OIDC access and id tokens are logged as well as the response from the user_info api if queried. TLS Verification is disabled for the Authorization URL, Token URL, and URL Info URL API interactions. This feature should remain disabled unless needed for troubleshooting. | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Redirect URL** | The identify provider can be configured to allow access to redirect to this URL. :code:`https:///api/oidc_callback` | +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. note:: A non redirecting login page is at https://hostname/#/staticlogin when auto login is enabled. Group Assignment ---------------- Users that auth via OIDC, can automatically be associated with Groups defined in Kasm. To automatically assign groups: #. In the OpenID Authentication configuration, ensure the **Groups Attribute** is defined. #. Navigate to the Groups tab in the admin navigation bar #. Using the three dot menu select **View** of the desired group #. Scroll to the bottom of the screen and select **Add SSO Mapping**. #. Select the OpenID IDP for example "OpenID - test_oidc" for the **SSO Provider**. #. Enter the group name used in the identity provider (e.g :code:`sales`) in the OpenID Group Name field .. figure:: /images/oidc/add_sso_group_mapping.png :scale: 50% **Add SSO Group Mapping** Configuration Examples ---------------------- .. toctree:: :maxdepth: 1 oidc/github oidc/google oidc/keycloak oidc/microsoft oidc/microsoft_internal