.. title:: Session Casting Session Casting =============== Session Casting allows administrators to expose external facing URLs that will automatically launch a Kasm session. These Casting URLs can optionally be unauthenticated and protected by ReCAPTCHA, Referrer, and IP rate limits. Administrators may find this feature useful for offering no-auth access to the Kasm environments. .. figure:: /images/casting/workflow.png :width: 100% :align: center Casting Workflow Configuration ------------- * Log into the Kasm Web UI as an administrator. * Click **Casting**. * Click **Create New Config**. .. figure:: /images/casting/create_casting_config.png :width: 90% :align: center Casting Config .. table:: :widths: 70 +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Name | Description | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **URL Key** | The unique identifier for a Casting URL. If **123abc** is the key, users will launch sessions via the following URL https://my.kasm.server/#/cast/**123abc** | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Image** | The Kasm **Image** to use for the created sessions. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Resume** | When enabled, authenticated users who already have a running session will have their session resumed instead of having a new session created when connecting to the same **Casting URL** | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Anonymous** | If checked, requests to the **Casting URL** will not require authentication. Instead the system will create an anonymous users account for each new request. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Require reCAPTCHA** | When **Allow Anonymous** is enabled, administrators can choose to have requests validated by `Google reCAPTCHA `_ . | | | To use this feature, the **Google reCAPTCHA Private Key** and **Google reCAPTCHA Site Key** properties must be set in the :doc:`Server Settings`. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Anonymous User Group** | When **Allow Anonymous** is checked, the system will create new user accounts for each new request. These anonymous users accounts will automatically be added to the **All Users** Group | | | and an additional Group defined here. Administrators can configure the appropriate Group Settings to configure permissions such as **allow_kasm_downloads** etc on this Group. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Limit Total Session** | When enabled, the administrator can configure a maximum number of sessions that will be served via this Casting URL. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Sessions Remaining** | Sets the total number of sessions that can be requested. This value will automatically decrement as new sessions are served. When the value reaches zero, users will receive an error when | | | attempting to request subsequent sessions. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Limit Requests Per IP** | When enabled, the system will limit the number of requests that will employ rate-limiting based on the source IP of the request. (e.g limiting requests to 1 sessions per 60 seconds) | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Sessions Allowed** | When **Limit Requests Per IP** is enabled, this value is used as the total number of sessions that are allowed for the given time period as defined in **Within Seconds**. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Within Seconds** | When **Limit Requests Per IP** is enabled, this value sets the timeframe (in seconds) that is used for the source IP. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Kasm URL** | If defined, this value will populate as the **KASM_URL** environment variable for created or assigned :doc:`Staged Sessions`. These values are often used in the | | | :doc:`Docker Exec Configs` of the browser Images. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Dynamic Kasm URL Parameter** | When checked, the user is allowed to append a :code:`kasm_url` query argument to the cast url. e.g :code:`https://kasm.server/#/cast/123?kasm_url=example.com` | | | If present the system will use this value as the **KASM_URL**. | | | | | | When used in conjunction with **Allow Resume**, this will open a new tab with the specified **KASM_URL** when the session is resumed. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Dynamic Docker Network URL Parameter** | When checked, the user is allowed to append a :code:`docker_network` query argument to the cast url. e.g :code:`https://kasm.server/#/cast/123?docker_network=example_network` | | | The Image used must have **Allow Network Selection** enabled. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Error URL** | If defined, the user will be pushed to this URL when an error (such as IP rate limit violation) occurs. If left blank, an internal error page is shown. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Disable Control Panel** | When checked, the Control Panel widget is not shown for the sessions. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Disable Tips** | When checked, the Tips dialogue is not shown when a user enters a session. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Enable Sharing** | When checked, this session will automatically have sharing activated. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Disable Shared Fixed Resolution** | When checked and the session is in sharing mode, the resolution will be dynamic. The resolution is typically fixed when a session enters sharing mode. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Restrict to Referrers** | Administrators may chose to restrict where the Casting URLs can be accessed from. If a user were to click a Casting URL link that was embedded on a 3rd party website, the system can detect the | | | website domain. It the address is not in the list defined in this setting, the request will be denied. Enter one domain (e.g acme.com) per line. If the option is left blank, requests from | | | all domains are accepted. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ * Fill out the form then click **Submit**. * A list of all Casting Configs is shown. .. figure:: /images/casting/casting_config_list.png :width: 90% :align: center Casting Config List * Test by navigating to the defined URL in a new browser window (e.g https://my.kasm.server/#/cast/123abc ) .. figure:: /images/casting/casting_captcha.png :width: 90% :align: center Casting reCAPTCHA Check .. note:: If the selected Image is configured with persistent profiles, and the Casting Config enforces authentication, the session launched will always load the user's persistent profile. Error Page ---------- When an error occurs that prevents the user from loading a session via a Casting URL, the system will send the user to an internal error page with an appropriate error message. If desired, the administrator can chose to redirect the user to a page of their choosing by configuring the **Error URL** setting in the Casting Config. .. figure:: /images/casting/casting_error.png :width: 90% :align: center Error Message