GARRCS:GARR-TCS-4

GARR Certification Service

GARR CS (Certification Service) gestisce il servizio GEANT TCS (Trusted Certificate Service) per la comunità della ricerca italiana.

Supporto

Per richieste di adesione, supporto, problemi tecnici e gestione degli account Admin scrivete a <garr-ca@garr.it>.

Per domande sull'uso della piattaforma, sui tipi di certificati, la loro creazione ed il loro uso utilizzate la mailing list <tcs@garr.it>. L'iscrizione alla lista è a cura di GARR CS ed è riservata ai Registration Authority Officers nominati da ogni organizzazione.

Per aprire un Ticket verso Sectigo: https://sectigo.com/support-ticket

Documentazione Sectigo

La documentazione Sectigo è disponibile in https://support.sectigo.com/Com_KnowledgeProductPage?c=Sectigo_Certificate_Manager_SCM

In particolare:

• SCM - Sectigo® Certificate Manager Quick Start Guide è una guida rapida per iniziare a lavorare con il portale SCM
• SCM - Sectigo Certificate Manager Administrator's Guide è la guida completa del portale SCM per Amministratori
• SCM - Sectigo Certificate Manager REST API è la guida per interfacciarsi al sistema con le API REST

Configurazione iniziale (Quickstart)

Se stai accedendo per la prima volta al nuovo servizio TCS (Sectigo Limited) è necessario leggere con attenzione le informazioni che seguono.

Definizioni

SCM = Sectigo Certificate Manager, il nome del portale per la gestione dei certificati x.509

MRAO = Master Registration Authority Officer, ruolo amministrativo di alto livello riservato ad ogni NREN che ha sottoscritto il contratto GEANT TCS. Per GARR il ruolo è affidato ai membri del Servizio GARR CS.

RAO = Registration Authority Officer, ruolo amministrativo a livello di Organizzazione che permette la gestione di dipartimenti, domini, certificati e ruoli amministrativi afferenti a tale Organizzazione

DRAO = Department Registration Authority Officer, ruolo amministrativo a livello di Dipartimento che permette la gestione di domini, certificati e ruoli amministrativi afferenti al tale Dipartimento.

Primi passi

1. E' necessario inizializzare una chiave di cifratura per ogni Organizzazione e Dipartimento creato nel Portale SCM. Si tratta di una chiave Escrow (https://it.wikipedia.org/wiki/Key_escrow) e senza un'inizializzazione non sarà possibile richiedere certificati personali tramite la GUI del Portale stesso. Per procedere scegliere dal menù principale in grigio scuro la voce Settings e poi Encryption. Selezionare la Organizzazione e premere il bottone [Inizialize Encryption]. Seguire le istruzioni a video e salvare la chiave in maniera sicura per eventuale uso futuro.
2. Per iniziare a richiedere certificati SSL server è necessario creare almeno 1 dominio (vedi la sezione "Gestione Dominii")

Registration Authority Officer

Ogni organizzazione deve indicare nel documento di adesione 2 persone a cui sarà assegnato da GARR CS il ruolo di Registration Authority Officer (RAO) all'interno del portale Sectigo.

Attivazione dei primi 2 Registration Authority Officer (RAO)

Dopo la ricezione della documentazione di Adesione il servizio GARR CS procederà sul portale SCM alla creazione della Organizzazione e contestualmente alla creazione degli account per i due RAO indicati.

Dato che il portale SCM non prevede meccanismi dinamici di attivazione degli account è necessario poter comunicare out of band i dati di login per i primi 2 RAO.

Sono previste due modalità per trasmettere le proprie credenziali (istruzioni dettagliate più sotto):

1. modalità digitale con posta elettronica firmata e cifrata
2. modalità de visu con videoconferenza e presentazione di un documento di identità

Una volta ricevute le credenziali temporanee riceverete una mail di conferma e sarà possibile accedere al portale SCM.

Trasmettere una password temporanea al servizio GARR CS con email cifrata e firmata

Cifratura

Accedere al sito https://keybase.io/encrypt e completare con i seguenti valori:

• Recipient: digitare "keybm" (Barbara Monticini) e selezionare come destinatario
• Message to encrypt: scrivere a vostra scelta una password temporanea con cui sarà attivata la vostra utenza
• Bottone [Encrypt] per eseguire la cifratura del messaggio

Copiare tutto il testo -----BEGIN PGP MESSAGE----- ... -----END PGP MESSAGE----- comprese la prima e l'ultima riga e incollarlo in un nuovo messaggio di posta.

Firma

A partire dal messaggio creato al punto precedente, apporre una firma S/MIME con il vostro client di posta e il vostro certificato digitale (è possibile richiederne uno con TCS Digicert fino al 30 Aprile o usare un certificato per la firma qualificata).

Inviare il messaggio con destinatario <garr-ca@garr.it> e oggetto "Attivazione Account RAO per <Nome> <Cognome>".

Videoconferenza con il servizio GARR CS per l'identificazione e la consegna delle credenziali

Contattare <garr-ca@garr.it> per fissare una videoconferenza in cui presentarsi e identificarsi con documento di identità (è richiesta una videocamera)

Accesso al Portale Sectigo Certificate Manager (SCM)

L'istanza del portale Sectigo Certificate Manager (SCM) per GARR è accessibile su:

https://cert-manager.com/customer/GARR

Al primo accesso il Portale proporrà il cambio password. Memorizzare la password in maniera opportuna.

Aggiunta e configurazione di Registration Authority Officer (RAO)

I RAO creati da GARR CS sono autorizzati ad aggiungere ulteriori RAO e DRAO.

Dal menù principale in grigio scuro scegliere la voce Admins. La pagina presenta la tabella degli amministratori della vostra organizzazione (sia RAO che DRAO).

Inizialmente la tabella include soltanto i due RAO nominati nel documento di adesione.

