spid-ruby

Project	Spid Ruby
Gem name	spid
License	BSD 3
Version
Continuous integration
Test coverage
Credits	Contributors
Slack Channel
Forum

Installazione & Configurazione

Installazione

Aggiungi al tuo Gemfile

gem "spid"

ed esegui nel terminale

$ bundle install

Configurazione

A questo punto è necessario aggiungere il middleware Spid::Rack nello stack dell'applicazione, avendo cura di inserirlo dopo un middleware per la gestione della sessione, ad esempio Rack::Session::Cookie

use Rack::Session::Cookie
use Spid::Rack

E configurare il parametri spid tramite il seguente codice

Spid.configure do |config|
  #config ...
end

tramite il quale potete accedere alle seguenti configurazioni:

Nome	valore default		Obbligatorio?
config.hostname		Hostname dell'applicazione, che verrà utilizzato come entity_id del service provider	✓
config.idp_metadata_dir_path		Directory dove si troveranno copia dei metadata degli Identity Provider del sistema SPID	✓
config.private_key_pem		Chiave privata del Service Provider in rappresentazione pem	✓
config.certificate_pem		Certificato X509 del Service Provider in rappresentazione pem	✓
config.attribute_services		Array degli attribute service indexes richiesti dal Service Provider all'Identity Provider (vedi sotto)	✓
config.metadata_path	/spid/metadata	Path per la fornitura del metadata del Service Provider
config.login_path	/spid/login	Path per la generazione ed invio dell'AuthnRequest all'Identity Provider
config.acs_path	/spid/sso	Path per la ricezione dell'Assertion di autenticazione
config.logout_path	/spid/logout	Path per la generazione ed invio della LogoutRequest all'Identity Provider
config.slo_path	/spid/slo	Path per la ricezione dell'Assertion di chiusura della sessione
config.default_relay_state_path	/	Indirizzo di ritorno dopo aver ricevuto un Assertion
config.digest_method	Spid::SHA256	Algoritmo utilizzato per la generazione del digest per le firme
config.signature_method	Spid::RSA_SHA256	Algoritmo utilizzato per la generazione della signature XML
config.acs_binding	Spid::BINDINGS_HTTP_POST	Binding method utilizzato per la ricezione dell'Assertion di autenticazione
config.slo_binding	Spid::BINDINGS_HTTP_REDIRECT	Binding method utilizzato ler la ricezione dell'Assertion di chiusura della sessione
config.logging_enabled	false	Se true, abilita il logging delle richieste
config.logger	Logger.new($stdout)	Indica lo stream dove viene salvato il log delle AuthnRequest e delle Response

Attribute Services

Il protocollo SPID prevede la possibilità di specificare almeno un servizio di attributi. Ogni servizio ha un nome e un elenco di attributi richiesti.

Per configurare dei servizi bisogna utilizzare questa configurazione

  Spid.configure do |config|
    ...
    config.attribute_services = [
      { name: "Service 1 name", fields: [ elenco_attributi_servizio_1 ] },
      { name: "Service 2 name", fields: [ elenco_attributi_servizio_2] }
    ]

Gli attributi disponibili sono

 :spid_code, :name, :family_name, :place_of_birth, :date_of_birth, :gender, :company_name, :registered_office, :fiscal_number, :iva_code, :id_card, :mobile_phone, :email, :address, :digital_address

Scaricamento metadata degli Identity Providers

Per motivi di sicurezza il sistema SPID prevede che un Service Provider abbia una copia 'sicura' dei metadata degli Identity Providers.

Al fine di facilitarne lo scaricamento la gemma spid-ruby prevede un task rake che li installa nella directory config.idp_metadata_dir_path.

$ rake spid:fetch_idp_metadata

Essendo dei segreti, è sconsigliato salvare i metadata di produzione nel codebase, quindi è preferibile rimandare il task durante la fase di deploy.

Utilizzando capistrano un modo potrebbe essere:

# config/deploy.rb

set :linked_dirs %(
  /path/to/idp_metadata_dir
)

namespace :deploy do
  task :fetch_idp_metadata do
    on roles(:web) do
      execute :rake, "spid:fetch_idp_metadata"
    end
  end
end

Se invece state usando heroku potete usare un buildpack apposito

$ heroku buildpacks:add  https://github.com/cantierecreativo/spid-ruby-heroku-buildpack.git

che lancierà automaticamente il comando durante il deploy. In questo modo i metadata verranno congelati nel dyno e saranno sempre disponibili

Sinatra

Occorre modificare il Rakefile dell'applicazione aggiungendo

# qui è necessario caricare preventivamente la configurazione SPID
# require "sinatra-app.rb"
require "spid/tasks"

Nota sulle chiavi OpenSSL

Per generare delle chiavi di test è possibile utilizzare il seguende comando:

openssl req -x509 -nodes -sha512 -subj '/C=IT' -newkey rsa:4096 -keyout spid-private-key.pem -out spid-certificate.pem

La configurazione di spid-ruby prevede che venga fornita direttamente la codifica .pem del certificato. Questo perché in sistemi quali Heroku sarebbe necessario avere le chiavi all'interno del repository git, cosa altamente sconsigliata in quanto segreto.

Nel caso di deploy su una macchina personale una possibile soluzione è l'utilizzo di capistrano in modo che i certificati siano gestiti esternamente dal repository.

Esempio di configurazione:

# config/deploy.rb

set :linked_files, %w(
  /path/to/private-key.pem,
  /path/to/certificate.pem
)

e nella configurazione

Spid.configure do |config|
  config.private_key_pem = File.read("/path/to/private-key.pem")
  config.certificate_pem = File.read("/path/to/certificate.pem")
end

