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.