Integrare Azure AD in un'app per AndroidIntegrate Azure AD into an Android app

Suggerimento

È consigliabile provare l'anteprima del nuovo portale per sviluppatori che consentirà di imparare a usare Azure AD in pochi minuti.Try the preview of our new developer portal, which will help you get up and running with Azure AD in just a few minutes. Il portale per sviluppatori guida l'utente nel processo di registrazione di un'app e di integrazione di Azure AD nel codice.The developer portal will walk you through the process of registering an app and integrating Azure AD into your code. Al termine si ottiene una semplice applicazione in grado di autenticare gli utenti nel tenant e un back-end che può accettare i token ed eseguire la convalida.When you’re finished, you'll have a simple application that can authenticate users in your tenant and a back end that can accept tokens and perform validation.

Se si sta sviluppando un'applicazione desktop, Azure Active Directory (Azure AD) semplifica e facilita l'autenticazione degli utenti tramite gli account Active Directory locali.If you're developing a desktop application, Azure Active Directory (Azure AD) makes it simple and straightforward for you to authenticate your users by using their on-premises Active Directory accounts. Consente inoltre all'applicazione di usare in modo sicuro qualsiasi API Web protetta da Azure AD, ad esempio le API di Office 365 o l'API di Azure.It also enables your application to securely consume any web API protected by Azure AD, such as the Office 365 APIs or the Azure API.

Per i client Android che devono accedere a risorse protette, Azure AD fornisce Active Directory Authentication Library (ADAL).For Android clients that need to access protected resources, Azure AD provides the Active Directory Authentication Library (ADAL). La funzione di ADAL è di permettere all'app di ottenere facilmente i token di accesso.The sole purpose of ADAL is to make it easy for your app to get access tokens. Per illustrare la semplicità del processo, verrà compilata un'applicazione Android To-Do List che esegue le operazioni seguenti:To demonstrate how easy it is, we’ll build an Android To-Do List application that:

Per iniziare, è necessario un tenant di Azure AD in cui poter creare gli utenti e registrare un'applicazione.To get started, you need an Azure AD tenant in which you can create users and register an application. Se non si ha già un tenant, vedere le informazioni su come ottenerne uno.If you don't already have a tenant, learn how to get one.

Passaggio 1: Scaricare ed eseguire il server di esempio dell'API REST TODO per Node.jsStep 1: Download and run the Node.js REST API TODO sample server

L'esempio dell'API REST TODO per Node.js è scritto specificamente per funzionare con l'esempio esistente per la compilazione di una singola API REST To-Do del tenant per Azure AD.The Node.js REST API TODO sample is written specifically to work against our existing sample for building a single-tenant To-Do REST API for Azure AD. Questo è un prerequisito per l'Avvio rapido.This is a prerequisite for the Quick Start.

Per informazioni sulla procedura di configurazione di questa funzionalità, vedere gli esempi esistenti in Servizio API REST di esempio per Microsoft Azure Active Directory per Node.js.For information on how to set this up, see our existing samples in Microsoft Azure Active Directory Sample REST API Service for Node.js.

Passaggio 2: Registrare l'API Web con il tenant di Azure ADStep 2: Register your web API with your Azure AD tenant

Active Directory supporta l'aggiunta di due tipi di applicazioni:Active Directory supports adding two types of applications:

  • API Web che offre servizi agli utentiWeb APIs that offer services to users
  • Applicazioni, in esecuzione sul Web o in un dispositivo, che accedono a queste API WebApplications (running either on the web or on a device) that access those web APIs

In questo passaggio si registra l'API Web in esecuzione in locale per il test di questo esempio.In this step, you're registering the web API that you're running locally for testing this sample. In genere questa API Web è un servizio REST che offre le funzionalità a cui un'app deve accedere.Normally, this web API is a REST service that's offering functionality that you want an app to access. Azure AD contribuisce alla protezione di qualsiasi endpoint.Azure AD can help protect any endpoint.