Funzionamento

Login

Per iniziare un login con SPID è necessario utilizzare un url in questo formato /spid/login?idp_name=posteid&relay_state=/path/to/return&attribute_index=0, dove

• /spid/login: è il path configurato nel parametro config.login_path
• idp_name: rappresenta l'identificativo dell'Identity Provider con cui si vuole autenticarsi
• relay_state: rappresenta l'url dove deve essere fatto il redirect a seguito della ricezione della response di autenticazione
• attribute_index: rappresenta l'indice del servizio di attributi che vogliano vengano forniti dall'Identity Provider in caso di autenticazione riuscita

Logout

Per iniziare un logout con SPID l'url da utilizzare è /spid/logout?idp_name=posteid&relay_state=/path/to/return, dove

• /spid/logout: è il path configurato nel parametro config.logout_path
• idp_name: rappresenta l'identificativo dell'Identity Provider dove vogliamo terminare la sessione di autenticazione
• relay_state: rappresenta l'url dove deve essere fatto il redirect a seguito della ricezione della response di logout

Features

Compliance with SPID regulations (for Service Providers)
Metadata:
parsing of IdP XML metadata (1.2.2.4)	✓
parsing of AA XML metadata (2.2.4)
SP XML metadata generation (1.3.2)	✓
AuthnRequest generation (1.2.2.1):
generation of AuthnRequest XML	✓
HTTP-Redirect binding	✓
HTTP-POST binding
AssertionConsumerServiceURL customization	✓
AssertionConsumerServiceIndex customization
AttributeConsumingServiceIndex customization	✓
AuthnContextClassRef (SPID level) customization	✓
RequestedAuthnContext/@Comparison customization
RelayState customization (1.2.2)	✓
Response/Assertion parsing
verification of Response/Signature value (if any)
verification of Response/Signature certificate (if any) against IdP/AA metadata
verification of Assertion/Signature value	✓
verification of Assertion/Signature certificate against IdP/AA metadata	✓
verification of SubjectConfirmationData/@Recipient
verification of SubjectConfirmationData/@NotOnOrAfter
verification of SubjectConfirmationData/@InResponseTo
verification of Issuer	✓
verification of Destination	✓
verification of Conditions/@NotBefore	✓
verification of Conditions/@NotOnOrAfter	✓
verification of Audience	✓
parsing of Response with no Assertion (authentication/query failure)
parsing of failure StatusCode (Requester/Responder)
Response/Assertion parsing for SSO (1.2.1, 1.2.2.2, 1.3.1):
parsing of NameID	✓
parsing of AuthnContextClassRef (SPID level)
parsing of attributes	✓
Response/Assertion parsing for attribute query (2.2.2.2, 2.3.1):
parsing of attributes
LogoutRequest generation (for SP-initiated logout):
generation of LogoutRequest XML	✓
HTTP-Redirect binding	✓
HTTP-POST binding
LogoutResponse parsing (for SP-initiated logout):
parsing of LogoutResponse XML	✓
verification of Response/Signature value (if any)
verification of Response/Signature certificate (if any) against IdP metadata
verification of Issuer	✓
verification of Destination	✓
PartialLogout detection
LogoutRequest parsing (for third-party-initiated logout):
parsing of LogoutRequest XML	✓
verification of Response/Signature value (if any)
verification of Response/Signature certificate (if any) against IdP metadata
verification of Issuer	✓
verification of Destination	✓
parsing of NameID	✓
LogoutResponse generation (for third-party-initiated logout):
generation of LogoutResponse XML	✓
HTTP-Redirect binding
HTTP-POST binding	✓
PartialLogout customization
AttributeQuery generation (2.2.2.1):
generation of AttributeQuery XML
SOAP binding (client)

Compliance with SPID regulations (for Attribute Authorities)
Metadata:
parsing of SP XML metadata (1.3.2)
AA XML metadata generation (2.2.4)
AttributeQuery parsing (2.2.2.1):
parsing of AttributeQuery XML
verification of Signature value
verification of Signature certificate against SP metadata
verification of Issuer
verification of Destination
parsing of Subject/NameID
parsing of requested attributes
Response/Assertion generation (2.2.2.2):
generation of Response/Assertion XML
Signature

Testing

Clona il repository

$ git clone git@github.com:italia/spid-ruby
$ cd spid-ruby
$ bundle install
$ bundle exec rake

Contribuire

Chiunque è benvenuto nella community e libero di contribuire al suo sviluppo. Ci aspettiamo che chi contribuisca aderisca al codice di condotta Contributor Covenant.

Se sei nuovo e vuoi iniziare a contribuire anche te, tieni d'occhio queste issues!!

Per contribuire al repository

• Forka il progetto
• Crea il tuo feature branch git checkout -b my-feature-branch
• Committa le tue modifiche git commit -a -m "Add some feature"
• Pusha il tuo branch git push origin my-feature-branch -u
• Crea una pull request

Essendo SPID un sistema atto a garatire un sistema di autenticazione certificato con le PA la correttezza del codice deve essere sempre garantita, pertanto ogni pull request che andrà a modificare il codice della libreria dovrà essere corredato degli specifici tests che ne dimostrano la correttezza. Pertanto pull requests senza relativi tests non verranno mergiate.

Nel caso di apertura di una issue relativa ad un bug, siete pregati di fornire o un commit con un test fallimentare o tutti gli step necessari alla riproduzione del bug.

License

Questa gemma è disponibile in open source sotto i termini della licenza BSD-3

Code of Conduct

Chiunque interagisca con il codice, l'issue tracker o qualunque altro canale di comunicazione è pregato di rispettare il seguente codice di condotta.

Authors

• David Librera - Cantiere Creativo