spid-ruby

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

Aggiungi al tuo Gemfile

gem "spid"

ed esegui nel terminale

$ bundle install

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:

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

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

Occorre modificare il Rakefile dell'applicazione aggiungendo

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

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

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

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

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

Clona il repository

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

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.

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

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

• David Librera - Cantiere Creativo