.. 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. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Enforce Client Settings** | When enabled, the client settings listed below will be enforced on the session , overriding the client settings attached to the user's group(s). | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Audio** | When enabled, the staged session will support streaming audio from the session to the user. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Audio Default On** | When disabled, the audio service will be muted by default. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Downloads** | When enabled, the staged session will allow download files from the session to their local computer via the control panel download widget. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Clipboard Down** | When enabled, the staged session will allow copying data from the session to the users local computer via the clipboard. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Clipboard Up** | When enabled, the staged session will allow copying data from the user’s local computer to the session. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Microphone** | When enabled, the staged session will allow the user to pass their local microphone into the session. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Uploads** | When enabled, the staged session will allow the user to upload files from their local computer to the session via the upload widget in the control panel. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Sharing** | When enabled, the user will be able to place their session in sharing mode. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **IME Default On** | When enabled, IME mode will be enabled by default if the doesnt already have a local preference set. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Valid Until** | When defined, the casting link will only be valid until this time, after which the client will be presented with an error. | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ * 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