Per inserire un nuovo amministratore premere il bottone [+ Add] (per il momento sconsigliamo l'aggiunta di amministratori con il bottone [Add IdP User]).

La maschera di creazione di un nuovo amministratore (Add New Client Admin) si suddivide in 3 colonne: Credentials, Privileges, Role.

CREDENTIALS

Compilare almeno i campi obbligatori:

• Login
• Email
• Forename
• Surname
• Password
• Confirm Password

La password impostata per il nuovo amministratore dovrà essere comunicata out-of-band al collega il quale potrà in seguito accedere al portale SCM.

Una nota speciale per il campo IdP Person Id che è collegato all'autenticazione via SAML con la Federazione IDEM e va configurato solo se il vostro Ente partecipa alla Federazione e solo dopo aver configurato l'identity provider con le istruzioni riportate nell'apposita sezione dedicata.

PRIVILEGES

E' consigliabile assegnare sempre i primi 5 privilegi:

• Allow creation of peer admin users
• Allow editing of peer admin users
• Allow deleting of peer admin users
• Allow DCV
• Allow SSL details changing

Una nota speciale per gli ultimi 2 privilegi:

• Allow SSL auto approve: se non abilitato, le richieste di certificati fatte da questo RAO dovranno essere sempre approvate dai RAO creati da GARR CS.
• WS API use only: usare solo se il RAO che si vuole creare non è una persona, ma un utente ad hoc da utilizzare in programmi e script che consumino le API di Sectigo accessibili via Web Service. Se il controllo viene impostato a true il RAO non potrà accedere al Portale in modalità GUI.

ROLE

Dopo aver premuto su Expand All selezionare la casella indicante ll'opportuna Organization che si trova sotto a:

• + RAO Admin - SSL
• + RAO Admin - Client Certificate
• + RAO Admin - Code Signing

E' possibile assegnare al RAO tutti e 3 i ruoli oppure un sottoinsieme a seconda delle necessità. La configurazione può essere cambiata successivamente.

Per modificare un amministratore già creato in precedenza selezionare dalla tabella degli amministratori la radio button relativa e premere il bottone [Edit].

La maschera di modifica di un amministratore (Edit Client Admin) è sostanzialmente identica alla maschera di creazione nuovo amministratore.

La differenza riguarda la sezione della password in cui è presente il link Reset password.

Reset della password

Il reset della password di un account RAO può essere fatto da un qualsiasi altro RAO della stessa Organizazion. Dal menù Admins selezionare il nome dell'amministratore da modificare, premere il bottone [Edit] e seguire il link Reset password. La nuova password dovrà essere comunicata out-of-band al collega.

Gestione Dominii

Per emettere certificati è prima di tutto necessario creare un dominio, delegarne la gestione alla propria organizzazione e validarlo. Vediamo come.

Creazione dominio

Dal menù principale selezionare Settings, poi Domains, poi Delegation e premere il bottone [+ Add].

Nella finestra che si apre inserire il dominio alla voce Domain e selezionare l'organizzazione o il dipartimento a cui delegare il dominio e premere il bottone [OK].

Di default tutti i tipi di certificati disponibili sono abilitati per il dominio, se si vuole disabilitarne alcuni eliminare la spunta dalla casella corrispondente.

Una volta creato il dominio, si deve attendere che delega di gestione all'organizzazione o al dipartimento sia approvata dagli MRAO. Il richiedente riceverà una notifica non appena la delega sarà stata approvata.

Validazione dominio

Dal menù principale selezionare Settings, poi Domains, poi DCV (che sta per Domain Control Validation), selezionare il dominio da validare nella tabella e premere il bottone [DCV] .

Nella finestra che si apre selezionare il metodo di validazione del dominio. Le scelte possibili sono Email, HTTP, HTTPS, CNAME, a seconda della scelta sono presentati requisiti diversi:

• Email: selezionare l'indirizzo a cui Sectigo invierà il messaggio di controllo.

• HTTP: seguire le istruzioni che consistono nel creare un file txt contenente un codice generato da Sectigo e posizionarlo in una location well-known sul server web attivato sul dominio da validare.
• HTTPS: come per HTTP, ma la location sarà in HTTPS.
• CNAME: seguire le istruzioni che consistono nel creare un record DNS di tipo CNAME con il valore indicato sul dominio da validare.

Una volta scelto il metodo ed annotate le istruzioni premere il bottone [Submit] per avviare la validazione. Nella schermata successiva sarà possibile confermare la scelta premendo il bottone [OK], o cancellare la richiesta di validazione e ripartire da capo premendo il bottone [Reset]. Anche una volta chiusa la finestra di validazione si potrà cancellare la richiesta, selezionando nuovamente il dominio, premendo il bottone [DCV] e poi [Reset] come già detto.

Emissione Certificati

Quanto segue riguarda l'emissione di certificati tramite portale SCM da parte degli Admins, ovvero RAO e DRAO.

Prima di procedere con la richiesta di certificati GEANT EV SSL e GEANT EV Multi-Domain consigliamo di consultare la sezione dedicata più sotto.

Richiesta SSL Certificate

Dal menù principale selezionare Certificates, poi SSL Certificates e premere il bottone [+Add].

Nella finestra che si apre (Request New SSL Certificate) si deve scegliere la modalità di creazione tra:

• Manual creation of CSR: creare la private key e la CSR (Certificate Submission Request) in locale e copiare la CSR sul form della schermata successiva.
• Auto generation of CSR: la CSR e la private key sono create sul portale. Per scaricare la private key è necessario avere abilitato l'autenticazione ad SCM tramite certificato.
• Auto generation of CSR with auto installation: riguarda le organizzazioni che si avvalgono dei Network Agents --- vedi documentazione Sectigo.
• Auto generation of CSR in Azure Key Vault: riguarda le organizzazioni che hanno configurato la Azure Key Vault.

Manual creation of CSR

Una volta selezionata la modalità Manual creation of CSR, premere il bottone [Next >], incollare la CSR nel form della nuova schermata e premere il bottone [Next >].

Nella schermata successiva vanno inserite le informazioni necessarie all'emissione. Una volta selezionati Organization e Department, va scelto il Certficate Type, selezionare GEANT OV SSL per un certificato SSL per un solo nome di dominio o GEANT OV Multi-Domain per aggiungere SAN (Subject Alternative Names).

Importante: nei certificati GEANT OV SSL viene aggiunto in automatico un Subject Alternative Names che riporta il valore del CN ed eventualmente la versione con prefisso www. . Per questo motivo consigliamo di richiedere certificati GEANT OV Multi-Domain anche quando la richiesta presenta un solo fqdn.

Completare la richiesta indicando il periodo di validità in Certificate Term, il Server Software che determinerà il formato in cui scaricare il certificato ed eventuali Subject Alternative Names nel caso si stia richiedendo un certificato GEANT OV Multi-Domain.

Nella schermata successiva ci verrà richesto se abilitare o meno il rinnovo automatico, Enable auto renewal of this certificate, e quanti giorni prima iniziareil processo. Il rinnovo automatico è disponibile solo per gli Admin (RAO e DRAO) per cui è stato abilitato.

Certificati Extended Validation (GEANT EV SSL e GEANT EV Multi-Domain)

Nonostante questo tipo di certificato possa essere richiesto attraverso il modulo standard di richiesta certificati vi preghiamo di considerare la possibilità di validare a priori l'emissione dei certificati EV per la vostra Organizzazione grazie al meccanismo chiamato EV Anchor.

Come nei precedenti contratti TCS ricordiamo che il tipo EV richiede, per l'emissione di un certificato, un livello di validazione molto alto e questo può creare lunghi tempi di attesa. EV Anchor, una volta ottenuta, permette di velocizzare la validazione dei successivi certificati EV creando appunto un'ancora riutilizzabile dall'Organizzazione. EV Anchor ha validità di un anno.

Cosa succede se non sfrutto il meccanismo EV Anchor? Per ogni nuova richiesta di certificato EV si dovrà contattare il team di validazione Sectigo attraverso il sistema di ticketing https://sectigo.com/support-ticket.

La mia organizzazione vuole attivare EV Anchor, cosa dobbiamo fare? Stabilire l'elenco dei domini per i quali il vostro Ente è interessato a ottenere certificati EV e assicurarsi di aver creato i domini all'interno del portale SCM. In seguito contattare <garr-ca@garr.it> per gli ulteriori passaggi.

Richiesta Client Certificate

La richiesta di Client Certificate da parte degli Admin via portale SCM è piuttosto scomoda e non sarà la modalità principale, ma è utile fino a che non sarà disponibile la richiesta via autenticazione federata SAML.

Per richiedere un Client Certificate per un membro della propria organizzazione selezionare Certificates, poi Client Certificates e premere il bottone [+Add].

Nella finestra che si apre devono essere indicati o confermati Organization e Department, alla voce Domain va selezione il dominio su cui emettere il certificato, in Email Address va inserita la parte locale (a sinistra della @domain) dell'indirizzo di posta che sarà associato al certificato, in Common Name va inserito il nome completo dell'utente, in First Name il nome proprio ed in Last Name il cognome. Una volta terminato l'inserimento premere il bottone [OK].

Selezionare la richiesta appena creata spuntando il radio button nell'elenco e premere il bottone [Certificates]. Nella finestra che si apre premere il bottone [Send Invitation]. Si aprirà un'ulteriore finestra dove deve essere indicato il Certificate Type ed il periodo di validità, Term, da 1 a 3 anni. I certificati di tipo GEANT IGTF-* sono per uso GRID, mentre per emettere un normale certificato client per uso personale va selezionato GEANT Personal Certificate, che è anche il default. Una volta premuto il bottone [OK], l'utente riceverà una mail di invito da parte di Sectigo contenente un link dove potrà scaricare il certificato in formato P12 dopo aver indicato la password con cui proteggere la private key del certificato e la passphrase per il suo utilizzo.

Richiesta Code Signing Certificate

Questa sezione della guida verrà documentata nella prossima release.

Gestione Organizzazione

Modifica della configurazione dell'Organizzazione

Dal menù principale in grigio scuro selezionare Settings e poi scegliere Organizations. Nella tabella selezionare il radiobutton relativo alla Organization da modificare e premere il bottone [Edit].

Si aprirà una finestra pop-up (Edit Organization:) composta dalle seguenti sezioni: General, Client Certificate, SSL Certificate, Code Signing Certificate, Email Template.

E' possibile modificare solo parte della configurazione ed in particolare nella sezione SSL Certificate è possibile configurare Self Enrollment per gli utenti non amministrativi e SSL Types [Customize] per ridurre il numero dei tipi di certificati richiedibili via GUI e tramite la form Self Enrollment. Per approfondimenti su Self Enrollment vedi la sezione Richiesta certificati SSL tramite codice o autenticazione SAML.

Aggiunta e configurazione Department

Dal menù principale in grigio scuro selezionare Settings e poi scegliere Organizations. Nella tabella selezionare il radiobutton relativo alla Organization su cui operare e premere il bottone [Departments].

Si aprirà una finestra pop-up (Departments) che permette di aggiungere nuovi dipartimenti, visualizzare e modificare i dipartimenti già creati.

Aggiungere un nuovo Dipartimento

Premendo il bottone [Add] si aprirà un'ulteriore finestra di pop-up (Add New Department) composta dalle seguenti sezioni: General, Client Certificate, SSL Certificate, Code Signing Certificate.

In General è possibile assegnare il nome al nuovo Department.

In SSL Certificate è possibile configurare Self Enrollment per gli utenti non amministrativi e SSL Types [Customize] per ridurre il numero dei tipi di certificati richiedibili via GUI e tramite la form Self Enrollment. Per approfondimenti su Self Enrollment consultare la sezione Richiesta certificati SSL tramite codice o autenticazione SAML.

In Client Certificate disabilitare la checkbox Allow Key Recovery by Master Administrators.

In Code Signing Certificate è possibile abilitare tale tipo di certificato per questo Department se necessario.

Premere [OK] per salvare la configurazione del nuovo Department.

Visualizzare e modificare i dipartimenti già creati

Selezionando il radiobutton relativo al Department che si vuole visualizzare sarà possibile modificarlo (Edit), rimuoverlo definitivamente (Delete), aggiungere e consultare i domini delegati (Domains) e associarvi account ACME (ACME Accounts).

Per la gestione dei domini associati ad un Department fare riferimento alla sezione Gestione Dominii.

Aggiunta e configurazione DRAO

Prima di poter aggiungere un ruolo DRAO è necessario aver creato almeno un Department.

Possono aggiungere e modificare DRAO in un determinato Department tutti i ruoli RAO e i DRAO di quel Department .

Per aggiungere un amministratore DRAO seguire le istruzioni di creazione di un amministratore RAO eseguendo la seguente variazione per la sezione Role:

ROLE

Dopo aver premuto su Expand All selezionare la checkbox indicante il Department opportuno che si trova sotto a:

+ DRAO Admin - SSL

+ DRAO Admin - Client Certificate

+ DRAO Admin - Code Signing

E' possibile assegnare ad un DRAO tutti e 3 i ruoli oppure un sottoinsieme a seconda delle necessità. La configurazione può essere cambiata successivamente.

Per modificare un amministratore già creato in precedenza selezionare dalla tabella degli amministratori la radio button relativa e premere il bottone [Edit].

La maschera di modifica di un amministratore (Edit Client Admin) è sostanzialmente identica alla maschera di creazione nuovo amministratore.

La differenza riguarda la sezione della password in cui è presente il link Reset password.

Reset della password

Il reset della password di un account DRAO può essere fatto da qualsiasi DRAO dello stesso Department e dai RAO della stessa Organization. Dal menù Admins selezionare il nome dell'amministratore da modificare, premere il bottone [Edit] e seguire il link Reset password. La nuova password dovrà essere comunicata out-of-band al collega.

Richiesta certificati SSL tramite codice o autenticazione SAML (per utenti non admin)

È possibile richiedere certificati SSL con autenticazione basata su codice o su autenticazione federata SAML via IDEM. In questo modo sarà possibile far richiedere i certificati anche ad utenti che non siano RAO o DRAO. Nel portale SCM questa funzionalità è definita Self Enrollment.

Per abilitare il Self Enrollment selezionate Settings, poi Organizations, selezionare l'organizzazione e premere il bottone [Edit].

Nella finestra che si aprirà selezionare SSL Certificate':

• spuntare la casella Self Enrollment ed inserire un codice di accesso in Access Code per abilitare il Self Enrollment basato su codice. L'accesso avverrà tramite la URL https://cert-manager.com/customer/GARR/ssl ed il codice indicato, il codice andrà comunicato out-of-band agli utilizzatori. Il codice potrà essere utilizzato da chiunque e per questo motivo sconsigliamo l'utilizzo di questa modalità.
• spuntare la casella Self Enrollment ed inserire un codice di accesso in Access Code e poi spuntare Self Enrollment via SAML per abilitare il Self Enrollment basato su SAML. L'accesso averrà tramite la URL generata e mostrata sotto il campo Token e l'autenticazione SAML, in questo modo l'accesso sarà limitato ai soli utenti della propria organizzazione e tutti gli accessi saranno autenticati su base personale. Il codice Access Code è obbligatorio ma sarà ignorato.

Raccomandiamo di non spuntare la casella Automatically Approve Self Enrollment Requests per mantenere il controllo delle richieste di certificati SSL richiesti tramite Self Enrollment. È inoltre possibile limitare i tipi di certificati che si possono richiedere, così come i formati in cui scaricarli.

Una volta terminata la configurazione del Self Enrollment premendo il bottone [OK], andranno distribuite le URL per la richiesta dei certificati.

SSL Certificate Enrollment: accesso ed emissione

Gli utenti che accederanno alle URL del SSL Certificate Enrollment dovranno autenticarsi tramite il proprio Identity Provider o con il codice di accesso loro fornito.

Una volta acceduti dovranno selezionare il Certificate Type, il Certificate Term ed il Server Software per cui stanno richiedendo il certificato, incollare la Certificate Submission Request nel campo CSR, mentre i campi rimanenti sono opzionali. Una volta premuto il bottone [ENROLL] il RAO riceverà una notifica di richiesta e potrà approvare la richiesta del certificato dal menù Certificates del portale SCM.

Una volta approvata la richiesta ed emesso il certificato, l'utente riceverà infine un messaggio di posta elettronica contenente i link per scaricare il certificato richiesto.

Configurazione SAML

Il portale SCM è disponibile in eduGAIN ed è accessibile tramite tutti gli Identity Provider della Federazione IDEM che sono pubblicati in eduGAIN e consumano correttamente i metadata di federazione (vedi Metadata).

Le organizzazioni che intendono abilitare il proprio Identity Provider per l'accesso al portale SCM devono rilasciare i seguenti attributi al Service Provider di Sectigo (https://cert-manager.com/shibboleth):

• eduPersonPrincipalName
• email
• displayName (facoltativo)
• givenName (facoltativo)
• sn (facoltativo)

Di seguito un esempio di configurazione per Shibboleth Identity Provider 3.x.

<AttributeFilterPolicy id="GARR-TCS-4">
  <PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="https://cert-manager.com/shibboleth"/>
  <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="email">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="givenName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="sn">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
</AttributeFilterPolicy>

Per verificare se il vostro Identity Provider stia rilasciando correttamente gli attributi necessari, Sectigo mette a disposizione una pagina di controllo al seguente indirizzo:

https://cert-manager.com/customer/garr/ssocheck/

Una volta configurato e verificato il rilascio degli attributi, l'accesso federato via SAML andrà abilitato nelle sezioni del portale SCM che lo prevedono (ad esempio per il Self Enrollment via SAML).

ACME account

Questa sezione della guida verrà documentata nella prossima release.

Fare riferimento alla capitolo "Using the Sectigo ACME Service" della guida SCM - Sectigo Certificate Manager Administrator's Guide