Compilazione di Multi-Factor Authentication in app personalizzate (SDK)Building Multi-Factor Authentication into Custom Apps (SDK)

Importante

Azure Multi-Factor Authentication Software Development Kit (SDK) è deprecato.The deprecation of the Azure Multi-Factor Authentication Software Development Kit (SDK) has been announced. Questa funzionalità non è più supportata per i nuovi clienti.This feature will no longer be supported for new customers. I clienti correnti possono continuare a usare l'SDK fino al 14 novembre 2018.Current customers can continue using the SDK until November 14, 2018. Dopo tale periodo, le chiamate all'SDK avranno esito negativo.After that time, calls to the SDK will fail.

Il Software Development Kit (SDK) di Azure Multi-Factor Authentication consente di compilare la verifica in due passaggi direttamente nei processi di accesso o di transazione delle applicazioni nel tenant di Azure AD.The Azure Multi-Factor Authentication Software Development Kit (SDK) lets you build two-step verification directly into the sign-in or transaction processes of applications in your Azure AD tenant.

L'SDK di Multi-Factor Authentication è disponibile per C#, Visual Basic (.NET), Java, Perl, PHP e Ruby.The Multi-Factor Authentication SDK is available for C#, Visual Basic (.NET), Java, Perl, PHP, and Ruby. L'SDK fornisce un wrapper sottile per la verifica in due passaggi.The SDK provides a thin wrapper around two-step verification. Include tutto ciò che occorre per scrivere il codice, inclusi i file di codice sorgente commentati, i file di esempio e un file ReadMe dettagliato.It includes everything you need to write your code, including commented source code files, example files, and a detailed ReadMe file. Ogni SDK include anche un certificato e una chiave privata univoci per il provider Multi-Factor Authentication per crittografare le transazioni.Each SDK also includes a certificate and private key for encrypting transactions that are unique to your Multi-Factor Authentication Provider. Fino a quando si dispone di un provider, è possibile scaricare l'SDK in tutti i formati e le lingue necessari.As long as you have a provider, you can download the SDK in as many languages and formats as you need.

La struttura delle API nell'SDK di Multi-Factor Authentication è semplice.The structure of the APIs in the Multi-Factor Authentication SDK is simple. Eseguire una sola funzione di chiamata a un'API con i parametri di opzione a più fattori (ad esempio la modalità di verifica) e dati utente (come il numero di telefono da chiamare o il numero PIN da convalidare).Make a single function call to an API with the multi-factor option parameters (like verification mode) and user data (like the telephone number to call or the PIN number to validate). Le API convertono la chiamata di funzione in richieste di servizi web per il servizio Azure Multi-Factor Authentication.The APIs translate the function call into web services requests to the cloud-based Azure Multi-Factor Authentication Service. Tutte le chiamate devono includere un riferimento al certificato privato incluso in ogni SDK.All calls must include a reference to the private certificate that is included in every SDK.

Poiché le API non hanno accesso agli utenti registrati in Azure Active Directory, è necessario fornire le informazioni sull'utente in un file o database.Because the APIs do not have access to users registered in Azure Active Directory, you must provide user information in a file or database. Inoltre, le API non forniscono funzionalità di gestione di registrazione o dell'utente, pertanto è necessario creare questi processi nell'applicazione.Also, the APIs do not provide enrollment or user management features, so you need to build these processes into your application.

Importante

Per scaricare l'SDK, è necessario creare un provider di Azure Multi-Factor Authentication, anche se si dispone di licenze di Azure MFA, AAD Premium o EMS.To download the SDK, you need to create an Azure Multi-Factor Auth Provider even if you have Azure MFA, AAD Premium, or EMS licenses. Se si crea un provider di Azure Multi-Factor Authentication a tale scopo e si dispone già di licenze, creare il provider con il modello Per utente abilitato.If you create an Azure Multi-Factor Auth Provider for this purpose and already have licenses, make sure to create the Provider with the Per Enabled User model. Collegare quindi il Provider alla directory contenente le licenze di Azure MFA, Azure AD Premium o EMS.Then, link the Provider to the directory that contains the Azure MFA, Azure AD Premium, or EMS licenses. Con questa configurazione verranno eseguiti addebiti solo se il numero di utenti singoli che usano l'SDK è maggiore del numero di licenze possedute.This configuration ensures that you are only billed if you have more unique users using the SDK than the number of licenses you own.

Scaricare l'SDKDownload the SDK

