Protezione dell'integrazione con password o certificati
È possibile effettuare l'autenticazione a Mastercard Gateway utilizzando le password o i certificati SSL.
Autenticazione con password
È possibile consentire l'accesso protetto alle integrazioni Mastercard GatewayDirectAPI e Batch mediante password. La password generata dal sistema è un valore a 16 byte, generato casualmente e codificato come stringa esadecimale. Sebbene sia di lunghezza e qualità sufficienti a resistere a qualsiasi tentativo di violazione, è consigliabile proteggerla con le stesse modalità previste per le password utente e gli altri dati sensibili.
La password è segreta e deve essere nota solo all'esercente e a Mastercard. È importante che resti riservata per proteggere il conto.
Generazione di password per DirectAPI
È possibile generare la propria password dell'API in Merchant Administration. Un prerequisito necessario è che il profilo dell'esercente sia abilitato per i privilegi API, Batch e "Utilizza l'autenticazione con password".
Per accedere a Merchant Administration, sono necessarie le credenziali di accesso. Le credenziali di accesso dell'amministratore verranno fornite dal your payment service provider una volta registrati con il gateway. In qualità di amministratore, per generare la password API è possibile creare un nuovo operatore con le autorizzazioni.
- Accedere a https://eu-gateway.mastercard.com/ma con le credenziali di accesso dell'amministratore.
- Passare a Amministrazione > Operatori
- Creare un nuovo operatore completando tutti i campi obbligatori. Assegnare il privilegio "È possibile configurare le impostazioni dell'integrazione" per consentire all'operatore di generare la password API.
- Uscire da Merchant Administration e accedere di nuovo a Merchant Administration come nuovo operatore.
- Passare a Amministrazione > Impostazioni di integrazione dell'API dei servizi Web > Modifica.
- Fare clic su Genera nuovo e selezionare la casella Abilita accesso integrazione tramite password.
- Questa è la password API da utilizzare per autenticare le richieste API effettuate dal proprio server Web al gateway.
- Fare clic su Invia.
È sempre necessario disporre di almeno una password generata e abilitata ma è possibile impostare fino a due password. Per motivi di sicurezza, è consigliabile cambiare periodicamente la password. Per configurare l'applicazione, deve essere utilizzata una sola password. La seconda funge da riserva in caso di aggiornamento della password.
Una volta generata la password, è necessario includerla in tutte le richieste di transazione dirette a Mastercard Gateway. Se la richiesta viene inviata mediante il protocollo REST-JSON, deve includere l'id utente e la password nell'intestazione di autenticazione di base HTTP standard. Con NVP, è necessario fornire parametri aggiuntivi nella richiesta, apiUsername
e apiPassword
, per utilizzare l'API.
Per effettuare l'autenticazione come esercente, il nome (apiUsername
per NVP e id utente per REST-JSON) e la password (apiPassword
per NVP e password per REST-JSON) devono contenere rispettivamente 'merchant.<your gateway merchant ID>' e la password generata dal sistema.
A partire da DirectAPI v13, è obbligatorio fornire sia il nome che la password. Nelle versioni precedenti alla 13 era obbligatorio lasciare il nome vuoto e fornire solo la password.
Riferimento API per Password [REST][NVP]
Autenticazione con certificato
L'autenticazione con certificato attualmente non è supportata con le API
Batch o le
Reporting.
Notare che il nome dell'host per l'autenticazione con certificato è diverso da
https://eu-gateway.mastercard.com/api. Si prega di contattare il your payment service provider per il nome dell'host.
Con l'autenticazione con certificato, è necessario presentare un certificato per autenticarsi in Mastercard Gateway. I certificati sono generalmente emessi da una delle tante organizzazioni che fungono da autorità di certificazione (CA). Questo modello di autenticazione è un componente dell'Infrastruttura a chiave pubblica (PKI) in cui la sicurezza si ottiene mediante la riservatezza, l'integrità, il non ripudio e l'autenticazione. La CA dichiara che la chiave pubblica associata al certificato è corretta, appartiene alla persona o all'entità dichiarata (ad esempio è autentica), e non è stata danneggiata o sostituita da malintenzionati.
Il meccanismo di autenticazione mediante certificato richiede sia il client (il server Web) sia il server (server HTTP di Mastercard Gateway) per presentare i certificati che consentono di autenticarsi. Il workflow di questa procedura, definita autenticazione reciproca, è illustrato di seguito.
Quando ci si connette a Mastercard Gateway utilizzando l'autenticazione con certificato, si verificano le situazioni seguenti:
- Il client richiede la connessione a una risorsa protetta sul server. Questo accade per ogni richiesta di transazione avviata dal client.
- Il server presenta la propria catena di certificati al client.
- Il client verifica il certificato del server utilizzando un archivio affidabile, che contiene le autorità di certificazione all'origine affidabili. Il client convalida il percorso del certificato in un certificato all'origine CA affidabile.
- Se riesce, il client invia la propria catena di certificati al server, che è contenuto in un archivio chiavi.
A seconda del software client del server Web, l'archivio affidabile e l'archivio chiavi spesso coincidono.
- Il server verifica il certificato del client utilizzando la serie completa di certificati CA all'origine affidabili/approvati caricati sul server. Vengono eseguiti i seguenti controlli:
- Verifica che il certificato sia in formato X.509.
- Convalida il percorso del certificato in un certificato all'origine CA affidabile.
- Esegue il controllo CRL o OCSP (Online Certificate Status Protocol) per verificare che il certificato non sia stato revocato.
- Verifica che il certificato non sia scaduto.
Se il server HTTP ha convalidato il certificato client, la catena completa di certificati client viene passata a DirectAPI per la verifica. In caso contrario, vengono restituiti messaggi di errore del certificato SSL standard dal server HTTP.
La verifica viene eseguita sia a livello di server HTTP sia a livello di DirectAPI. Il server HTTP esegue la validazione del certificato SSL completa e DirectAPI esegue l'autenticazione con certificato a livello aziendale.
- Il DirectAPI esegue i controlli elencati di seguito.
- Estrae la ragione sociale del soggetto del certificato client e verifica che corrisponda a quella registrata per l'esercente nel database La ragione sociale del soggetto del certificato deve contenere la denominazione sociale dell'esercente.
- Verifica che il certificato client abbia un'estensione Key-Usage, contrassegnata come critica, che include l'autenticazione client tra gli usi consentiti del certificato.
- Esegue una semplice validazione del certificato client in un certificato all'origine CA contenuto nella serie di CA consentite. Ciò significa che l'applicazione DirectAPI deve contenere il certificato all'origine dell'autorità di certificazione utilizzato per emettere e firmare il certificato client.
La serie iniziale di CA consentite è stabilita da Mastercard.
- Verifica che il certificato presentato corrisponda allo stato del profilo dell'esercente. Un profilo di produzione accetterà solo i certificati di produzione, mentre un profilo di prova accetterà i certificati di prova o di produzione.
Se i passaggi 1-4 vengono eseguiti correttamente, l'autenticazione dell'esercente viene considerata riuscita, in caso contrario la connessione viene rifiutata con la restituzione di un messaggio di errore appropriato.
- Se tutti i controlli descritti nei passaggi 5 e 6 vengono eseguiti correttamente, il server accetta la connessione e consente la prosecuzione dell'operazione di richiesta.
È possibile scegliere di presentare il certificato client o un certificato diverso per autenticarsi quando il pagante accede all'applicazione. In questa interazione, il server Web funge da server e il pagante da client. L'integrazione con questo meccanismo di autenticazione può offrire ai paganti l'ulteriore garanzia che la transazione viene eseguita con un'azienda legittima.
Come ottenere il certificato di produzione e prova da una CA
Prima di attivare il certificato di produzione, è possibile sviluppare e testare l'autenticazione PKI con un certificato di prova. Ciò può essere utile, ad esempio, quando non si desidera condividere il certificato di produzione e la chiave privata con un integratore web di terze parti.
È importante che il certificato che si ottiene dalla CA scelta soddisfi i requisiti Mastercard di implementazione dei certificati. Di seguito sono elencati alcuni punti chiave da considerare quando si ottiene il certificato SSL.
- Il certificato deve essere nel formato X.509.
- Il certificato deve avere un'estensione Key-Usage, contrassegnata come critica e includere l'autenticazione client tra gli usi consentiti del certificato.
- Il certificato deve essere emesso da una CA approvata da Mastercard. Contattare Mastercard per ottenere un elenco di CA approvate.
- La ragione sociale del soggetto del certificato deve contenere il nome di dominio completo, con o senza un carattere jolly, del sito Web per il quale si intende acquistare il certificato.
- Il campo dell'organizzazione (O) del soggetto deve contenere l'organizzazione dell'esercente.
Configurazione dei certificati esercente in Gestore degli esercenti
Dopo aver ottenuto il certificato da una CA affidabile, il your payment service provider dovrà configurare il certificato di produzione e/o di prova in Gestore degli esercenti durante la configurazione di tutte le impostazioni API per il profilo dell'esercente sul gateway. Se necessario, un certificato esercente può essere collegato a più profili di esercente della stessa o di più aziende. Per ulteriori informazioni su come configurare i certificati dell'esercente in Gestore degli esercenti, vedere la sezione Configurazione API nella Guida per l'utilizzo di Gestore degli esercenti.
Il sito controlla l'elenco di certificati all'origine CA affidabili utilizzati per verificare i certificati esercente. Per consentire la verifica dei certificati, il sistema acquisisce la versione codificata PEM del certificato di produzione attraverso Gestore degli esercenti. La ragione sociale del soggetto viene estratta da questo certificato e verificata rispetto alla ragione sociale del soggetto del certificato presentato durante l'handshake SSL.
Fintantoché si rinnova il certificato con la stessa ragione sociale del certificato scaduto, non è necessario aggiornare la configurazione in Gestore degli esercenti. in quanto per convalidare il certificato il sistema salva solo la Ragione sociale del soggetto del certificato.
Integrazione del certificato SSL nell'applicazione
Dopo aver configurato il certificato con il profilo dell'esercente, è necessario eseguire i passaggi indicati di seguito per installare il certificato nell'ambiente di lavoro.
- Rendere la chiave privata e il certificato disponibili per il software client SSL che stabilisce la connessione SSL a Mastercard Gateway. A seconda del software, potrebbe essere necessario convertire la chiave privata, il certificato e la catena di certificati associata in un formato supportato. Ad esempio le chiavi private e i certificati vengono spesso forniti in file di testo, in formato PEM, con la chiave privata protetta da una password. In Java questi file vengono generalmente caricati in un archivio chiavi Java. Consultare la documentazione del software per conoscere i formati supportati.
Per gli ambienti Java e .NET, si consiglia di convertire i file PEM in PKCS12.
- In quasi tutti i casi, la CA emittente per il certificato fornisce anche certificati aggiuntivi, noti come catena di certificati. Tali certificati devono essere forniti a Mastercard Gateway durante l'handshake SSL per consentire al gateway di convalidare il certificato. Il software client SSL riceverà istruzioni su come e dove inserire i certificati.
- Una semplice prova per verificare se si dispone di tutti i certificati necessari consiste nel caricarli in un browser Web, come Internet Explorer, Firefox o Safari, accedere all'URL Check Gateway DirectAPI del gateway e recuperare lo stato del gateway. Se i certificati sono caricati correttamente, quando si accede all'URL Check Gateway, viene visualizzata la richiesta di selezionare/accettare il certificato da utilizzare per connettersi con il gateway. Se viene visualizzata la richiesta e si riesce a stabilire la connessione, si otterrà la risposta riportata di seguito. {status: "OPERATING"}.
Per la maggior parte dei browser è richiesta anche la conversione dei certificati formattati PEM. Pertanto, utilizzando il browser per testare i certificati, si potrà verificare anche se è possibile convertire correttamente i certificati nel formato appropriato. Internet Explorer supporta i seguenti formati: PKCS#12, PKCS#7 e Archivio certificati serializzati Microsoft. La utility OpenSSL è uno strumento eccellente per la conversione tra i formati PEM e i formati basati su PKCS.
Riferimento API per URL Check Gateway [REST][NVP]
Alternanza di certificati
Esistono vari motivi per passare dal certificato esistente a un nuovo certificato. Ad esempio potrebbe essere necessario aggiornare i certificati se cambia il nome della società o per passare da un certificato di prova a un certificato di produzione.
Per passare a un nuovo certificato, il your payment service provider deve aggiungere il nuovo certificato come certificato principale mentre il vecchio certificato diventa un certificato aggiuntivo. È possibile avere uno o più certificati aggiuntivi. Gli esercenti configurati per l'uso della nuova serie di certificati possono eseguire l'autenticazione in DirectAPI utilizzando indifferentemente il certificato precedente o quello nuovo. Si tratta di una configurazione provvisoria che ha validità fino a quando tutte le integrazioni non sono state aggiornate per l'uso del nuovo certificato. Per ulteriori informazioni su come aggiungere altri certificati esercente, vedere la sezione Configurazione API nella Guida per l'utilizzo di Gestore degli esercenti.
Autenticazione della sessione
L'autenticazione della sessione utilizza la sessione di pagamento del gateway, un contenitore temporaneo per i campi delle richieste per autenticare l'esercente. Poiché la sessione di pagamento viene creata da un esercente autenticato (tramite l'autenticazione con password/certificato), il pagante può utilizzarla per interazioni con il gateway, come l'esecuzione di operazioni di autenticazione.
Questo meccanismo di autenticazione consente ai paganti di fornire i propri dettagli di pagamento direttamente al gateway. I dati del pagante vengono ottenuti tramite un'interazione lato client con il gateway, tramite il browser del pagante o un'app sul dispositivo mobile del pagante. Fornisce un semplice modello di integrazione per ottenere in modo sicuro i dati del pagante richiesti poiché le richieste API al gateway vengono eseguite direttamente dal client piuttosto che dal server.
Utilizza un meccanismo di autenticazione HTTP di base (simile all'autenticazione con password) in cui è necessario fornire "merchant.<your gateway merchant ID>;>" nella parte userid e l'ID sessione nella parte password.
L'autenticazione della sessione è disponibile solo a partire da DirectAPI versione 55 e successive.
Per utilizzare questo tipo di autenticazione:
- Creare una sessione inviando una richiesta API Create Session dal server al server del gateway. Questa operazione restituisce un identificativo di sessione.
- Inviare la richiesta Update Session utilizzando l'autenticazione di sessione per aggiungere eventuali dati rilevanti alla sessione creata nel passaggio 1.
- Fornire la sessione al pagante.
Transazioni supportate
Le seguenti operazioni supportano l'autenticazione utilizzando un ID sessione.
- Update Session
- Initiate Authentication
- Authenticate Payer
Campi di input e output del pagante
Nelle interazioni autenticate con la sessione con il gateway, il pagante è limitato a un sottoinsieme di campi all'interno di un'operazione API. Questi sono indicati come campi di input del pagante. Se si forniscono campi diversi dai campi di input del pagante in una richiesta autenticata per la sessione, la richiesta viene rifiutata. Ad esempio, il pagante non può inviare dati come l'importo dell'ordine.
Analogamente ai campi di input del pagante, il gateway consente di restituire solo determinati campi nella risposta per interazioni autenticate con il gateway. Questi sono indicati come campi di output del pagante — vengono restituiti solo i campi che devono essere visualizzati da un pagante su un browser o un'app per eseguire una transazione. Ad esempio, i dati sensibili alla sicurezza come l'identificativo di sessione non vengono restituiti.
Update Session
Campi di input del pagante
- billing.address.city
- billing.address.company
- billing.address.country
- billing.address.postcodeZip
- billing.address.stateProvince
- billing.address.stateProvinceCode
- billing.address.street
- billing.address.street2
- browserPayment.preferredLanguage
- correlationId
- customer.dateOfBirth
- customer.email
- customer.firstName
- customer.lastName
- customer.mobilePhone
- customer.nationalId
- customer.phone
- customer.taxRegistrationId
- device.browser
- device.browserDetails.3DSecureChallengeWindowSize
- device.browserDetails.acceptHeaders
- device.browserDetails.colorDepth
- device.browserDetails.javaEnabled
- device.browserDetails.language
- device.browserDetails.screenHeight
- device.browserDetails.screenWidth
- device.browserDetails.timeZone
- device.fingerprint
- device.hostname
- device.ipAddress
- device.mobilePhoneModel
- gatewayEntryPoint
- locale
- merchant
- order.id
- order.walletProvider
- session.version
- shipping.contact.email
- shipping.contact.firstName
- shipping.contact.lastName
- shipping.contact.mobilePhone
- shipping.contact.phone
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.expiry.month
- sourceOfFunds.provided.card.expiry.year
- sourceOfFunds.provided.card.mobileWallet.emv.emvData
- sourceOfFunds.provided.card.nameOnCard
- sourceOfFunds.provided.card.number
- sourceOfFunds.provided.card.provided.card.prefix
- sourceOfFunds.provided.card.securityCode
- sourceOfFunds.token
- sourceOfFunds.type
- transaction.acquirer.customData
- transaction.acquirer.traceId
- transaction.id
Campi di output del pagante
- correlationId
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.amount
- order.currency
- order.customerNote
- order.customerReference
- order.invoiceNumber
- risultato
- session.updateStatus
- session.version
Initiate Authentication
Campi di input del pagante
- apiOperation
- correlationId
- order.walletProvider
- session.id
- session.version
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.number
- sourceOfFunds.token
- sourceOfFunds.type
Campi di output del pagante
- authentication.3ds2.methodCompleted
- authentication.3ds2.methodSupported
- authentication.redirect.customized.3DS.methodPostData
- authentication.redirect.customized.3DS.methodUrl
- authentication.redirectHtml
- authentication.version
- correlationId
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.authenticationStatus
- order.currency
- order.status
- response.gatewayCode
- response.gatewayRecommendation
- risultato
- sourceOfFunds.provided.card.number
- sourceOfFunds.type
- transaction.authenticationStatus
- versione
Authenticate Payer
Campi di input del pagante
- apiOperation
- billing.address.city
- billing.address.company
- billing.address.country
- billing.address.postcodeZip
- billing.address.stateProvince
- billing.address.stateProvinceCode
- billing.address.street
- billing.address.street2
- correlationId
- device.browser
- device.browserDetails.3DSecureChallengeWindowSize
- device.browserDetails.acceptHeaders
- device.browserDetails.colorDepth
- device.browserDetails.javaEnabled
- device.browserDetails.language
- device.browserDetails.screenHeight
- device.browserDetails.screenWidth
- device.browserDetails.timeZone
- device.ipAddress
- order.walletProvider
- session.id
- session.version
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.expiry.month
- sourceOfFunds.provided.card.expiry.year
- sourceOfFunds.provided.card.number
- sourceOfFunds.provided.card.securityCode
Campi di output del pagante
- authentication.3ds2.acsReference
- authentication.3ds2.challenge.signedContent
- authentication.3ds2.methodCompleted
- authentication.3ds2.methodSupported
- authentication.3ds2.sdk.interface
- authentication.3ds2.sdk.timeout
- authentication.3ds2.sdk.uiType
- authentication.payerInteraction
- authentication.redirect.customized.3DS.acsUrl
- authentication.redirect.customized.3DS.cReq
- authentication.redirect.domainName
- authentication.redirectHtml
- authentication.version
- correlationId
- encryptedData.ciphertext
- encryptedData.nonce
- encryptedData.tag
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.authenticationStatus
- order.currency
- order.status
- response.gatewayCode
- response.gatewayRecommendation
- risultato
- sourceOfFunds.provided.card.number
- sourceOfFunds.type
- transaction.authenticationStatus
- versione
Protezione delle informazioni del pagante mediante SSL
Tutti i siti Web che raccolgono informazioni sensibili o riservate devono proteggere i dati che vengono trasferiti tra il browser Internet del pagante, l'applicazione e Mastercard Gateway.
SSL è una tecnologia di sicurezza utilizzata per proteggere le transazioni tra il server Web e il browser Internet. È inclusa la protezione di tutte le informazioni (come il numero della carta di credito di un pagante) trasferite da un browser Internet a un server Web, come l'applicazione Web "Shop & Buy". SSL protegge i dati inviati tramite Internet impedendone l'intercettazione e la visualizzazione da parte di destinatari indesiderati.
Quando si implementa il Direct Payment è necessario assicurarsi che l'applicazione presenti un modulo protetto che utilizza SSL. Sarebbe inoltre opportuno utilizzare un modulo protetto nell'applicazione quando si acquisiscono informazioni riservate, come gli indirizzi del pagante.
Come fanno i paganti a sapere se il mio sito utilizza SSL?
Quando un pagante si connette all'applicazione utilizzando SSL, può vedere che http:// cambia in https:// e un piccolo lucchetto color oro visualizzato nel browser Internet, ad esempio:
Ogni volta che un browser Internet si connette a un server Web (sito Web) su https://, la comunicazione con Mastercard Gateway sarà crittografata e protetta. È possibile avvisare i paganti di questo in modo che sappiano cosa cercare quando effettuano transazioni nel sito Web.
Tabella di riferimento delle differenze principali tra i modelli di sicurezza
Nella tabella che segue vengono illustrate alcune differenze principali tra i modelli di autenticazione tramite password e quelli che prevedono l'uso di un certificato, allo scopo di fornire un aiuto nella scelta della soluzione di autenticazione che meglio soddisfa i requisiti di autenticazione della propria azienda.
|
Autenticazione con password |
Autenticazione con certificato |
Quando usarlo
|
Nelle piccole aziende, in cui è sufficiente l'autenticazione semplice. |
Nelle grandi aziende, in cui il costo dell'infrastruttura per l'implementazione della PKI è minimo rispetto alla sicurezza che si ottiene utilizzando un livello di autenticazione più elevato |
Abilità tecniche richieste
|
È richiesta la conoscenza dell'autenticazione HTTP di base |
È richiesta la conoscenza dell'autenticazione reciproca e della PKI che utilizza le autorità di certificazione |
Semplicità di integrazione
|
Facile da integrare |
L'impostazione del file di archivio chiavi e altra infrastruttura possono rendere più complessa l'integrazione. |
Livello di autenticazione |
Moderato |
Alto |
Costo |
È il metodo di autenticazione più economico |
Comporta costi aggiuntivi, come il costo di sottoscrizione dell'autorità di certificazione per l'emissione di certificati. |
Vantaggi |
Ideale per gli esercenti più piccoli, per i quali il costo dell'integrazione rappresenta un fattore importante e i modelli aziendali non richiedono livelli di sicurezza più elevati. |
L'autenticazione reciproca SSL garantisce un livello molto elevato di sicurezza e viene considerata una procedura ottimale di settore. Ottimizza le prestazioni di autenticazione grazie all'uso della connessione SSL esistente, che in genere viene creata comunque. L'impegno aggiuntivo per l'invio del certificato client è minimo. |
Svantaggi |
La password è incorporata come testo in chiaro nell'intestazione di autenticazione HTTP e deve essere inviata esclusivamente via SSL. Il Mastercard Gateway accetta solo connessioni protette da SSL, pertanto la password non è divulgabile. Tuttavia è molto importante per la sicurezza della connessione che venga eseguita un'autenticazione server appropriata per evitare la divulgazione involontaria ai server rogue. |
Nessuna |
Supporto per la condivisione delle credenziali in più profili esercente |
Non è possibile condividere le password in più profili esercente |
Consente di condividere un ID di una serie di certificati con più profili esercente in un'organizzazione o tra più organizzazioni di servizi agli esercenti (basato su privilegi). |