IO Onboarding portal backend
This repository contains the code of the backend application of the IO Public Administrations onboarding portal.
What is IO?
More informations can be found on the IO project website.
Prerequisites
Dependencies
In order to test the backend locally, aside the backend NodeJS process, some services must be up and running:
- SPID test environment
- PostgreSQL for data persistence
- [MailHog] smtp server (to test emails)
All these services starts automatically running docker-compose.
Environment variables
Required environment variables
The table lists the environment variables needed by the application; they may be customized as needed.
Variable name | Description | type |
---|---|---|
BACKEND_PORT | Port of express web server | number |
POSTGRESQL_HOST | The name of postgres server host to connect to | string |
POSTGRESQL_PASSWORD | The password used to connect to postgres server | string |
POSTGRESQL_USERNAME | PostgreSQL user name to connect as | string |
POSTGRESQL_DATABASE | The database name | string |
CLIENT_DOMAIN | The client domain, which will be CORS-enabled | string |
COOKIE_DOMAIN | The allowed hosts to receive the cookie containing the session token | string |
CLIENT_SPID_LOGIN_REDIRECTION_URL | The path where the user will be redirected to perform a SPID login | string |
CLIENT_SPID_ERROR_REDIRECTION_URL | The path where the user will be redirected when en error occurs during SPID login | string |
CLIENT_SPID_SUCCESS_REDIRECTION_URL | The path where the user will be redirected after a successful SPID login | string |
SAML_ACCEPTED_CLOCK_SKEW_MS | The value of the accepted clock skew in milliseconds | number |
SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX | The index in the attribute consumer list | number |
SAML_CALLBACK_URL | The absolute URL of the assertion consumer service endpoint | string |
SAML_ISSUER | The issuer id for this Service Provider | string |
SAML_CERT_PATH | The path of the public certificate used in SAML authentication to a SPID IdP. | string |
SAML_KEY_PATH | The path of the private key used in SAML authentication to a SPID IdP. | string |
SPID_AUTOLOGIN | The user used in the autologin feature, omit this to disable autologin | string |
SPID_TESTENV_URL | The absolute URL of the test IDP server | string |
IDP_METADATA_URL | Url to download IDP metadata from | string |
TOKEN_DURATION_IN_SECONDS | The number of seconds a session token is considered valid | int |
EMAIL_PASSWORD | The password used to connect to the email server | string |
EMAIL_USER | The user to connect to the email server | string |
EMAIL_SMTP_HOST | The hostname or IP address of the SMTP server | string |
EMAIL_SMTP_PORT | The port of the SMTP server | int |
EMAIL_SMTP_SECURE | If set to true, uses TLS in SMTP connection | boolean |
EMAIL_SENDER | The email address of the sender | string |
INDICEPA_ADMINISTRATIONS_URL | The URL to download the public administrations info from | string |
ARSS_WSDL_URL | The WSDL URL of Aruba Remote Sign Service | string |
ARSS_IDENTITY_OTP_PWD | The valid user OTP for the ARSS signature transaction | string |
ARSS_IDENTITY_TYPE_OTP_AUTH | The authentication domain of the ARSS user | string |
ARSS_IDENTITY_USER | The username of the ARSS user | string |
ARSS_IDENTITY_USER_PWD | The password of the ARSS user | string |
Optional environment variables
The table lists the optional environment variables: if any of them is not set, the application will use its default value instead.
Variable name | Description | type | default |
---|---|---|---|
ADMINISTRATION_SEARCH_RESULTS_LIMIT | The maximum number of administrations returned when performing a search | number | 30 |
Production deployments
An Azure pipeline is configured by the IO adminstrators to run on each push on the master branch.
Each time a change is merged, a corresponding Docker image is automatically created on DockerHub.
The image is then deployed on Kubernetes clusters using a dedicated helm-chart; see the production deployment repository.
The deployed backend is reachable at [https://api.pa-onboarding.dev.io.italia.it/]https://api.pa-onboarding.dev.io.italia.it/).
Test the application locally
To build the application and starts the services, run from the project root:
cp env.example .env
# edit .env
docker-compose up -d database
docker-compose up
The docker-compose.yaml file sources variables from a .env file that must be placed in the root folder of this repository. An example file env.example is distributed with the code.
The backend REST APIs can be now accessed at http://localhost:3000.
To rebuild the software and see changes:
docker-compose up --build
Skip docker
If you run a suitable environment (ie. a Linux machine with NodeJS and yarn installed), you can avoid using docker and run the backend application directly.
First, install nvm, NodeJS and Yarn.
In this setup you must connect the application to a running PostgreSQL instance and a configured SPID test environment.
You may try with a hybrid setup starting these services using docker-compose before running the backend since ports are exposed by default:
# change .env *_HOST settings to point to localhost then run
docker-compose up -d database spid-testenv2 mailhog
Finally, run the backend locally:
nvm install $(< .node-version)
nvm use $(< .node-version)
yarn install
yarn watch
Modify SPID Service Provider certificates
To create new certificates, run the command
rm certs/*
yarn generate-test-certs
Then, start the containers using docker-compose and point your browser to http://localhost:3000/metadata. You should now manually replace the content of the testenv2/conf/sp_metadata.xml file with the output of this page.
To complete the configuration, remove from the testenv2/conf/sp_metadata.xml
file the <EncryptionMethod>
elements, and add between the elements
<KeyDescriptor>
and <NameIDFormat>
the following tag:
<SingleLogoutService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="http://localhost:3000/spid/logout" />
Finally, run docker-compose restart
and start using the backend application
with the new certificates.
Test the login with SPID
SPID test users attributes and credentials are listed in the page http://localhost:8088/users.
Two users are created by default:
- pippo / test
- pinco / test
To validate SPID login functionalities, point your browser to http://localhost:3000/login?entityID=xx_testenv2&authLevel=SpidL2 and use the login credentials of one of the SPID test users configured.