Per scaricare l'SDK Multi-Factor di Azure è necessario un provider di Multi-Factor Authentication.Downloading the Azure Multi-Factor SDK requires an Azure Multi-Factor Auth Provider. Questo richiede una sottoscrizione di Azure completa, anche se si possiedono licenze di Azure MFA, Azure AD Premium o Enterprise Mobility Suite.This requires a full Azure subscription, even if Azure MFA, Azure AD Premium, or Enterprise Mobility Suite licenses are owned. I metodi pubblici di download dell'SDK sono stati ritirati da quando l'SDK è stato deprecato.The public methods of downloading the SDK have been decommissioned since the SDK has been deprecated. Se è necessario scaricare l'SDK, è consigliabile aprire un caso di supporto presso Microsoft.You should open a support case with Microsoft if you need to download the SDK. L'SDK è offerto solo ai clienti che già stanno usando l'SDK.The SDK is provided only to customers that are already using the SDK. Non è previsto l'onboarding di nuovi clienti.New customers will not be onboarded.

Contenuto dell'SDKWhat's in the SDK

L'SDK include gli elementi seguenti:The SDK includes the following items:

  • README.README. Viene illustrato come usare le API di Multi-Factor Authentication in un'applicazione nuova o esistente.Explains how to use the Multi-Factor Authentication APIs in a new or existing application.
  • File di origine per Multi-Factor AuthenticationSource files for Multi-Factor Authentication
  • Certificato client usato per comunicare con il servizio Multi-Factor AuthenticationClient certificate that you use to communicate with the Multi-Factor Authentication service
  • Chiave privata per il certificatoPrivate key for the certificate
  • Risultati delle chiamate.Call results. Un elenco di codici risultato chiamata.A list of call result codes. Per aprire questo file, usare un'applicazione con formattazione del testo, come ad esempio WordPad.To open this file, use an application with text formatting, such as WordPad. Usare i codici risultato chiamata per verificare e risolvere l'implementazione di autenticazione Multi-Factor Authentication nell'applicazione.Use the call result codes to test and troubleshoot the implementation of Multi-Factor Authentication in your application. Non sono codici di stato di autenticazione.They are not authentication status codes.
  • Esempi.Examples. Codice di esempio per un'implementazione di base funzionante di Multi-Factor Authentication.Sample code for a basic working implementation of Multi-Factor Authentication.

Avviso

Il certificato client è un certificato privato univoco generato per un utente specifico.The client certificate is a unique private certificate that was generated especially for you. Non condividere o perdere questo file.Do not share or lose this file. È la chiave per garantire la sicurezza delle comunicazioni con il servizio di autenticazione Multi-Factor Authentication.It’s your key to ensuring the security of your communications with the Multi-Factor Authentication service.

Esempio di codiceCode sample

Questo esempio di codice illustra come usare le API nell'SDK di Azure Multi-Factor Authentication per aggiungere all'applicazione una verifica tramite chiamata vocale in modalità standard.This code sample shows you how to use the APIs in the Azure Multi-Factor Authentication SDK to add standard mode voice call verification to your application. La modalità standard è una telefonata a cui l'utente risponde premendo il tasto #.Standard mode is a telephone call that the user responds to by pressing the # key.

In questo esempio viene usato l'SDK di Multi-Factor Authentication C# .NET 2.0 in un'applicazione ASP.NET con logica sul lato server C#, ma il processo è simile in altri linguaggi.This example uses the C# .NET 2.0 Multi-Factor Authentication SDK in a basic ASP.NET application with C# server-side logic, but the process is similar in other languages. Poiché l'SDK include file di origine, file non eseguibili, è possibile compilare i file e farvi riferimento o includerli direttamente nell'applicazione.Because the SDK includes source files, not executable files, you can build the files and reference them or include them directly in your application.

Nota

Quando si implementa Multi-Factor Authentication, usare i metodi aggiuntivi (telefonata o SMS) come verifica secondaria o terziaria per integrare il metodo di autenticazione principale (nome utente e password).When implementing Multi-Factor Authentication, use the additional methods (phone call or text message) as secondary or tertiary verification to supplement your primary authentication method (username and password). Questi metodi non sono progettati come metodi di autenticazione principale.These methods are not designed as primary authentication methods.

Panoramica dell'esempio di codiceCode Sample Overview

Questo codice di esempio per un'applicazione demo Web semplice usa una chiamata con risposta mediante il tasto # per verificare l'autenticazione dell'utente.This sample code for a simple web demo application uses a telephone call with a # key response to verify the user's authentication. Questo fattore telefonata è noto in Multi-Factor Authentication come modalità standard.This telephone call factor is known in Multi-Factor Authentication as standard mode.