Si presuppone che venga eseguita la registrazione dell'API REST TODO indicata in precedenza,We're assuming that you're registering the TODO REST API referenced earlier. ma questa procedura è applicabile a qualsiasi API Web che si vuole proteggere con Azure Active Directory.But this works for any web API that you want Azure Active Directory to help protect.

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Nella barra superiore fare clic sull'account.On the top bar, click your account. Nell'elenco di Directory scegliere il tenant di Azure AD in cui si vuole registrare l'applicazione.In the Directory list, choose the Azure AD tenant where you want to register your application.
  3. Fare clic su More Services (Altri servizi) nel riquadro sinistro, quindi selezionare Azure Active Directory.Click More Services in the left pane, and then select Azure Active Directory.
  4. Fare clic su Registrazioni per l'app, quindi selezionare Aggiungi.Click App registrations, and then select Add.
  5. Immettere un nome descrittivo per l'applicazione, ad esempio TodoListService, selezionare Applicazione Web e/o API Web, quindi fare clic su Avanti.Enter a friendly name for the application (for example, TodoListService), select Web Application and/or Web API, and click Next.
  6. Per l'URL di accesso immettere l'URL di base per l'esempio.For the sign-on URL, enter the base URL for the sample. Per impostazione predefinita, tale valore è https://localhost:8080.By default, this is https://localhost:8080.
  7. Fare clic su OK per completare la registrazione.Click OK to complete the registration.
  8. Nel portale di Azure passare alla pagina dell'applicazione, individuare il valore dell'ID applicazione e copiarlo.While still in the Azure portal, go to your application page, find the application ID value, and copy it. Servirà in un secondo momento durante la configurazione dell'applicazione.You'll need this later when configuring your application.
  9. Dalla pagina Impostazioni -> Proprietà aggiornare l'URI dell'ID app. Immettere https://<your_tenant_name>/TodoListService.From the Settings -> Properties page, update the app ID URI - enter https://<your_tenant_name>/TodoListService. Sostituire <your_tenant_name> con il nome del tenant di Azure AD.Replace <your_tenant_name> with the name of your Azure AD tenant.

Passaggio 3: Registrare l'applicazione client nativa Android di esempioStep 3: Register the sample Android Native Client application

È necessario registrare l'applicazione Web in questo esempio.You must register your web application in this sample. In questo modo l'applicazione può comunicare con l'API Web appena registrata.This allows your application to communicate with the just-registered web API. Se l'applicazione non è registrata, Azure AD non le consentirà nemmeno di chiedere di effettuare l'accesso.Azure AD will refuse to even allow your application to ask for sign-in unless it's registered. Questo fa parte della sicurezza del modello.That's part of the security of the model.

Si presuppone che venga eseguita la registrazione dell'applicazione di esempio indicata in precedenza,We're assuming that you're registering the sample application referenced earlier. ma questa procedura è applicabile a qualsiasi app in fase di sviluppo.But this procedure works for any app that you're developing.

Nota

Si procede all'inserimento di un'applicazione e di un'API Web in un tenant,You might wonder why you're putting both an application and a web API in one tenant. perché è possibile compilare un'app che accede a un'API esterna registrata in Azure AD da un altro tenant.As you might have guessed, you can build an app that accesses an external API that is registered in Azure AD from another tenant. In tal caso, ai clienti verrà richiesto di acconsentire all'uso dell'API nell'applicazione.If you do that, your customers will be prompted to consent to the use of the API in the application. Active Directory Authentication Library per iOS gestisce automaticamente la richiesta di consenso.Active Directory Authentication Library for iOS takes care of this consent for you. Iniziando a esaminare funzionalità più avanzate, si può immaginare come questa sia una parte importante del lavoro necessario per accedere alla gamma di API Microsoft da Azure e da Office, oltre che da altri provider di servizi.As we explore more advanced features, you'll see that this is an important part of the work needed to access the suite of Microsoft APIs from Azure and Office, as well as any other service provider. Per ora, poiché sia l'API Web che l'applicazione sono state registrate nello stesso tenant, non verrà visualizzata alcuna richiesta di consenso.For now, because you registered both your web API and your application under the same tenant, you won't see any prompts for consent. Di solito ciò avviene se si sta sviluppando un'applicazione che verrà usata solo in azienda.This is usually the case if you're developing an application just for your own company to use.

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Nella barra superiore fare clic sull'account.On the top bar, click your account. Nell'elenco di Directory scegliere il tenant di Azure AD in cui si vuole registrare l'applicazione.In the Directory list, choose the Azure AD tenant where you want to register your application.
  3. Fare clic su More Services (Altri servizi) nel riquadro sinistro, quindi selezionare Azure Active Directory.Click More Services in the left pane, and then select Azure Active Directory.
  4. Fare clic su Registrazioni per l'app, quindi selezionare Aggiungi.Click App registrations, and then select Add.
  5. Immettere un nome descrittivo per l'applicazione, ad esempio TodoListClient-Android, selezionare Applicazione client nativa, quindi fare clic su Avanti.Enter a friendly name for the application (for example, TodoListClient-Android), select Native Client Application, and click Next.
  6. Per l'URI di reindirizzamento, immettere http://TodoListClient.For the redirect URI, enter http://TodoListClient. Fare clic su Fine.Click Finish.
  7. Nella pagina dell'applicazione trovare il valore dell'ID applicazione e copiarlo.From the application page, find the application ID value and copy it. Servirà in un secondo momento durante la configurazione dell'applicazione.You'll need this later when configuring your application.
  8. Nella pagina Impostazioni selezionare Autorizzazioni necessarie e selezionare Aggiungi.From the Settings page, select Required Permissions and select Add. Individuare e selezionare TodoListService, aggiungere l'autorizzazione di Access TodoListService in Autorizzazioni delegate e fare clic su Operazione completata.Locate and select TodoListService, add the Access TodoListService permission under Delegated Permissions, and click Done.

