Microsoft Information Protection SDK - Concetti relativi all'autenticazioneMicrosoft Information Protection SDK - Authentication concepts

L'autenticazione in MIP SDK viene eseguita estendendo la classe mip::AuthDelegate per implementare il metodo di autenticazione preferito.Authentication in the MIP SDK is performed by extending the class mip::AuthDelegate to implement your preferred method of authentication. mip::AuthDelegate contiene:mip::AuthDelegate contains:

  • mip::AuthDelegate::OAuth2Challenge -una classe che gestisce le informazioni dell'autorità OAuth2 e le fornisce all'applicazione client.mip::AuthDelegate::OAuth2Challenge - a class that manages the OAuth2 authority info and provides to the client application.
  • mip::AuthDelegate::OAuth2Token -una classe che gestisce l'acquisizione del token di accesso OAuth2 (dall'applicazione client) e l'archiviazione dei token.mip::AuthDelegate::OAuth2Token - a class manages OAuth2 access token acquisition (from the client application) and token storage.
  • mip::AuthDelegate::AcquireOAuth2Token() -una funzione virtuale pura, la cui implementazione determina il metodo di acquisizione del token di accesso.mip::AuthDelegate::AcquireOAuth2Token() - a pure virtual function, whose implementation determines the method of access token acquisition. Dopo la chiamata dall'SDK, acquisisce il token di accesso, quindi lo restituisce alla logica di autenticazione dell'SDK.After being called by the SDK, it acquires the access token, then provides it back to the SDK's authentication logic.

mip::AuthDelegate::AcquireOAuth2Token accetta i parametri seguenti e restituisce un valore booleano che indica se l'acquisizione del token ha avuto esito positivo:mip::AuthDelegate::AcquireOAuth2Token accepts the following parameters, and returns a bool indicating whether token acquisition was successful:

  • mip::Identity: l'identità dell'utente o del servizio da autenticare, se nota.mip::Identity: The identity of the user or service to be authenticated, if known.
  • mip::AuthDelegate::OAuth2Challenge: Accetta quattro parametri, Authority, Resource, Claims e Scopes.mip::AuthDelegate::OAuth2Challenge: Accepts four parameters, authority, resource, claims, and scopes. Authority è il servizio per cui verrà generato il token.Authority is the service the token will be generated against. Resource è il servizio a cui si tenta di accedere.Resource is the service we're trying to access. L'SDK gestirà il passaggio di questi parametri al delegato quando viene chiamato.The SDK will handle passing these parameters into the delegate when called. Le attestazioni sono le attestazioni specifiche dell'etichetta richieste dal servizio di protezione.Claims are the label-specific claims required by the protection service. Gli ambiti sono gli ambiti di autorizzazione Azure ad necessari per accedere alla risorsa.Scopes are the Azure AD permission scopes required to access the resource.
  • mip::AuthDelegate::OAuth2Token: Il risultato del token viene scritto in questo oggetto.mip::AuthDelegate::OAuth2Token: The token result is written to this object. Verrà utilizzato dall'SDK quando viene caricato il motore.It will be consumed by the SDK when the engine is loaded. Al di fuori di questa implementazione dell'autenticazione non dovrebbe essere necessario ottenere o impostare questo valore in altre posizioni.Outside of our authentication implementation, it shouldn't be necessary to get or set this value anywhere.

Importante: le applicazioni non chiamano AcquireOAuth2Token direttamente.Important: Applications don't call AcquireOAuth2Token directly. L'SDK chiamerà questa funzione quando necessario.The SDK will call this function when required.

Azure AD richiede di dare il consenso per un'applicazione, prima che le venga concessa l'autorizzazione per accedere alle risorse/API protette con l'identità di un account.Azure AD requires an application to be given consent, before it is granted permission to access secured resources/APIs under the identity of an account. Il consenso viene registrato come riconoscimento permanente dell'autorizzazione nel tenant dell'account, per l'account specifico (consenso dell'utente) o per tutti gli account (consenso dell'amministratore).Consent is recorded as a permanent acknowledgment of permission in the tenant of the account, for the specific account (user consent) or all accounts (admin consent). Gli scenari per il consenso sono vari, a seconda dell'API a cui si accede e delle autorizzazioni che cerca l'applicazione, nonché dell'account usato per l'accesso:Consent occurs in various scenarios, based on the API being accessed and permissions the application is seeking, and the account used for sign-in:

  • Gli account dallo stesso tenant in cui è registrata l'applicazione, se l'utente o un amministratore non ha fornito esplicitamente il pre-consenso tramite la funzionalità "Concedi autorizzazioni".accounts from the same tenant where your application is registered, if you or an administrator didn't explicitly pre-consent access via the "Grant Permissions" feature.
  • Gli account da un tenant diverso se l'applicazione è registrata come multi-tenant e l'amministratore del tenant non ha già dato il consenso per tutti gli utenti in anticipo.accounts from a different tenant if your application is registered as multi-tenant, and the tenant administrator hasn't pre-consented for all users in advance.

