Procédure d’inscription et d’activation RMS de votre application dans Azure ADHow to register and RMS enable your app with Azure AD

Cette rubrique décrit les concepts de base de l’inscription d’une application et de son activation RMS dans le portail Azure, puis l’authentification utilisateur avec Azure Active Directory Authentication Library (ADAL).This topic will guide you through the basics of app registration and RMS enablement through the Azure portal followed by user authentication with the Azure Active Directory Authentication Library (ADAL).

Qu’est-ce que l’authentification utilisateur ?What is user authentication

L’authentification utilisateur est une étape essentielle pour établir la communication entre votre application et l’infrastructure RMS.User authentication is an essential step to establish communication between your device app and the RMS infrastructure. Ce processus d’authentification utilise le protocole OAuth 2.0 standard qui nécessite les éléments d’information suivants sur l’utilisateur actuel et sur sa demande d’authentification.This authentication process uses the standard OAuth 2.0 protocol which requires key pieces of information about the current user and the authentication request.

Inscription dans le portail AzureRegistration via Azure portal

Commencez par suivre ce guide pour configurer l’inscription de votre application dans le portail Azure, Configurer Azure RMS pour l’authentification ADAL.Begin by following this guide for configuring your app's registration through the Azure portal, Configure Azure RMS for ADAL authentication. Copiez et enregistrez l’ID client et l’URI de redirection de ce processus pour les utiliser plus tard.Be sure to copy and save the Client ID and Redirect Uri from this process for use later.

Signature d'un IPIA (Information Protection Integration Agreement)Complete your Information Protection Integration Agreement (IPIA)

Avant de pouvoir déployer votre application, vous devez signer un contrat IPIA avec l’équipe Microsoft Information Protection.Before you can deploy your application, you must complete an IPIA with the Microsoft Information Protection team. Pour plus d’informations, consultez la première section de la rubrique Déployer en production.For complete details, see the first section of the topic, Deploy into production.

Implémenter l’authentification utilisateur pour votre applicationImplement user authentication for your app

Chacune des API RMS a un rappel qui doit être implémenté pour activer l’authentification de l’utilisateur.Each RMS API has a callback that must be implemented in order to enable the user's authentication. RMS SDK 4.2 utilise votre implémentation du rappel quand vous ne fournissez pas de jeton d’accès, que votre jeton d’accès doit être actualisé ou que le jeton d’accès a expiré.The RMS SDK 4.2 will then use your implementation of the callback when you do not provide an access token, when your access token needs to be refreshed or when the access token is expired.

Bibliothèque à utiliser pour l’authentificationWhat library to use for authentication

Pour implémenter votre rappel d’authentification, vous devez télécharger une bibliothèque appropriée et de configurer votre environnement de développement pour qu’il l’utilise.In order to implement your authentication callback you will need to download an appropriate library and configure your development environment to use it. Les bibliothèques ADAL pour ces plateformes se trouvent sur GitHub.You will find the ADAL libraries on GitHub for these platforms.

Chacune des ressources suivantes contient de l’aide pour la configuration de votre environnement et pour l’utilisation de la bibliothèque.Each of the following resources contains guidance to setup your environment and use the library.

Note

Nous vous recommandons d’utiliser une des bibliothèques ADAL, même si vous pouvez utiliser d’autres bibliothèques d’authentification.We recommend that you use one of the ADAL although you may use other authentication libraries.

Paramètres d’authentificationAuthentication parameters