Per compilare con Maven, è possibile usare pom.xml al livello principale:To build with Maven, you can use pom.xml at the top level:

  1. Clonare il repository in una directory di propria scelta:Clone this repo into a directory of your choice:

    $ git clone git@github.com:AzureADSamples/NativeClient-Android.git

  2. Seguire la procedura illustrata nei prerequisiti per la configurazione dell'ambiente Maven per Android.Follow the steps in the prerequisites to set up your Maven environment for Android.
  3. Configurare l'emulatore con SDK 19.Set up the emulator with SDK 19.
  4. Passare alla cartella radice in cui è stato clonato il repository.Go to the root folder where you cloned the repo.
  5. Eseguire questo comando: mvn clean installRun this command: mvn clean install
  6. Passare alla directory dell'esempio di Avvio rapido: cd samples\hello.Change the directory to the Quick Start sample: cd samples\hello
  7. Eseguire questo comando: mvn android:deploy android:runRun this command: mvn android:deploy android:run

    Dovrebbe essere visualizzato l'avvio dell'app.You should see the app starting.

  8. Immettere le credenziali dell'utente test per provare.Enter test user credentials to try.

Oltre al pacchetto AAR, verranno inviati i pacchetti JAR.JAR packages will be submitted beside the AAR package.

Passaggio 4: Scaricare ADAL per Android e aggiungerlo all'area di lavoro di EclipseStep 4: Download the Android ADAL and add it to your Eclipse workspace

Per semplificare l'operazione, sono disponibili più opzioni per usare ADAL nel progetto Android:We've made it easy for you to have multiple options to use ADAL in your Android project:

  • È possibile usare il codice sorgente per importare la libreria in Eclipse e collegarla all'applicazione.You can use the source code to import this library into Eclipse and link to your application.
  • Se si usa Android Studio, è possibile usare il formato di pacchetto AAR e fare riferimento ai file binari.If you're using Android Studio, you can use the AAR package format and reference the binaries.

Opzione 1: Zip del codice sorgenteOption 1: Source Zip

Per scaricare una copia del codice sorgente, fare clic su Download ZIP (Scarica ZIP) nel lato destro della pagina.To download a copy of the source code, click Download ZIP on the right side of the page. In alternativa, eseguire il download da GitHub.Or you can download from GitHub.

Opzione 2: Codice sorgente tramite GitOption 2: Source via Git

Per ottenere il codice sorgente dell'SDK tramite Git, digitare:To get the source code of the SDK via Git, type:

git clone git@github.com:AzureAD/azure-activedirectory-library-for-android.git
cd ./azure-activedirectory-library-for-android/src

Opzione 3: File binari tramite GradleOption 3: Binaries via Gradle

È possibile ottenere i file binari dal repository centrale di Maven.You can get the binaries from the Maven central repo. Il pacchetto AAR può essere incluso come segue nel progetto in Android Studio:The AAR package can be included as follows in your project in Android Studio:

repositories {
    mavenCentral()
    flatDir {
        dirs 'libs'
    }
    maven {
        url "YourLocalMavenRepoPath\\.m2\\repository"
    }
}
dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile('com.microsoft.aad:adal:1.1.1') {
        exclude group: 'com.android.support'
    } // Recent version is 1.1.1
}

