--- myst: html_meta: "description lang=en": "Configuration guide for two factor authentication using common authentication apps and TOTP software tokens. " "keywords": "Kasm, Multifactor, Authentication, 2FA, TOTP" "property=og:locale": "en_US" --- ```{title} Two Factor Authentication ``` # Two Factor Authentication Two Factor Authentication requires the user provide an additional piece of evidence beyond their standard password, to gain access to the system. Kasm implements a Time-based One-Time Password (TOTP) algorithm that can be used with popular apps such as Google's Authenticator. Physical tokens and WebAuthn devices (e.g. YubiKeys) can also be used. A user can be required to enroll a second authentication factor upon their next login by [the admin configuring the "require_2fa" setting](#require-two-factor-authentication). Alternatively, users may also [self-enroll a Two Factor device through the User Profile Page](#self-enrollment) when the "allow_2fa_self_enrollment" setting is enabled. ## Require Two Factor Authentication An Admin may require that all members of a group enroll a two factor device upon their next login. - Navigate to the Access Management -> Groups tab in the Administrators Sidebar and select Edit from the arrow menu for the group - Select Add Settings from the Settings tab - Select the "require_2fa" setting and select True to add to all of the users in the group ```{figure} /images/two_factor/auth_enable.webp :align: center **Require Two Factor Authentication Group Setting** ``` ```{note} WebAuthn and TOTP can be disabled individually using the "allow_webauthn_2fa" and "allow_totp_2fa" {doc}`group settings `. ``` ## Self Enrollment A user may self enroll a two factor in their user settings page when the "allow_2fa_self_enrollment" setting is enabled. Navigate to the user profile settings on your Kasm deployment by logging into your Kasm Workspaces deployment, clicking on your user icon and clicking "Edit Profile". ```{figure} /images/open_in_extension/profile.webp :align: center **Edit Profile** ``` Scroll down to select "Two Factor" and then select "Add Second Authentication Factor" ```{figure} /images/two_factor/profile_two_factor.webp :align: center **Add Two Factor** ``` ## Two Factor Setup When a user logs in the first time with "require_2fa" enabled, or they self-enroll, they will be presented with a setup page where they can select the following methods to register a new second factor: - [Soft TOTP Token (Google Authenticator)](#user-authentcator-app-setup) - [Hard TOTP Token](#physical-totp-token-setup) - [WebAuthn Device (YubiKey, TouchID, FaceID)](#webauthn-authentication) ```{figure} /images/two_factor/2fa_setup.webp :align: center **Two Factor Setup** ``` ## User Authentcator App Setup The user will be asked to add the authentication cide to their Authenticator App on the first log on after two factor was enabled. Once the username and password have been verified a QR code and secret are provided for easy implementation in Google's Authenticator - The User will select the plus icon in Authenticator and select Scan barcode to use thier phones camera to add the secret or Manual Entry to enter the secret manually ```{figure} /images/two_factor/auth_setup.webp :align: center **TOTP Setup** ``` - User must enter one time password provided in the Authenticator App to login ```{figure} /images/two_factor/auth_code.webp :align: center **Auth Code** ``` Download the Apps: [Apple App Store](https://itunes.apple.com/us/app/google-authenticator/id388497605?mt=8) [Google Play Store](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en_US?) ### Reset Single-User Authentication The user can reset the authentication code in the reset password section. - Navigate to the profile tab in the Sidebar and select "Reset Password" - Enter current password and a new password - Check the "Reset Two Factor Authenticator" checkbox and then click Submit ```{figure} /images/two_factor/auth_reset.webp :align: center **Auth Reset** ``` The administrator can reset the user's Two Factor TOTP Token or WebAuthn Credential. - Navigate to the Access Management -> Users tab in the Administrators Sidebar and select edit for the user from the arrow menu - Check the "Reset Two Factor TOTP Token" or "Reset Two Factor WebAuthn Credential" checkbox and then click Save ```{figure} /images/two_factor/auth_user_reset.webp :align: center **Auth Reset Admin** ``` ## Physical TOTP Token Setup Kasm Workspaces supports using physical tokens that meet the TOTP specification defined in RFC 6238. The tokens must use a 30 second token interval and use SHA1. Physical tokens purchased must come with a seed file, which is a password encrypted zip file containing a list of serial numbers with the associated base32 secret for each token. ```{figure} /images/two_factor/physical_tokens.webp :align: center **Physical Tokens List** ``` ### Import Physical Tokens Physical tokens will come with an encrypted zip file containing a list of serial numbers and associated secrets. In the administrator panel, go to Authenticate, Physical Tokens, and click the Import button. Provide the file and password associated with the file and click upload. ```{figure} /images/two_factor/import_physical_tokens.webp :align: center **Import Token Zip** ``` Physical TOTP vendors will provide the seed file with your order. The file must be a password protected zip file. The vendor will provide the password for the zip file. The zip file will contain a text file with a comma separated list of tokens. The first value is the token serial number, which matches the serial number on the back of the token. The second value in each row is the secret, which is a base32 encoded string. The following is an example of what the raw uncompressed seed file would look like. ``` 1234567891234,JNQXG3JANFZSA5DIMUQGEZLTOQQHG33G 1234567891235,OR3WC4TFEBSXMZLSEBRXEZLBORSWICQG ``` ### Assigning Tokens #### Administrator Assigned Tokens can be assigned and unassigned by the administrator by clicking arrow menu icon next to a token and selecting assign or unassign. #### User Self Register If an administrator does not explicitly assign a token to a user, the user can input the serial number on login to self register the token. A user will only be able to self-register a token if they are required to login with two factor authentication and they don't currently have a token assigned. Under those conditions, the user will be prompted to setup a token on login. The user will need to select the "I have a physical hardware device instead" link, which will then display the following dialog where they can enter the serial number located on the back of the physical token. ```{figure} /images/two_factor/token_setup.webp :align: center **User Token Setup** ``` ### Deleting Tokens Tokens can either be deleted individually or the administrator can delete all tokens that were imported together as part of the same seed file by clicking the Delete Seed Series button on the Physical Tokens view. Deleting a token will make it unusable to the currently assigned user. ## Token Time Drift TOTP requires the physical token or the user's phone to have nearly the same time as the server authenticating the user. This means that your Kasm backend servers need to have proper time synchronization for TOTP to work. Physical tokens utilize inexpensive crystal oscillation based timing hardware, which will drift over time. See your manufacturer's documentation for details. Generally speaking, crystal oscillation based hardware will drift upwards of 2 minutes every year. By default, Kasm allows for one 1 minute of drift forward or backward, from the server's time. A token is valid for 30 seconds, providing an overall allowed effective drift of 1 minute and 30 seconds by default. You may override the default by modifying the `Token Drift` {doc}`Server Settings <./settings>`. ## WebAuthn Authentication WebAuthn Authentication allows for users to use a supported WebAuthn device, such as a Yubikey, TouchID, or FaceID as a second factor to login to Kasm. Upon selecting "WebAuthn Device" during the Two Factor registration process the user will be presented with a dialogue to use a passkey, the user may select whatever device is desired. On their next login they will be prompted to use the WebAuthn device as a second factor. ```{figure} /images/two_factor/create_passkey.webp :align: center **WebAuthn Setup** ``` ```{note} WebAuthn only functions when the user's browser trusts the connection to Kasm Workspaces. This can be acheived by setting up the deployment with a valid {doc}`Custom Certificate ` or deploying behind a {doc}`Reverse Proxy ` that has a valid server certificate. ```