SAML 2.0 Authentication

Kasm offers SAML configurations for authorization through SAML 2.0 Identity Providers. This gives users a single sign on experience and improves security.

Configuration

Saml configuration can be found under the Authentication tab in the Admin Navigation Bar.

Service Provider

We automatically generate the Service Provider Entity ID, single login url and single logout URL when you submit a configuration as this is based on the hostname of your server.

  • Enabled

    This checkbox will enable this configuration to be seen by the users. It is not the same as the Servers enable_saml setting which turns off all SAML capabilities. This will allow one specific configuration to be shown on the login page to allow multiple configurations to be added but not shown to users until enabled.

  • Display Name

    This is the name shown to the users in a login button on the login page. e.g. ‘OneLogin’, ‘Okta’

  • Entity ID

    This is the URL that identifies the Service Provider. It may be called a Provider Issuer or something similar. The URL is automatically created by Kasm for this configurations sign on.

  • Single Sign On Service

    This is the URL used for the response from the Idp to login. The URL is automatically created by Kasm to connect to the specific configuration.

  • Single Logout Service

    This is the URL provided for the logout of the user. It may be provided by the IDP but is not required

  • Relay State

    The Relay state must be set to https://hostname/#/sso

  • Auto Login

    This setting will automatically launch this saml configuration from the default login page. Only one configuration should be set to auto login. If this is set the normal login page may still be accessed at /#/staticlogin

  • Group Member Attribute

    This setting maps the attribute from the Idp to the Kasm group. The group must be enabled for kasm and given the name under the individual group edit.

  • NameID

    This attribute is used as the identifier for the user. The Idp may specify it is set to “emailAddress” or something similar but it may also be blank.

  • ADFS

    if using Active Directory Federation Services select this checkbox

  • x509 Certificate

    This is an Optional Certificate that can be provided for signature verification of the SP

  • Private Key

    This will be generated along with the optional x509 certificate above

  • Debug

    This will enable the response to show the specific saml error that is occuring. It is useful during setup of the configuration.

Identity Provider

  • Entity ID *Required

    This is the URL provided by the IDP that identifies the provider. It may be called a Provider Issuer or something similar. This URL must be configured for the Login to work properly.

  • SingleSignOnService/SAML 2.0 Endpoint *Required

    This is the URL provided by the IDP used for the login. This URL must be configured for the Login to work properly.

  • SingleLogoutService/SLO Endpoint

    This is the URL provided for the logout of the user. It may be provided by the IDP but is not required

  • x509 Certificate

    This is the certificate used to verify the signature of the application and it is required.

  • Attributes

    One attribute must be provided by the IDP. It should be a unique identifier like username or email

Security Options

These options can be configured in the security text area at the bottom of the configuration in JSON format.

SAML Setup

For general SAML configuration:

  • Copy the Service Provider Entity ID, Single Sign On, (optionally) Single Logout Service to the Identity Provider.

  • The Identity Provider must also be given the Relay State provided

  • a NameID attribute must be set to return the specific attribute of the user. (e.g. ‘emailAddress’, ‘transient’) A default of Unspecified is used when not present.

The Identity Provider should then return these same settings to be put under the Identity Provider section in the configuration settings.

  • The metadata button should return the Service Provider information.

If the Test SSO button is working the ‘enable_saml’ setting may then be set to true. This allows all users to be redirected to the Single Sign On portal.

Some of the specific IDP setups below may help in setting up SAML as they are sometimes similar

Note

A non redirecting login page is at https://hostname/#/staticlogin when auto login is enabled.

Group Assignment

Groups for saml users are automatically assigned if group has “saml group” attribute set in group edit. This will allow automatic provisioning of groups to saml users but will not unassign non-saml groups.

To automatically assign groups to saml users:

  • Navigate to the Groups tab in the admin navigation bar

  • Select edit of desired group

  • Check SAML Group

  • Enter SAML Group Name as the name the IDP has for this group

