Virtual Users


By default, the user you use to log in and the linux user running your sessions are the same. However there are times when this is not possible. Common reasons are

  • Web Bases authentication (SAML, OpenID Connect)
  • Heterogeneous Clusters (you have different logins on different systems and want them to map to the same login).

In these and other scenarios, you can create virtual users that map the login to the session name. FastX provides multiple scripts to allow for mapping of the linux users and the FastX logins.

Notes on Login vs User

You may see two similar but distinct parameters in the session data.

  • login – the FastX login who owns the session
  • user – the actual Linux user running the session

Remapping sessions to different FastX Logins using uncordon

An admin can set an optional FastX login when uncordoning a session. This has the effect of migrating the session to a new FastX Login. It is important to note that this action is happened when a session is already running and has connected and is sending data to the web server

USER_ID_SCRIPT

After a successful authentication, the FastX server executes the USER_ID_SCRIPT. This script takes input from the authentication, and returns a JSON like object of metadata that is attached to the login account.

The default script is located in /usr/lib/fastx/4/integration/id.py. Copy and modify it as needed and set the USER_ID_SCRIPT environment variable to the new script

Input

each authentication method expects its own special data fields custom to the auth method

SSH Authentication: auth-ssh
 { 
     "authMethod": "auth-ssh",
     "data": {
         "username": "THE_SSH_USERNAME"
     }
  }


OpenID Connect Authentication: auth-oidc

  { 
     "authMethod": "auth-oidc",
     "data": {
          "user": <Decoded user token -- standard claims can be found here https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims >
          "tokeninfo": {
               "token_type": "Bearer",
               "expires_at": <number_linux_timestamp>,
               "access_token": <OIDC Token>,
               "scope": "openid email profile",
               "id_token": <OIDC Id Token>
           }
      }
  }

SAML Authentication:  auth-saml
  { 
     "authMethod": "auth-oidc",
     "data": {
          "profile": <assertion object. the only standard assertion is nameID>
      }
  }

Output

All output is optional, but the following are typically used

login: map the name that was used to authenticate to a different FastX user.  Typically used for OIDC, SAML, 
user: specify the linux username to use when launching a session.  By default user = login
email: default email address.  Can be overridden by the end user preferences
groups: array of groups user belongs to.  Used to set permissions, or to filter apps/nodes to launch sessions on

The following options are typically used for docker/kubernetes integrations

uid: uid to use when launching a session.
gid: gid to use when launching a session.
shell: shell to set when launching a session. 
home: set user's home directory

USER_ID_START_SCRIPT

A related script USER_ID_START_SCRIPT can be executed on a per system basis and is executed right before the user attempts to start the session. There are slight differences in the input but the output is the same.

USER_ID_SCRIPT vs USER_ID_START_SCRIPT

Both scripts work to set certain variables for the user. However there are slight variations in the execution of both scripts

Input

USER_ID_SCRIPT

  • takes the input as listed above

USER_ID_START_SCRIPT

  • Takes the same input as the start object.
  • Appends the output to start.stdin.userData

Output

Both scripts can return any metadata needed for integration. However there are several special output parameters that add to functionality of FastX.

USER_ID_SCRIPT

  • login — sets the login of the user. This is the FastX login to be used throughout
  • email — sets the login email for use with the email service
  • groups — sets the groups array

USER_ID_START_SCRIPT

  • user — defines the linux user that will execute the start command

Exit Codes

USER_ID_SCRIPT will log the exit code and continue.
USER_ID_START_SCRIPT must exit with code 0 or it results in an API error.