Gör så här: Registrera och RMS-aktivera din app med Azure ADHow to register and RMS enable your app with Azure AD

Det här avsnittet går igenom grunderna i appregistrering och RMS-aktivering via Azure Portal samt användarautentisering med ADAL (Azure Active Directory Authentication Library).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).

Vad är användarautentisering?What is user authentication

Användarautentisering är ett grundläggande steg för att upprätta kommunikation mellan din enhetsapp och RMS-infrastrukturen.User authentication is an essential step to establish communication between your device app and the RMS infrastructure. I den här autentiseringsprocessen används standardprotokollet OAuth 2.0 som kräver uppgifter om aktuell användare och autentiseringsbegäran.This authentication process uses the standard OAuth 2.0 protocol which requires key pieces of information about the current user and the authentication request.

Registrering via Azure PortalRegistration via Azure portal

Börja med att följa anvisningarna i den här guiden för att konfigurera appens registrering via Azure Portal enligt Konfigurera Azure RMS för ADAL-autentisering.Begin by following this guide for configuring your app's registration through the Azure portal, Configure Azure RMS for ADAL authentication. Kopiera och spara klient-ID och omdirigerings-Uri när du gör detta. Du kommer att behöva dem senare.Be sure to copy and save the Client ID and Redirect Uri from this process for use later.

Fyll i ditt Information Protection Integration-avtal (IPIA)Complete your Information Protection Integration Agreement (IPIA)

Innan du kan distribuera ditt program så måste du fylla i ett IPIA med Microsoft Information Protection-teamet.Before you can deploy your application, you must complete an IPIA with the Microsoft Information Protection team. Fullständig information finns i det första avsnittet av ämnet, Distribuera till produktion.For complete details, see the first section of the topic, Deploy into production.

Implementera användarautentisering för din appImplement user authentication for your app

Varje RMS-API har ett återanrop som måste implementeras för att aktivera användarautentiseringen.Each RMS API has a callback that must be implemented in order to enable the user's authentication. RMS SDK 4.2 använder din implementering av återanropet om du inte anger ett åtkomsttoken, om ditt åtkomsttoken behöver uppdateras eller om åtkomsttoken har upphört att gälla.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.

Vilket bibliotek som ska användas för autentiseringWhat library to use for authentication

För att kunna implementera autentiseringsåteranropry måste du hämta ett lämpligt bibliotek och konfigurera din utvecklingsmiljö för att använda det.In order to implement your authentication callback you will need to download an appropriate library and configure your development environment to use it. Du hittar ADA-biblioteken på GitHub för dessa plattformar.You will find the ADAL libraries on GitHub for these platforms.

Var och en av följande resurser innehåller vägledning för konfigurering av din miljö och användning av biblioteket.Each of the following resources contains guidance to setup your environment and use the library.

Anteckning

Det går visserligen att även använda andra autentiseringsbibliotek, men vi rekommenderar att du använder något av ovanstående ADAL-bibliotek.We recommend that you use one of the ADAL although you may use other authentication libraries.

AutentiseringsparametrarAuthentication parameters

ADAL kräver flera uppgifter för att kunna autentisera en användare till Azure RMS (eller AD RMS).ADAL requires several pieces of information to successfully authenticate a user to Azure RMS (or AD RMS). Detta är OAuth 2.0-standardparametrar. Dessa krävs normalt för alla Azure AD-appar.These are standard OAuth 2.0 parameters and are generally required of any Azure AD app. Du hittar de aktuella riktlinjerna för ADAL-användning i filen VIKTIGT för de Github-lagringsplatser som anges ovan.You will find the current guidelines for ADAL usage in the README file of the corresponding Github repositories, listed previously.

  • Utfärdare – URL: en för autentiseringsslutpunkten, vanligtvis AAD eller AD FS.Authority – the URL for the authentication end-point, usually AAD or ADFS.
  • Resurs – URL/URI för tjänstprogrammet som du försöker komma åt, vanligtvis Azure RMS eller AD RMS.Resource - the URL/URI of the service application you are trying to access, usually Azure RMS or AD RMS.
  • Användar-ID – UPN-namnet, vanligtvis e-postadressen till den användare som vill få åtkomst till appen.User Id – the UPN, usually email address, of the user who wants to access the app. Denna parameter kan vara tom om användaren ännu inte är känd och används även för cachelagring av användartoken eller för att begära ett token från cacheminnet.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. Det används också i allmänhet som ett tips för att ställa frågor till användaren.It is also generally used as a hint for user prompting.
  • Klient-ID – Klientappens ID.Client Id – the ID of your client app. Detta måste vara ett giltigt program-ID för Azure AD.This must be a valid Azure AD application ID. Värdet kommer från det föregående registreringssteget via Azure Portal.and comes from the previous registration step via the Azure portal.
  • Omdirigerings-Uri – ger autentiseringsbiblioteket ett URI-mål för autentiseringskoden.Redirect Uri – provides the authentication library with a URI target for the authentication code. Det krävs specifika format för iOS och Android.Specific formats are required for iOS and Android. Dessa beskrivs i VIKTIGT-filerna på motsvarande GitHub-lagringsplatser för ADAL.These are explained in the README files of the corresponding GitHub repositories of ADAL. Det här värdet kommer från det föregående registreringssteget via Azure Portal.This value comes from the previous registration step via the Azure portal.

Anteckning

Omfattning används inte för närvarande men kan komma att användas, och är därför reserverad för framtida användning.Scope is not currently used but may be and is therefore reserved for future use.

Android: msauth://packagename/Base64UrlencodedSignatureAndroid: msauth://packagename/Base64UrlencodedSignature

Stoppa <app-scheme>://<bundle-id>iOS: <app-scheme>://<bundle-id>

Anteckning

Om din app inte följer dessa riktlinjer utförs troligen inte Azure RMS- och AD Azure-arbetsflödena och de stöds inte av 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. Dessutom kan Rights Management-licensavtalet (RMLA) överträdas om ett ogiltigt klient-ID används i ett produktionsprogram.Further, the Rights Management License Agreement (RMLA) may be violated if an invalid Client Id is used in a production app.

Hur bör en implementering av ett autentiseringsåteranrop se ut?What should an authentication callback implementation look like

Exempel på autentiseringskod – Denna SDK innehåller exempelkod som visar hur autentiseringsåteranrop används.Authentication Code Examples - This SDK has example code showing the use of authentication callbacks. För att underlätta för dig visas dessa kodexempel här samt i vart och ett av de länkade avsnitten nedan.en.For your convenience, these code examples are represented here as well as in each of the follow linked topics.

Android-användarautentisering – mer information finns i Android-kodexempel, steg 2 av det första scenariot ”Använda en RMS-skyddad fil”.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-ABCDEFGH12"; // 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());
                                }
                            }
                        });
                         }

iOS/OS X-användarautentisering – mer information finns i iOS/OS X-kodexempel, steg 2 av det första scenariot ”Använda en RMS-skyddad fil”.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-ABCDEFGH12";

    // 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);
                          }
                      }

        ];
    }

Linux-användarautentisering – mer information finns i Linux-kodexempel.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;
      }
    }