La bibliothèque ADAL nécessite plusieurs éléments d’information pour authentifier un utilisateur dans Azure RMS (ou AD RMS).ADAL requires several pieces of information to successfully authenticate a user to Azure RMS (or AD RMS). Il s’agit de paramètres OAuth 2.0 standard qui sont généralement nécessaires pour toutes les applications Azure AD.These are standard OAuth 2.0 parameters and are generally required of any Azure AD app. Les instructions d’utilisation de la bibliothèque ADAL sont disponibles dans le fichier LISEZ-MOI des dépôts Github correspondants indiqués.You will find the current guidelines for ADAL usage in the README file of the corresponding Github repositories, listed previously.

  • Autorité : l’URL pour le point de terminaison d’authentification, généralement AAD ou ADFS.Authority – the URL for the authentication end-point, usually AAD or ADFS.
  • Ressource : l’URL/URI de l’application de service à laquelle vous essayez d’accéder, généralement Azure RMS ou AD RMS.Resource - the URL/URI of the service application you are trying to access, usually Azure RMS or AD RMS.
  • ID utilisateur : l’UPN, généralement une adresse de messagerie, de l’utilisateur qui veut accéder à l’application.User Id – the UPN, usually email address, of the user who wants to access the app. Ce paramètre peut être vide si l’utilisateur n’est pas encore connu ; il est également utilisé pour mettre en cache le jeton de l’utilisateur ou pour demander un jeton auprès du cache.This parameter can be empty if the user is not yet known, and is also used for caching the user token or requesting a token from the cache. Il est aussi généralement utilisé comme indicateur pour la confirmation de l’utilisateur.It is also generally used as a hint for user prompting.
  • ID de client : l’ID de votre application cliente.Client Id – the ID of your client app. Il doit s’agir d’un ID d’application Azure AD valide.This must be a valid Azure AD application ID. Il provient de l’étape d’inscription dans le portail Azure.and comes from the previous registration step via the Azure portal.
  • URI de redirection : fournit la bibliothèque d’authentification avec une cible d’URI pour le code d’authentification.Redirect Uri – provides the authentication library with a URI target for the authentication code. Des formats spécifiques sont nécessaires pour iOS et Android.Specific formats are required for iOS and Android. Ils sont expliqués dans les fichiers LISEZ-MOI des dépôts GitHub correspondants de la bibliothèque ADAL.These are explained in the README files of the corresponding GitHub repositories of ADAL. Cette valeur provient de l’étape d’inscription dans le portail Azure.This value comes from the previous registration step via the Azure portal.
Note

L’étendue n’est pas utilisée, mais peut l’être et est donc réservée à une utilisation future.Scope is not currently used but may be and is therefore reserved for future use.

Android: `msauth://packagename/Base64UrlencodedSignature`

iOS: `<app-scheme>://<bundle-id>`
Note

Si votre application ne suit pas ces instructions, les flux de travail Azure RMS et Azure AD risquent d’échouer et ne sont pas pris en charge par Microsoft.com.If your app does not follow these guidelines, Azure RMS and Azure AD workflows are likely to fail and will not be supported by Microsoft.com. En outre, il peut se produire une violation du contrat RMLA si un ID de client non valide est utilisé dans une application de production.Further, the Rights Management License Agreement (RMLA) may be violated if an invalid Client Id is used in a production app.

Exemple d’implémentation d’un rappel d’authentificationWhat should an authentication callback implementation look like

Exemples de code d’authentification : ce SDK comprend un exemple de code montrant l’utilisation de rappels d’authentification.Authentication Code Examples - This SDK has example code showing the use of authentication callbacks. Pour votre commodité, ces exemples de code sont représentés ici, ainsi que dans chacune des rubriques liées.For your convenience, these code examples are represented here as well as in each of the follow linked topics.

Authentification utilisateur Android : pour plus d’informations, consultez Exemples de code Android, Étape 2 du premier scénario, « Consommation d’un fichier protégé par RMS ».Android user authentication - for more information, see Android code examples, Step 2 of the first scenario, "Consuming an RMS protected file".