La classe enum mip::Consent implementa un approccio semplice che consente agli sviluppatori di applicazioni di fornire un'esperienza di consenso personalizzata in base all'endpoint a cui si accede dall'SDK.The mip::Consent enum class implements an easy-to-use approach that permits application developers to provide a custom consent experience based on the endpoint that is being accessed by the SDK. La notifica può informare un utente dei dati che verranno raccolti e di come ottenere la rimozione dei dati o fornire qualsiasi altra informazione necessaria per legge o in base ai criteri di conformità.The notification can inform a user of the data that will be collected, how to get the data removed, or any other information that is required by law or compliance policies. Quando l'utente concede il consenso, l'applicazione può continuare.Once the user grants consent, the application can continue.

ImplementazioneImplementation

Il consenso viene implementato estendendo la classe di base mip::Consent e implementando GetUserConsent per restituire uno dei valori di enumerazione mip::Consent.Consent is implemented by extending the mip::Consent base class and implementing GetUserConsent to return one of the mip::Consent enum values.

L'oggetto derivato da mip::Consent viene passato al costruttore mip::FileProfile::Settings o mip::ProtectionProfile::Settings.The object derived from mip::Consent is passed in to the mip::FileProfile::Settings or mip::ProtectionProfile::Settings constructor.

Quando un utente esegue un'operazione che richiede il consenso, l'SDK chiama il metodo GetUserConsent passando l'URL di destinazione come parametro.When a user performs an operation that would require providing consent, the SDK calls the GetUserConsent method, passing in the destination URL as the parameter. Questo è il metodo in cui si implementerebbe la visualizzazione delle informazioni necessarie per l'utente, consentendogli di decidere se acconsentire o meno all'uso del servizio.It's in this method where one would implement displaying the necessary information to the user, allowing them to make a decision on whether or not they consent to using the service.

  • AcceptAlways: fornisce il consenso e memorizza la decisione.AcceptAlways: Consent and remember the decision.
  • Accept: fornisce il consenso una sola volta.Accept: Consent once.
  • Reject: non fornisce il consenso.Reject: Do not consent.

Quando l'SDK richiede il consenso dell'utente con questo metodo, l'applicazione client deve presentare all'utente l'URL.When the SDK requests user consent with this method, the client application should present the URL to the user. Le applicazioni client devono offrire un modo per ottenere il consenso dell'utente e restituire l'enumerazione di consenso appropriata che corrisponde alla decisione dell'utente.Client applications should provide some means of obtaining user consent and return the appropriate Consent enum that corresponds to the user's decision.

Implementazione di esempioSample implementation

class ConsentDelegateImpl final : public mip::ConsentDelegate {
public:
  ConsentDelegateImpl() = default;
  
  virtual mip::Consent GetUserConsent(const std::string& url) override;

};

Quando l'SDK richiede il consenso, il metodo GetUserConsent viene chiamato dall'SDK e l'URL viene passato come parametro.When the SDK requires consent, the GetUserConsent method is called by the SDK, and the URL passed in as a parameter. Nell'esempio seguente l'utente riceve una notifica che l'SDK si connetterà all'URL specificato e fornisce all'utente un'opzione nella riga di comando.In the sample below, the user is notified that the SDK will connect to that provided URL and provides the user with an option on the commandline. In base alla scelta da parte dell'utente, l'utente accetta o rifiuta il consenso e viene passato all'SDK.Based on the choice by the user, the user accepts or rejects consent and that is passed to the SDK. Se l'utente rifiuta di concedere il consenso all'applicazione genererà un'eccezione e non verrà effettuata alcuna chiamata al servizio di protezione.If the user declines to consent the application will throw an exception and no call is made to the protection service.

Consent ConsentDelegateImpl::GetUserConsent(const string& url) {
  //Print the consent URL, ask user to choose
  std::cout << "SDK will connect to: " << url << std::endl;

  std::cout << "1) Accept Always" << std::endl;
  std::cout << "2) Accept" << std::endl;
  std::cout << "3) Reject" << std::endl;
  std::cout << "Select an option: ";
  char input;
  std::cin >> input;

  switch (input)
  {
  case '1':
    return Consent::AcceptAlways;
    break;
  case '2':
    return Consent::Accept;
    break;
  case '3':
    return Consent::Reject;
    break;
  default:
    return Consent::Reject;
  }  
}

A scopo di test e sviluppo, è ConsentDelegate possibile implementare un semplice aspetto simile al seguente:For testing and development purposes, a simple ConsentDelegate can be implemented that looks like:

Consent ConsentDelegateImpl::GetUserConsent(const string& url) {
  return Consent::AcceptAlways;
}

Tuttavia, nel codice di produzione è possibile che l'utente debba presentare una scelta per il consenso, a seconda dei requisiti e delle normative regionali o aziendali.However, in production code the user may be required to be presented with a choice to consent, depending on regional or business requirements and regulations.

Passaggi successiviNext steps

Per semplicità, gli esempi dimostrativi del delegato implementeranno l'acquisizione del token tramite la chiamata di uno script esterno.For simplicity, samples demonstrating the delegate will implement token acquisition by calling an external script. Questo script può essere sostituito da qualsiasi altro tipo di script, una libreria OAuth2 open source o una libreria OAuth2 personalizzata.This script can be replaced by any other type of script, an open-source OAuth2 library, or a custom OAuth2 library.