Opzione 4: AAR tramite MavenOption 4: AAR via Maven

Se si usa il plug-in M2Eclipse, è possibile specificare la dipendenza nel file pom.xml:If you're using the M2Eclipse plug-in, you can specify the dependency in your pom.xml file:

<dependency>
    <groupId>com.microsoft.aad</groupId>
    <artifactId>adal</artifactId>
    <version>1.1.1</version>
    <type>aar</type>
</dependency>

Opzione 5: Pacchetto JAR nella cartella libsOption 5: JAR package inside the libs folder

È possibile ottenere il file JAR dal repository Maven e inserirlo nella cartella libs del progetto.You can get the JAR file from the Maven repo and drop it into the libs folder in your project. È necessario copiare anche le risorse necessarie per il progetto, perché non sono incluse nei pacchetti JAR.You need to copy the required resources to your project as well, because the JAR packages don't include them.

Passaggio 5: Aggiungere i riferimenti ad ADAL per Android nel progettoStep 5: Add references to Android ADAL to your project

  1. Aggiungere un riferimento al progetto e specificarlo come una libreria Android.Add a reference to your project and specify it as an Android library. In caso di dubbi su questa operazione, è possibile ottenere altre informazioni nel sito Android Studio.If you're uncertain how to do this, you can get more information on the Android Studio site.
  2. Aggiungere la dipendenza del progetto per il debug alle impostazioni del progetto.Add the project dependency for debugging into your project settings.
  3. Aggiornare il file AndroidManifest.xml del progetto includendo:Update your project's AndroidManifest.xml file to include:

     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
     <application
         android:allowBackup="true"
         android:debuggable="true"
         android:icon="@drawable/ic_launcher"
         android:label="@string/app_name"
         android:theme="@style/AppTheme" >
    
         <activity
             android:name="com.microsoft.aad.adal.AuthenticationActivity"
             android:label="@string/title_login_hello_app" >
         </activity>
         ....
     <application/>
    
  4. Creare un'istanza di AuthenticationContext nell'attività principale.Create an instance of AuthenticationContext at your main activity. I dettagli di questa chiamata non rientrano dell'ambito di questo argomento, ma come punto di partenza è possibile vedere l'esempio relativo al client nativo Android.The details of this call are beyond the scope of this topic, but you can get a good start by looking at the Android Native Client sample. Nell'esempio seguente SharedPreferences è la cache predefinita e il formato di Authority è https://login.microsoftonline.com/yourtenant.onmicrosoft.com:In the following example, SharedPreferences is the default cache, and Authority is in the form of https://login.microsoftonline.com/yourtenant.onmicrosoft.com:

    mContext = new AuthenticationContext(MainActivity.this, authority, true); // mContext is a field in your activity

  5. Copiare il blocco di codice per gestire la fine di AuthenticationActivity dopo che l'utente ha immesso le credenziali e ricevuto un codice di autorizzazione:Copy this code block to handle the end of AuthenticationActivity after the user enters credentials and receives an authorization code:

     @Override
      protected void onActivityResult(int requestCode, int resultCode, Intent data) {
          super.onActivityResult(requestCode, resultCode, data);
          if (mContext != null) {
             mContext.onActivityResult(requestCode, resultCode, data);
          }
      }
    
  6. Per richiedere un token, definire un callback:To ask for a token, define a callback:

     private AuthenticationCallback<AuthenticationResult> callback = new AuthenticationCallback<AuthenticationResult>() {
    
         @Override
         public void onError(Exception exc) {
             if (exc instanceof AuthenticationException) {
                 textViewStatus.setText("Cancelled");
                 Log.d(TAG, "Cancelled");
             } else {
                 textViewStatus.setText("Authentication error:" + exc.getMessage());
                 Log.d(TAG, "Authentication error:" + exc.getMessage());
             }
         }
    
         @Override
         public void onSuccess(AuthenticationResult result) {
             mResult = result;
    
             if (result == null || result.getAccessToken() == null
                     || result.getAccessToken().isEmpty()) {
                 textViewStatus.setText("Token is empty");
                 Log.d(TAG, "Token is empty");
             } else {
                 // request is successful
                 Log.d(TAG, "Status:" + result.getStatus() + " Expired:"
                         + result.getExpiresOn().toString());
                 textViewStatus.setText(PASSED);
             }
         }
     };
    
  7. Infine, richiedere il token usando il callback:Finally, ask for a token by using that callback:

    mContext.acquireToken(MainActivity.this, resource, clientId, redirect, user_loginhint, PromptBehavior.Auto, "", callback);