class MsipcAuthenticationCallback implements AuthenticationRequestCallback
{
...

@Override
public void getToken(Map<String, String> authenticationParametersMap,
                     final AuthenticationCompletionCallback authenticationCompletionCallbackToMsipc)
{
    String authority = authenticationParametersMap.get("oauth2.authority");
    String resource = authenticationParametersMap.get("oauth2.resource");
    String userId = authenticationParametersMap.get("userId");
    mClientId = “12345678-ABCD-ABCD-ABCD-ABCDEFGHIJ”; // get your registered Azure AD application ID here
    mRedirectUri = “urn:ietf:wg:oauth:2.0:oob”;
    final String userHint = (userId == null)? "" : userId;
    AuthenticationContext authenticationContext = App.getInstance().getAuthenticationContext();
    if (authenticationContext == null || !authenticationContext.getAuthority().equalsIgnoreCase(authority))
    {
        try
        {
            authenticationContext = new AuthenticationContext(App.getInstance().getApplicationContext(), authority, …);
            App.getInstance().setAuthenticationContext(authenticationContext);
        }
        catch (NoSuchAlgorithmException e)
        {
            …
            authenticationCompletionCallbackToMsipc.onFailure();
        }
        catch (NoSuchPaddingException e)
        {
            …
            authenticationCompletionCallbackToMsipc.onFailure();
        }
   }
    App.getInstance().getAuthenticationContext().acquireToken(mParentActivity, resource, mClientId, mRedirectURI, userId, mPromptBehavior,
                   "&USERNAME=" + userHint, new AuthenticationCallback<AuthenticationResult>()
                    {
                        @Override
                        public void onError(Exception exc)
                        {
                            …
                            if (exc instanceof AuthenticationCancelError)
                            {
                                 …
                                authenticationCompletionCallbackToMsipc.onCancel();
                            }
                            else
                            {
                                 …
                                authenticationCompletionCallbackToMsipc.onFailure();
                            }
                        }

                        @Override
                        public void onSuccess(AuthenticationResult result)
                        {
                            …
                            if (result == null || result.getAccessToken() == null
                                    || result.getAccessToken().isEmpty())
                            {
                                 …
                            }
                            else
                            {
                                // request is successful
                                …
                                authenticationCompletionCallbackToMsipc.onSuccess(result.getAccessToken());
                            }
                        }
                    });
                     }

Authentification utilisateur iOS/OS X : pour plus d’informations, consultez Exemples de code iOS/OS X, Étape 2 du premier scénario, « Consommation d’un fichier protégé par RMS ».iOS/OS X user authentication - for more information, see iOS/OS X code examples, Step 2 of the first scenario, "Consuming an RMS protected file".

// AuthenticationCallback holds the necessary information to retrieve an access token.
@interface MsipcAuthenticationCallback : NSObject<MSAuthenticationCallback>

@end

@implementation MsipcAuthenticationCallback

- (void)accessTokenWithAuthenticationParameters:
     (MSAuthenticationParameters *)authenticationParameters
                            completionBlock:
     (void(^)(NSString *accessToken, NSError *error))completionBlock
{
ADAuthenticationError *error;
ADAuthenticationContext* context = [ADAuthenticationContext authenticationContextWithAuthority:authenticationParameters.authority error:&error];

NSString *appClientId = @”12345678-ABCD-ABCD-ABCD-ABCDEFGHIJ”;

// get your registered Azure AD application ID here

NSURL *redirectURI = [NSURL URLWithString:@”ms-sample://com.microsoft.sampleapp”];

// get your <app-scheme>://<bundle-id> here
// Retrieve token using ADAL
[context acquireTokenWithResource:authenticationParameters.resource
                         clientId:appClientId
                      redirectUri:redirectURI
                           userId:authenticationParameters.userId
                  completionBlock:^(ADAuthenticationResult *result)
                  {
                      if (result.status != AD_SUCCEEDED)
                      {
                          NSLog(@"Auth Failed");
                          completionBlock(nil, result.error);
                      }
                      else
                      {
                          completionBlock(result.accessToken, result.error);
                      }
                  }

    ];
}

Authentification utilisateur Linux : pour plus d’informations, consultez Exemples de code Linux.Linux user authentication - for more information, see Linux code examples.

// Class Header
class AuthCallback : public IAuthenticationCallback {
private:

  std::shared_ptr<rmsauth::FileCache> FileCachePtr;
  std::string clientId_;
  std::string redirectUrl_;

  public:

  AuthCallback(const std::string& clientId,
           const std::string& redirectUrl);
  virtual std::string GetToken(shared_ptr<AuthenticationParameters>& ap) override;
};

class ConsentCallback : public IConsentCallback {
  public:

  virtual ConsentList Consents(ConsentList& consents) override;
};

// Class Implementation
AuthCallback::AuthCallback(const string& clientId, const string& redirectUrl)
: clientId_(clientId), redirectUrl_(redirectUrl) {
  FileCachePtr = std::make_shared<FileCache>();
}

string AuthCallback::GetToken(shared_ptr<AuthenticationParameters>& ap)
{
  string redirect =
  ap->Scope().empty() ? redirectUrl_ : ap->Scope();

  try
  {
    if (redirect.empty()) {
    throw rmscore::exceptions::RMSInvalidArgumentException(
          "redirect Url is empty");
  }

  if (clientId_.empty()) {
  throw rmscore::exceptions::RMSInvalidArgumentException("client Id is empty");
  }

  AuthenticationContext authContext(
    ap->Authority(), AuthorityValidationType::False, FileCachePtr);

  auto result = authContext.acquireToken(ap->Resource(),
                                       clientId_, redirect,
                                       PromptBehavior::Auto,
                                       ap->UserId());
  return result->accessToken();
  }

  catch (const rmsauth::Exception& ex)
  {
    // out logs
    throw;
  }
}

CommentairesComments

Avant de transmettre vos commentaires, nous vous demandons de consulter notre règlement interne.Before commenting, we ask that you review our House rules.