illgrenoble/visa-accounts repository overview

⁠VISA Accounts

This project contains the source code for the Accounts service of the VISA platform.

VISA (Virtual Infrastructure for Scientific Analysis) makes it simple to create compute instances on facility cloud infrastructure to analyse your experimental data using just your web browser.

See the User Manual⁠ for deployment instructions and end user documentation.

⁠Description

The main objective of VISA Accounts is to authenticate a user using OpenID Connect and returns an Account object (with related attributes such as username, home path, etc) and the connected user (userId, name, etc).

Access to this micro service is from the VISA API Server. VISA passes the OpenID Connect token (JWT) and VISA Accounts provides the necessary mechanism to contact the SSO, validate the token and return user and account information.

⁠Account Attributes and Cloud-Init

Account attributes are details concering the user and the account of the connected person (eg user name, email, username, home path, etc). Some are common across VISA (ie the user details) but a number can be site specific (eg home path, UID, GID, etc): these attributes are called account parameters.

The Account Parameters are stored in a dictionary (key - value) and sent automatically to a user's instance as part of the Cloud-Init metadata. These can then be used during the boot process of the instance if any confiuration within the VM is needed.

⁠Obtaining account attributes

As mentioned previously, certain Account Attributes can be site-specific so we leave this open for deployment at each facility. SSOs (eg Keycloak) can provide these in many cases but we need to make the design open to add institute-specific modules to obtain account details.

Different providers are necessary to obtain the account attributes as this can depend on site-specific infrastructure. For example we can have

• account attributes passed with the authentication token (eg using keycloak)
• LDAP
• DB
• web service

An internal API written in JavaScript is therefore used to have an abstraction of the provider methods. An environment variable allows for the path to the concrete implementation of the attribute-provider API to be specified at runtime (Docker volume mounts can also be used to link a container to the provider file on the host machine).

⁠Developing and integrating an attribute provider

To integrate and attribute provider for a facility, a simple JavaScript file has to be linked to the application (specified using an environmnet variable). The interface of this javascript files is as follows:

getUserId(userInfo): string;
getUsername(userInfo): string;
getFirstname(userInfo): string;
getLastname(userInfo): string;
getEmail(userInfo): string;
getAccountParameters(userInfo): Object;

⁠The User ID

The User ID is an essential element returned by the attribute provider. This ID has to be unique for a user and it is required to be able to link the authenticated user to the facility User Office data (ie proposals or experiments) and user roles (injected separately in the ETL process of VISA).

The UserId is a string type to allow any identifier type from facility sites. This may be the same as the account username but it could also be a database primary key.

⁠The UserInfo object

The userInfo object is a wrapper to the UserInfo Response⁠ provided by OpenID Connect and provides a single method (get(claim)) to obtain claims returned by the SSO. In implementing the attribute provider this can be used as follows:

getUserId(userInfo) {
  return userInfo.get('user_id_claim');
}

⁠Account Parameters

The getAccountParameters method is expected to return an object with parameters as properties. These parameters are passed to the OpenStack instance on creation using the Cloud-Init mechanism and therefore are accessible during the boot process.

⁠Example Attribute Provider

An example attribute provider⁠ is included in the VISA Account Github project:

const getUserId = function (userInfo) {
  return userInfo.get('the_userid_claim')
}
 
const getAccountParameters = function (userInfo) {
  return {
    'homePath', userInfo.get('the_home_directory_claim')
  }
}
 
module.exports = {
  getUserId: getUserId,
  getAccountParameters: getAccountParameters
};

⁠Implementation

Not all attributes may come directly from OpenID Connect as mentioned previously, so connections to other databases or LDAP may be required for the full implementation.

A default attribute provider⁠ is included in VISA Accounts to take standard claims from the UserInfo Response. As such not all of the methods outlined above necessarily need to be implemented. The following table shows which methods can be optionally implemented and what are the default values used by the service:

⁠Installation

npm install

⁠Run

npm start

⁠Environment variables

The following environment variables are used to configure VISA Accounts and can be placed in a dotenv file:

⁠Acknowledgements

VISA has been developed as part of the Photon and Neutron Open Science Cloud (PaNOSC⁠)

PaNOSC has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No 823852.