--- myst: html_meta: "description lang=en": "General OpenID configuration guide for Kasm Workspaces. " "keywords": "Kasm, OpenID, ODIC, Authentication" "property=og:locale": "en_US" --- ```{title} OpenID Authentication ``` # OpenID Authentication Kasm can utilize external authentication providers using OpenID Connect (OIDC). ```{include} /guide/oidc/warning.md ``` ```{figure} /images/oidc/login.webp :align: center **Kasm Login** ``` ## Configuration OpenID configuration can be found under the Access Management -> Authentication tab in the Admin Navigation Bar. ```{eval-rst} .. 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 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: 1. In the OpenID Authentication configuration, ensure the **Groups Attribute** is defined. 2. Navigate to the Access Management -> Groups tab in the admin navigation bar. 3. Using the arrow menu select **Edit** of the desired group 4. Navigate to the **SSO Group Mappings** tab and select **Add SSO Mapping**. 5. Select the OpenID IDP for example "OpenID - test_oidc" for the **SSO Provider**. 6. 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.webp :align: center **Add SSO Group Mapping** ``` ## OpenID Attribute Mapping Additional OpenID attributes can be passed with the login redirect. Administrators can optionally map those attribute values to fields on the Kasm user. See the documentation for your OpenID provider for a listing of attributes. These can be configured by editing an existing OpenID Authentication configuration, if creating a new configuration you will need to submit and edit to add them. The following Kasm User fields can be populated with values from OpenID attributes. - First Name - Last Name - Phone - Organization - Notes - City - State - Country - Email - Custom Attribute 1 - Custom Attribute 2 - Custom Attribute 3 ```{figure} /images/oidc/oidc_attribute_mapping.webp :align: center **Attribute Mapping** ``` ```{note} Kasm can log all OpenID attributes present in the login event, this is helpful for determining the attribute names. Add an OpenID Attribute Mapping with an attribute name of 'debug' and target any user field. The next time a user logs in, all OpenID attributes and values will be logged by Kasm. ``` ## Configuration Examples ```{toctree} :maxdepth: 1 oidc/github oidc/google oidc/keycloak oidc/microsoft oidc/microsoft_internal oidc/auth0 ```