../_images/group_attributes.png

  • Navigate to the SAML configuration

  • Change the Group Member Attribute to the corresponding group attribute of the IDP

Okta Setup

Follow the steps in the Okta application setup

When asked for the SAML Settings.

../_images/saml_okta_settings.png

Go To Kasm’s Saml configuration

  • Select Create New Configuration

Fill out the form:

  • Copy Entity ID from the configurations page in the “Audience URI (SP Entity ID)” field

  • Copy the Single Sign on Service from the configurations page to the Single sign on URL field

  • Copy Relay State to the default Relay State

  • Change Name ID format to EmailAddress

  • Optionally advanced settings can be set here and the Single Logout Service could be configured

Kasm SAML currently requires attributes to be returned in the SAML response unless security option wantAttributeStatement is false

  • Enter a user name attribute on the optional attributes section

../_images/saml_okta_attributes.png

Under Group Attribute Statements

  • If the users are to be automatically added to a group then this can be set to match the Service Provider Group Member Attribute field. It will match the name of the groups passed with the names of the group saml name in the group configuration

Select next and add an internal app

Once created the Sign On page will say “View Setup Instructions”

In this form copy the field into the Kasm Saml Configuration

  • Copy the Single Sign-On URL to the Identity Provider Single Sign On URL

  • Copy the Identity Provider Issuer to the Identity Provider Entity ID

  • Copy the x.509 Certificate to the Identity Provider x.509 Certificate. This may need to have the begin and end certificate lines removed

Then in Okta assign a user to the application

In Kasm Select the test SSO button at the bottom of the configuration form

If the connection works properly go to Settings in the Admin navigation bar

Select enable_saml from the settings and change it to true

Users will now be automatically routed to the Okta portal on first connection to the Kasm. Administrators can still sign in through https://hostname/#/staticlogin as normal

OneLogin Setup

In the Administration panel of OneLogin:

  • Select add app

  • Select SAML Test Connector (IdP w/attr)

  • Select Save

  • Select the Configuration tab

../_images/onelogin_config.png

Open Kasm as an administrator.

  • Go to Authentication/Saml in Kasm’s navigation bar

  • Click “Create New Configuration”

  • Copy Entity ID to OneLogin’s Audience field

  • Copy Single Sign On Service to OneLogin’s Recipient Field.

  • Copy Single Sign on Service to OneLogin’s ACS (Consumer) URL

  • Enter .* in ACS validator (this should be updated with regex for the ACS URL later once login is setup)

  • Optionally copy Single Logout Service to Single Logout URL

  • Select Save on the OneLogin configuration page

Go to the SSO tab on OneLogin’s page

../_images/onelogin_sso.png

  • Copy the Issuer URL to the Identity Provider Entity ID field on the bottom of the Kasm SAML configuration form

  • Copy the SAML 2.0 Endpoint URL to the Identity Provider Single Sign field on the bottom of the Kasm SAML configuration form

  • Optionally add the SLO endpoint single logout service to the Single Logout Field

  • Select the SSO, then select View Details of the X.509 certificate on the OneLogin page

  • Copy the certificate into the X509 certificate text area in Kasm

  • Select Submit on the Kasm Configuration

In OneLogin select the Access tab and select the default roles for users. Go back to the Kasm Saml configuration and select Test SSO.

This will launch the login with the OneLogin portal. If the test is successful the Kasm will be logged in under the username for the OneLogin email provided.

If the test was successful it will have logged out the Admin. Logout and log back in as an administrator.

If the login is not working you may select the debug checkbox in the saml configuration the response will contain the specific saml error

If the login works properly enable the configuration with the enabled checkbox under service Provider

  • Navigate to the Settings tab in the administators navigation bar

  • Select the enable_saml setting and change it to “true”

  • Select enabled in the Saml configuration

This will enable the login to be seen by the users