Ecco una descrizione dei parametri:Here's an explanation of the parameters:

  • resource è obbligatorio ed è la risorsa a cui si sta tentando di accedere.resource is required and is the resource you're trying to access.
  • clientid è obbligatorio e viene fornito da Azure AD.clientid is required and comes from Azure AD.
  • RedirectUri non è obbligatorio specificarlo per la chiamata acquireToken.RedirectUri is not required to be provided for the acquireToken call. È possibile configurarlo come nome del pacchetto.You can set it up as your package name.
  • PromptBehavior facilita la richiesta delle credenziali per ignorare cache e cookie.PromptBehavior helps to ask for credentials to skip the cache and cookie.
  • callback viene chiamato dopo lo scambio del codice di autorizzazione con un token.callback is called after the authorization code is exchanged for a token. Ha un oggetto AuthenticationResult, che include un token di accesso, la data di scadenza e le informazioni sul token ID.It has an object of AuthenticationResult, which has access token, date expired, and ID token information.
  • acquireTokenSilent è facoltativo.acquireTokenSilent is optional. È possibile chiamarlo per gestire la memorizzazione nella cache e l'aggiornamento del token.You can call it to handle caching and token refresh. Fornisce anche la versione di sincronizzazione.It also provides the sync version. Accetta userId come parametro.It accepts userId as a parameter.

      mContext.acquireTokenSilent(resource, clientid, userId, callback );
    

Tramite questa procedura dettagliata si dovrebbero avere tutte le informazioni necessarie per una corretta integrazione con Azure Active Directory.By using this walkthrough, you should have what you need to successfully integrate with Azure Active Directory. Per altre informazioni sull'esecuzione di queste operazioni, visitare il repository AzureADSamples/ su GitHub.For more examples of this working, visit the AzureADSamples/ repository on GitHub.

Informazioni importantiImportant information

PersonalizzazioneCustomization

Le risorse dell'applicazione possono sovrascrivere le risorse del progetto di libreria.Your application resources can overwrite library project resources. Ciò si verifica durante la compilazione dell'app.This happens when your app is being built. Per questo motivo, è possibile personalizzare il layout dell'attività di autenticazione come si preferisce.For this reason, you can customize authentication activity layout the way you want. È necessario accertarsi che venga mantenuto l'ID dei controlli usati da ADAL (Webview).Be sure to keep the ID of the controls that ADAL uses (WebView).

GestoreBroker

L'app Portale aziendale di Microsoft Intune fornisce il componente broker.The Microsoft Intune Company Portal app provides the broker component. L'account viene creato in AccountManager.The account is created in AccountManager. Il tipo di account è "com.microsoft.workaccount".The account type is "com.microsoft.workaccount." AccountManager consente solo un singolo account Single Sign-On (SSO).AccountManager allows only a single SSO account. Dopo il completamento della richiesta di verifica del dispositivo per una delle app, viene creato un cookie SSO per questo utente.It creates an SSO cookie for the user after completing the device challenge for one of the apps.

ADAL usa l'account broker, se è stato creato un account utente per questo autenticatore e si è scelto di non ignorarlo.ADAL uses the broker account if one user account is created at this authenticator and you choose not to skip it. È possibile ignorare l'utente broker usando:You can skip the broker user with:

AuthenticationSettings.Instance.setSkipBroker(true);

È necessario registrare un URI di reindirizzamento speciale per l'utilizzo da parte del broker.You need to register a special RedirectUri for broker usage. L'URI di reindirizzamento è nel formato msauth://packagename/Base64UrlencodedSignature.RedirectUri is in the format of msauth://packagename/Base64UrlencodedSignature. È possibile ottenere l'URI di reindirizzamento per l'app usando lo script brokerRedirectPrint.ps1 o la chiamata API mContext.getBrokerRedirectUri.You can get your RedirectUri for your app by using the script brokerRedirectPrint.ps1 or the API call mContext.getBrokerRedirectUri. La firma è correlata ai certificati di firma.The signature is related to your signing certificates.

