Skip to content
App IO (backend)
Branch: master
Clone or download
Latest commit 1c72d1e Mar 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.prettierrc Tsc fixes (#34) Feb 26, 2018
api_pagopa.yaml [#159851430] Markdown and Subject in a MessageWithContent need to be … Sep 6, 2018
api_proxy.yaml Fixes specs of notification API (#358) Oct 3, 2018
docker-compose.yml [#158907283] Remove latest references to the old spid-testenv-identit… Sep 12, 2018
tsconfig.json Enables tslint-language-service plugin (#224) [skip ci] Jul 9, 2018
yarn.lock Updates yarn.lock Mar 20, 2019


Codacy Badge



Docker Build Status


FOSSA Status

Digital citizenship web and mobile backend

This repository contains the code of the backend used by the web and mobile applications of the Digital citizenship project.

Table of content

What is this?

This is the backend that supports the italia-app mobile application.

This project is part of the Italian Digital Citizenship initiative, see the main repository for further information.

Authentication process

The italia-app application will authenticate to the backend in two steps:

  1. an initial user initiated SPID authentication process (SAML2 based) that identifies the user and, on success, triggers the creation of a new authentication session (associated to a session token)
  2. subsequent requests to the backend will be authenticated via a bearer session token


User authentication

When a client (the mobile app or a browser) wants to login with the backend it will call the /login endpoint with the IDP entityID as parameter in the query string. The backend will then builds an authorization URL and performs a redirect to the chosen IDP. The authentication process will continue to the IDP website. If the authentication process ends with success the IDP will redirect the client to an HTML page with a form that will auto-post itself to the /assertionConsumerService endpoint with a SAMLResponse as an hidden field. The backend will parse and validate the SAMLResponse to extract all the user attributes (fiscal code, first name, last name, email), then it will generates an unique alphanumeric string as token and saves an User object to the SessionStorage service using the token as key. Finally the backend will redirect the client to the value of the environment variable CLIENT_REDIRECTION_URL with the token in the query string. The client must saves the token and use it in all API request.

The code that manage this flow are in the spid-passport package (more info here), and in the src/strategies/spidStrategy.ts and src/controllers/authenticationController.ts files.

Token authentication

All API requests sent by the client to the backend must have an Authorization: Bearer header with the value of the token obtained from the SPID authentication process. The token is used to retrieve the User object from the SessionStorage service.

The code that manage this flow are in the src/strategies/bearerSessionTokenStrategy.ts file.

How to run the application


To fully simulate the SPID authentication process we use the images provided by the spid-testenv2 project.

A Linux/macOS environment is required at the moment.

Installation steps

  1. clone the project in a folder called italia-backend

  2. go to the project's folder

  3. run scripts/ to build the tools Docker image

  4. run scripts/ to install backend dependencies

  5. run scripts/ to generate the models defined in api_proxy.yaml and api_notifications.yaml

  6. run scripts/ to compile the Typescript files

  7. run scripts/ to create SAML (SPID) certificates

  8. run docker-compose up -d to start the containers

  9. edit your /etc/hosts file by adding:

    localhost    spid-testenv2
    localhost    italia-backend
  10. copy .env.example to .env and fill the variables with your values

  11. point your browser to https://italia-backend/metadata and copy the source of the page to a new testenv2/conf/sp_metadata.xml file

  12. run docker-compose up -d to restart the containers

  13. point your browser to https://italia-backend

If you are using Docker with a Docker Machine replace localhost with the IP of the Docker Machine (More details here).

Container description

  • backend: the backend Node application that serves the web and mobile applications
  • spid-testenv2: the test IDP server

Nginx is reachable at https://italia-backend:80
IDP is reachable at https://spid-testenv2:8088 \

Environment variables

Those are all Environment variables needed by the application:

Variable name Description type
API_KEY The key used to authenticate to the API backend string
API_URL The API backend URL string
CLIENT_REDIRECTION_URL The path where the user will be redirected after a successful SPID login string
CLIENT_ERROR_REDIRECTION_URL The path where the user will be redirected when en error occurs during SPID login string
PORT The HTTP port the Express server is listening to int
REDIS_URL The URL of a Redis instance string
TOKEN_DURATION_IN_SECONDS The number of seconds a session token is considered valid int
SAML_CALLBACK_URL The absolute URL of the assertion consumer service endpoint string
SAML_ISSUER The issuer id for this Service Provider string
SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX The index in the attribute consumer list int
PRE_SHARED_KEY The key shared with the API backend to authenticate the webhook notifications string
ALLOW_NOTIFY_IP_SOURCE_RANGE The range in CIDR form of allowed IPs for the webhook notifications string
AZURE_NH_HUB_NAME The hub name configured in the Azure Notification HUB string
AZURE_NH_ENDPOINT The endpoint URL configured in the Azure Notification HUB string
ALLOW_PAGOPA_IP_SOURCE_RANGE The range in CIDR form of allowed IPs for the PagoPA API string
AUTHENTICATION_BASE_PATH The root path for the authentication endpoints string
API_BASE_PATH The root path for the api endpoints string
PAGOPA_BASE_PATH The root path for the PagoPA endpoints string
SPID_AUTOLOGIN The user used in the autologin feature, omit this to disable autologin string


Application logs are saved into the logs folder.

SPID user management

The setup procedure adds some test users to the test IDP server, the full list could be retrieved in testenv2/conf/users.json. To add more users simply add more items to this file and restart the spid-testenv2 container.

How to contribute


A Linux/macOS environment is required at the moment.

Starting steps

  • use nodenv to run the correct version of Nodejs as specified in app/.node-version
  • run Jest tests directly or with scripts/

In general follow the Node Best Practices.

Generate SAML (SPID) certs (development)

The backend implements a SAML Service Provider - for authenticating the clients it needs a certificate that you can generate with the following command (you need to have openssl available in your path):

$ yarn generate:test-certs

Generate SAML (SPID) certs (production)

For production, the SPID certificate must be generated with the following command:

$ openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:4096 -keyout key.pem -out cert.pem

Then, the key and the certificate must be stored in the Kubernetes secrets:

$ kubectl create secret generic spid-cert --from-file=./cert.pem --from-file=./key.pem

Architecture decision records

In a world of evolutionary architecture, it's important to record certain design decisions for the benefit of future team members as well as for external oversight. Architecture Decision Records is a technique for capturing important architectural decisions along with their context and consequences. We store these details in source control, along with code, as then they can provide a record that remains in sync with the code itself.

We use ADRs to track architectural decisions of this initiative.

This repository is configured for Nat Pryce's adr-tools.

Here's the decisions we taken so far:

ADR Title PR (discussion)
1 Record architecture decisions
2 Backend runs on Docker on local environments
3 Use OpenAPI to defined the API specs
4 Use a dependency injection container
5 Use a GUID as Installation ID
6 Backend is deployed on more than one instance


I installed on my mac but seems that https://italia-backend:80 is not working (ping italia-backend return a host error)

Check out /etc/hosts Remember that in some cases you need to use your docker-machine ip (get it from >docker-machine ip) instead of localhost.

I followed all the steps but when i go to https://italia-backend it shows me the same as https://italia-backend:8080

This problem seems to be dependent on how Docker for Mac (doesn't) manage well the /etc/hosts file. If you install Docker Toolbox it works fine (and can coexist) (Read more at


FOSSA Status

You can’t perform that action at this time.