Il codice sul lato client non include elementi specifici di autenticazione Multi-Factor Authentication.The client-side code does not include any Multi-Factor Authentication-specific elements. Poiché i fattori di autenticazione aggiuntivi sono indipendenti dall'autenticazione principale, è possibile aggiungerli senza modificare l'interfaccia di accesso esistente.Because the additional authentication factors are independent of the primary authentication, you can add them without changing the existing sign-on interface. Le API negli SDK di Multi-Factor consentono di personalizzare l'esperienza dell'utente, ma potrebbe non essere necessario apportare alcuna modifica.The APIs in the Multi-Factor SDK let you customize the user experience, but you might not need to change anything at all.

Il codice lato server aggiunge l'autenticazione in modalità standard nel passaggio 2.The server-side code adds standard-mode authentication in Step 2. Crea un oggetto PfAuthParams con i parametri necessari per la verifica della modalità standard: nome utente, numero, modalità e il percorso verso il certificato del client (CertFilePath), che è necessario in ogni chiamata.It creates a PfAuthParams object with the parameters that are required for standard-mode verification: username, telephone number, and mode, and the path to the client certificate (CertFilePath), which is required in each call. Per una dimostrazione di tutti i parametri in PfAuthParams, vedere il file di esempio nel SDK.For a demonstration of all parameters in PfAuthParams, see the Example file in the SDK.

Successivamente, il codice passa l'oggetto PfAuthParams alla funzione pf_authenticate().Next, the code passes the PfAuthParams object to the pf_authenticate() function. Il valore restituito indica l'esito positivo o negativo dell'autenticazione.The return value indicates the success or failure of the authentication. I parametri out, callStatus ed errorID, contengono informazioni aggiuntive sul risultato della chiamata.The out parameters, callStatus, and errorID, contain additional call result information. I codici di risultato della chiamata sono documentati nel file dei risultati della chiamata nel SDK.The call result codes are documented in the call results file in the SDK.

Questa implementazione minima può essere scritta in poche righe.This minimal implementation can be written in a few lines. Nel codice di produzione, tuttavia, è necessario includere la gestione degli errori più sofisticati, il codice di database aggiuntivo e un'esperienza utente avanzata.However, in production code, you would include more sophisticated error handling, additional database code, and an enhanced user experience.

Codice client webWeb Client Code

Di seguito è riportato il codice di client web per una pagina demo.The following is web client code for a demo page.

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="Default.aspx.cs" Inherits="\_Default" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
<title>Multi-Factor Authentication Demo</title>
</head>
<body>
<h1>Azure Multi-Factor Authentication Demo</h1>
<form id="form1" runat="server">

<div style="width:auto; float:left">
Username:&nbsp;<br />
Password:&nbsp;<br />
</div>

<div">
<asp:TextBox id="username" runat="server" width="100px"/><br />
<asp:Textbox id="password" runat="server" width="100px" TextMode="password" /><br />
</div>

<asp:Button id="btnSubmit" runat="server" Text="Log in" onClick="btnSubmit_Click"/>

<p><asp:Label ID="lblResult" runat="server"></asp:Label></p>

</form>
</body>
</html>

Codice lato serverServer-Side Code

Nel seguente codice lato server, la Multi-Factor Authentication è configurata ed eseguita nel passaggio 2.In the following server-side code, Multi-Factor Authentication is configured and run in Step 2. La modalità standard (MODE_STANDARD) è una telefonata a cui l'utente risponde premendo il tasto #.Standard mode (MODE_STANDARD) is a telephone call to which the user responds by pressing the # key.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

public partial class \_Default : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
    }

    protected void btnSubmit_Click(object sender, EventArgs e)
    {
        // Step 1: Validate the username and password
        if (username.Text != "Contoso" || password.Text != "password")
        {
            lblResult.ForeColor = System.Drawing.Color.Red;
            lblResult.Text = "Username or password incorrect.";
        }
        else
        {
            // Step 2: Perform multi-factor authentication

            // Add call details from the user database.
            PfAuthParams pfAuthParams = new PfAuthParams();
            pfAuthParams.Username = username.Text;
            pfAuthParams.Phone = "5555555555";
            pfAuthParams.Mode = pf_auth.MODE_STANDARD;

            // Specify a client certificate
            // NOTE: This file contains the private key for the client
            // certificate. It must be stored with appropriate file
            // permissions.
            pfAuthParams.CertFilePath = "c:\\cert_key.p12";

            // Perform phone-based authentication
            int callStatus;
            int errorId;

            if(pf_auth.pf_authenticate(pfAuthParams, out callStatus, out errorId))
            {
                lblResult.ForeColor = System.Drawing.Color.Green;
                lblResult.Text = "Multi-Factor Authentication succeeded.";
            }
            else
            {
                lblResult.ForeColor = System.Drawing.Color.Red;
                lblResult.Text = "Multi-Factor Authentication failed.";
            }
        }

    }
}