Il modello di broker attuale è per un solo utente.The current broker model is for one user. AuthenticationContext fornisce il metodo API per ottenere l'utente broker.AuthenticationContext provides the API method to get the broker user.

String brokerAccount = mContext.getBrokerUser(); //Broker user is returned if account is valid.

Il manifesto dell'app deve avere le autorizzazioni seguenti per usare gli account di AccountManager.Your app manifest should have the following permissions to use AccountManager accounts. Per informazioni dettagliate, vedere le Informazioni su AccountManager nel sito Android.For details, see the AccountManager information on the Android site.

  • GET_ACCOUNTSGET_ACCOUNTS
  • USE_CREDENTIALSUSE_CREDENTIALS
  • MANAGE_ACCOUNTSMANAGE_ACCOUNTS

URL dell'autorità e AD FSAuthority URL and AD FS

Active Directory Federation Services (AD FS) non è riconosciuto come servizio token di sicurezza di produzione, quindi è necessario disattivare l'individuazione dell'istanza e passare false al costruttore AuthenticationContext.Active Directory Federation Services (AD FS) is not recognized as production STS, so you need to turn of instance discovery and pass false at the AuthenticationContext constructor.

L'URL dell'autorità richiede un'istanza del servizio token di sicurezza e il nome del tenant.The authority URL needs an STS instance and a tenant name.

Esecuzione di query sugli elementi della cacheQuerying cache items

ADAL fornisce una cache predefinita in SharedPrefrecens con alcune semplici funzioni di query nella cache.ADAL provides a default cache in SharedPreferences with some simple cache query functions. È possibile ottenere la cache corrente da AuthenticationContext con:You can get the current cache from AuthenticationContext by using:

ITokenCacheStore cache = mContext.getCache();

È anche possibile fornire l'implementazione della cache, se si desidera personalizzarla.You can also provide your cache implementation, if you want to customize it.

mContext = new AuthenticationContext(MainActivity.this, authority, true, yourCache);

Comportamento della richiestaPrompt behavior

ADAL include un'opzione per specificare il comportamento delle richieste.ADAL provides an option to specify prompt behavior. Se il token di aggiornamento non è valido e sono richieste le credenziali utente, PromptBehavior.Auto visualizzerà l'interfaccia utente.PromptBehavior.Auto will show the UI if the refresh token is invalid and user credentials are required. PromptBehavior.Always ignorerà l'utilizzo della cache e visualizzerà sempre l'interfaccia utente.PromptBehavior.Always will skip the cache usage and always show the UI.

Richiesta invisibile all'utente dei token dalla cache e aggiornamentoSilent token request from cache and refresh

Una richiesta di token invisibile all'utente non usa il popup dell'interfaccia utente e non richiede alcuna attività.A silent token request does not use the UI pop-up and does not require an activity. Restituisce un token dalla cache, se disponibile.It returns a token from the cache if available. Se il token è scaduto, questo metodo prova ad aggiornarlo.If the token is expired, this method tries to refresh it. Se il token di aggiornamento è scaduto o non è riuscito, restituisce AuthenticationException.If the refresh token is expired or failed, it returns AuthenticationException.

Future<AuthenticationResult> result = mContext.acquireTokenSilent(resource, clientid, userId, callback );

Con questo metodo è anche possibile effettuare una chiamata di sincronizzazione.You can also make a sync call by using this method. È possibile impostare Null per il callback o usare acquireTokenSilentSync.You can set null to callback or use acquireTokenSilentSync.

DiagnosticaDiagnostics

Di seguito sono riportate le fonti di informazioni principali per la diagnostica dei problemi:These are the primary sources of information for diagnosing issues:

  • EccezioniExceptions
  • LogLogs
  • Tracce di reteNetwork traces

Si noti che gli ID di correlazione sono fondamentali per la diagnostica della libreria.Note that correlation IDs are central to the diagnostics in the library. È possibile impostare gli ID di correlazione per le singole richieste, se si vuole correlare una richiesta ADAL con altre operazioni presenti nel codice.You can set your correlation IDs on a per-request basis if you want to correlate an ADAL request with other operations in your code. Se non si imposta un ID di correlazione, ADAL genererà un valore casuale.If you don't set a correlation ID, ADAL will generate a random one. Tutti i messaggi di log e le chiamate di rete verranno quindi contrassegnate con l'ID di correlazione.All log messages and network calls will then be stamped with the correlation ID. L'ID generato automaticamente cambia per ogni richiesta.The self-generated ID changes on each request.

EccezioniExceptions

Le eccezioni costituiscono il primo elemento di diagnostica.Exceptions are the first diagnostic. Vengono forniti messaggi di errore che dovrebbero risultare utili,We try to provide helpful error messages. ma se qualcuno non dovesse esserlo, registrare il problema e segnalarlo.If you find one that is not helpful, please file an issue and let us know. Includere le informazioni relative al dispositivo, ad esempio modello e numero di SDK.Include device information such as model and SDK number.

LogLogs

È possibile configurare la libreria in modo che vengano generati messaggi di log che possono risultare utili per diagnosticare i problemi.You can configure the library to generate log messages that you can use to help diagnose issues. Per configurare la registrazione, eseguire la chiamata seguente per configurare un callback che ADAL userà per presentare ogni messaggio di log generato.You configure logging by making the following call to configure a callback that ADAL will use to hand off each log message as it's generated.

Logger.getInstance().setExternalLogger(new ILogger() {
    @Override
    public void Log(String tag, String message, String additionalMessage, LogLevel level, ADALError errorCode) {
    ...
    // You can write this to log file depending on level or error code.
    writeToLogFile(getApplicationContext(), tag +":" + message + "-" + additionalMessage);
    }
}

I messaggi possono essere scritti in un file di log personalizzato, come illustrato nel codice seguente.Messages can be written to a custom log file, as shown in the following code. Non esiste purtroppo un metodo standard per ottenere i log da un dispositivo.Unfortunately, there is no standard way of getting logs from a device. A questo scopo, sono disponibili alcuni servizi che possono risultare utili.There are some services that can help you with this. È anche possibile crearne di personalizzati, ad esempio per l'invio del file a un server.You can also invent your own, such as sending the file to a server.

private syncronized void writeToLogFile(Context ctx, String msg) {
   File directory = ctx.getDir(ctx.getPackageName(), Context.MODE_PRIVATE);
   File logFile = new File(directory, "logfile");
   FileOutputStream outputStream = new FileOutputStream(logFile, true);
   OutputStreamWriter osw = new OutputStreamWriter(outputStream);
   osw.write(msg);
   osw.flush();
   osw.close();
}

Ecco i livelli di registrazione:These are the logging levels:

  • Errore (eccezioni)Error (exceptions)
  • Avviso (avviso)Warn (warning)
  • Info (a scopo informativo)Info (information purposes)
  • Dettagliato (altri dettagli)Verbose (more details)

Il livello di registrazione viene impostato nel modo seguente:You set the log level like this:

Logger.getInstance().setLogLevel(Logger.LogLevel.Verbose);

Tutti i messaggi di log vengono inviati a logcat, oltre agli eventuali callback di log personalizzati.All log messages are sent to logcat, in addition to any custom log callbacks. È possibile ottenere un log in un file da logcat, come indicato di seguito:You can get a log to a file from logcat as follows:

adb logcat > "C:\logmsg\logfile.txt"

Per informazioni dettagliate sui comandi adb, vedere le informazioni relative a logcat nel sito Android.For details about adb commands, see the logcat information on the Android site.

Tracce di reteNetwork traces

Per acquisire il traffico HTTP generato da ADAL sono disponibili diversi strumenti.You can use various tools to capture the HTTP traffic that ADAL generates. Ciò è particolarmente utile se si ha familiarità con il protocollo OAuth o se è necessario fornire informazioni di diagnostica a Microsoft o altri canali di supporto.This is most useful if you're familiar with the OAuth protocol or if you need to provide diagnostic information to Microsoft or other support channels.

Fiddler è lo strumento di traccia HTTP più semplice.Fiddler is the easiest HTTP tracing tool. Usare i collegamenti seguenti per configurarlo in modo che registri correttamente il traffico di rete ADAL.Use the following links to set it up to correctly record ADAL network traffic. Per usare in modo ottimale uno strumento di traccia come Fiddler o Charles, è necessario configurarlo per la registrazione del traffico SSL non crittografato.For a tracing tool like Fiddler or Charles to be useful, you must configure it to record unencrypted SSL traffic.

Nota

Le tracce generate in questo modo possono contenere informazioni con privilegi elevati, ad esempio token di accesso, nomi utente e password.Traces generated in this way might contain highly privileged information such as access tokens, usernames, and passwords. Se si usano account di produzione, non condividere queste tracce con terze parti.If you're using production accounts, do not share these traces with third parties. Se è necessario fornire una traccia a terzi per ottenere il supporto, riprodurre il problema con un account temporaneo usando nomi utente e password che è possibile condividere senza problemi.If you need to supply a trace to someone in order to get support, reproduce the issue by using a temporary account with usernames and passwords that you don't mind sharing.

Modalità della finestra di dialogoDialog mode

Il metodo acquireToken senza attività supporta prompt della finestra di dialogo.The acquireToken method without activity supports a dialog prompt.

CrittografiaEncryption

ADAL crittografa i token e li archivia in SharedPreferences per impostazione predefinita.ADAL encrypts the tokens and store in SharedPreferences by default. È possibile esaminare la classe StorageHelper per visualizzare i dettagli.You can look at the StorageHelper class to see the details. Android ha introdotto Android Keystore 4.3 (API 18) per l'archiviazione protetta delle chiavi private.Android introduced Android Keystore for 4.3 (API 18) secure storage of private keys. ADAL lo usa per API 18 e versioni successive.ADAL uses that for API 18 and higher. Se si vuole usare ADAL per versioni precedenti dell'SDK, è necessario fornire la chiave privata in AuthenticationSettings.INSTANCE.setSecretKey.If you want to use ADAL for lower SDK versions, you need to provide a secret key at AuthenticationSettings.INSTANCE.setSecretKey.

Richiesta di connessione di OAuth2OAuth2 bearer challenge

La classe AuthenticationParameters fornisce la funzionalità per ottenere authorization_uri dalla richiesta di connessione di OAuth2.The AuthenticationParameters class provides functionality to get authorization_uri from the OAuth2 bearer challenge.

Cookie di sessione in WebViewSession cookies in WebView

Android WebView non cancella i cookie di sessione dopo la chiusura dell'app.Android WebView does not clear session cookies after the app is closed. È possibile gestire questa operazione usando questo codice di esempio:You can handle that by using this sample code:

CookieSyncManager.createInstance(getApplicationContext());
CookieManager cookieManager = CookieManager.getInstance();
cookieManager.removeSessionCookie();
CookieSyncManager.getInstance().sync();

Per informazioni dettagliate sui cookie, vedere le informazioni su CookieSyncManager nel sito Android.For details about cookies, see the CookieSyncManager information on the Android site.

Override delle risorseResource overrides

La libreria ADAL include stringhe in inglese per messaggi ProgressDialog.The ADAL library includes English strings for ProgressDialog messages. L'applicazione deve sovrascriverle, se si vogliono usare stringhe localizzate.Your application should overwrite them if you want localized strings.

 <string name="app_loading">Loading...</string>
 <string name="broker_processing">Broker is processing</string>
 <string name="http_auth_dialog_username">Username</string>
 <string name="http_auth_dialog_password">Password</string>
 <string name="http_auth_dialog_title">Sign In</string>
 <string name="http_auth_dialog_login">Login</string>
 <string name="http_auth_dialog_cancel">Cancel</string>

Finestra di dialogo NTLMNTLM dialog box

ADAL versione 1.1.0 supporta la finestra di dialogo NTLM che viene elaborata tramite l'evento onReceivedHttpAuthRequest da WebViewClient.ADAL version 1.1.0 supports an NTLM dialog box that is processed through the onReceivedHttpAuthRequest event from WebViewClient. È possibile personalizzare il layout e le stringhe per la finestra di dialogo.You can customize the layout and strings for the dialog box.

Accesso Single Sign-On tra appCross-app SSO

Informazioni su Come abilitare l'accesso Single Sign-On tra app su Android usando ADAL.Learn how to enable cross-app SSO on Android by using ADAL.

Risorse aggiuntiveAdditional resources

Ottenere aggiornamenti della sicurezza per i prodottiGet security updates for our products

È consigliabile ricevere notifiche in caso di problemi di sicurezza. A tale scopo, visitare la pagina del TechCenter per le notifiche sulla sicurezza tecnica per Microsoft e sottoscrivere gli avvisi di sicurezza.We encourage you to get notifications of when security incidents occur by visiting the TechCenter page for Microsoft technical security notifications and subscribing to security advisory alerts.