Postup při registraci vaší aplikace v rámci služby Azure AD a jejím povolování pro službu RMSHow to register and RMS enable your app with Azure AD

Toto téma vás provede základy registrace aplikací a povolování RMS prostřednictvím portálu Azure, po nichž následuje ověření uživatele s použitím knihovny 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).

Co je ověření uživateleWhat is user authentication

Ověření uživatele je základním krokem k navázání komunikace mezi vaší aplikací a infrastrukturou RMS.User authentication is an essential step to establish communication between your device app and the RMS infrastructure. Tento proces ověřování využívá standardní protokol OAuth 2.0, který vyžaduje klíčové informace o aktuálním uživateli a žádosti o ověření.This authentication process uses the standard OAuth 2.0 protocol which requires key pieces of information about the current user and the authentication request.

Registrace prostřednictvím portálu AzureRegistration via Azure portal

Začněte konfigurováním registrace vaší aplikace prostřednictvím portálu Azure podle této příručky (Konfigurace Azure RMS pro ověřování ADAL).Begin by following this guide for configuring your app's registration through the Azure portal, Configure Azure RMS for ADAL authentication. Nezapomeňte zkopírovat a uložit ID klienta a identifikátor URI pro přesměrování z tohoto procesu pro pozdější použití.Be sure to copy and save the Client ID and Redirect Uri from this process for use later.

Uzavření smlouvy IPIA (Information Protection Integration Agreement)Complete your Information Protection Integration Agreement (IPIA)

Před nasazením aplikace je nutné uzavřít smlouvu IPIA s týmem Microsoft Information Protection.Before you can deploy your application, you must complete an IPIA with the Microsoft Information Protection team. Podrobnosti o vyplnění a uzavření smlouvy najdete v první části tématu Nasazení do provozu.For complete details, see the first section of the topic, Deploy into production.

Implementace ověřování uživatele pro vaši aplikaciImplement user authentication for your app

Každé rozhraní API RMS má k dispozici zpětné volání, které se musí implementovat, aby bylo možné ověřovat uživatele.Each RMS API has a callback that must be implemented in order to enable the user's authentication. Sada SDK RMS 4.2 pak použije vaši implementaci zpětného volání v případě, že neposkytnete přístupový token, že se přístupový token musí aktualizovat nebo že přístupovému tokenu vypršela platnost.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.

Jakou knihovnu používat pro ověřováníWhat library to use for authentication

Aby bylo možné implementovat vaše zpětné volání pro ověřování, budete si muset stáhnout příslušnou knihovnu a nakonfigurovat si její používání ve vývojovém prostředí.In order to implement your authentication callback you will need to download an appropriate library and configure your development environment to use it. Na GitHubu najdete knihovny ADAL pro tyto platformy.You will find the ADAL libraries on GitHub for these platforms.

U každého z následujících zdrojů informací najdete pokyny k instalaci prostředí a použití knihovny.Each of the following resources contains guidance to setup your environment and use the library.

Poznámka

Doporučujeme používat jednu z knihoven ADAL, můžete ale samozřejmě používat i jiné knihovny ověřování.We recommend that you use one of the ADAL although you may use other authentication libraries.

Parametry ověřováníAuthentication parameters

Pro úspěšné ověření uživatele v rámci služby Azure RMS (nebo služby AD RMS) vyžaduje knihovna ADAL několik informací.ADAL requires several pieces of information to successfully authenticate a user to Azure RMS (or AD RMS). Jsou to standardní parametry protokolu OAuth 2.0, které se obecně vyžadují od všech aplikací Azure AD.These are standard OAuth 2.0 parameters and are generally required of any Azure AD app. Aktuální pokyny pro používání knihovny ADAL najdete v souboru README odpovídajících úložišť Github uvedených výše.You will find the current guidelines for ADAL usage in the README file of the corresponding Github repositories, listed previously.

  • Autorita – Adresa URL pro koncový bod ověřování, obvykle AAD nebo AD FS.Authority – the URL for the authentication end-point, usually AAD or ADFS.
  • Prostředek – Adresa URL nebo identifikátor URI aplikace služby, ke které se pokoušíte získat přístup, obvykle Azure RMS nebo AD RMS.Resource - the URL/URI of the service application you are trying to access, usually Azure RMS or AD RMS.
  • ID uživatele – Hlavní název uživatele (UPN), obvykle e-mailová adresa uživatele, který žádá o přístup k aplikaci.User Id – the UPN, usually email address, of the user who wants to access the app. Tento parametr může být prázdný, pokud je ještě uživatel neznámý, a používá se také pro ukládání tokenu uživatele do mezipaměti nebo pro požadování tokenu z mezipaměti.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. Obvykle se také používá jako nápověda pro výzvu uživateli.It is also generally used as a hint for user prompting.
  • ID klienta – ID vaší klientské aplikace.Client Id – the ID of your client app. Musí se jednat o platné ID aplikace Azure AD.This must be a valid Azure AD application ID. a pochází z předchozího kroku registrace prostřednictvím portálu Azure.and comes from the previous registration step via the Azure portal.
  • Identifikátor URI pro přesměrování – Poskytuje knihovnu ověřování s cílovým identifikátorem URI pro ověřovací kód.Redirect Uri – provides the authentication library with a URI target for the authentication code. Pro systémy iOS a Android se vyžadují specifické formáty.Specific formats are required for iOS and Android. Tyto informace jsou vysvětleny v souborech README odpovídajících úložišť Github pro knihovnu ADAL.These are explained in the README files of the corresponding GitHub repositories of ADAL. Tato hodnota pochází z předchozího kroku registrace prostřednictvím portálu Azure.This value comes from the previous registration step via the Azure portal.

Poznámka

Scope (Obor) se v současné době nepoužívá. Je vyhrazen pro budoucí použití.Scope is not currently used but may be and is therefore reserved for future use.

Android: `msauth://packagename/Base64UrlencodedSignature`

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

Poznámka

Pokud se pro vaši aplikaci tyto pokyny nedodrží, pracovní postupy služeb Azure RMS a Azure AD s největší pravděpodobností selžou a aplikace nebude na webu Microsoft.com podporována. Pokud se bude v aplikaci v produkčním prostředí používat neplatné ID klienta, nebudou navíc dodrženy podmínky smlouvy Rights Management License Agreement (RMLA).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. Further, the Rights Management License Agreement (RMLA) may be violated if an invalid Client Id is used in a production app.

Jak by měla implementace zpětného volání pro ověřování vypadatWhat should an authentication callback implementation look like

Příklady ověřovacího kódu – Tato sada SDK obsahuje příklad kódu znázorňujícího používání zpětných volání pro ověřování.Authentication Code Examples - This SDK has example code showing the use of authentication callbacks. Z praktického důvodu jsou tyto příklady kódu uváděny zde a také v jednotlivých odkazovaných tématech.For your convenience, these code examples are represented here as well as in each of the follow linked topics.

Ověření uživatelů zařízení s Androidem – Další informace najdete v tématu Příklady kódu pro systém Android, Krok 2 prvního scénáře, Využívání souboru chráněného službou 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());
                            }
                        }
                    });
                     }

Ověření uživatelů zařízení se systémem iOS/OS X – Další informace najdete v tématu Příklady kódu pro systém iOS/OS X, Krok 2 prvního scénáře, Využívání souboru chráněného službou 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);
                      }
                  }

    ];
}

Ověření uživatele využívajícího Linux – Další informace najdete v tématu Příklady kódu pro systém 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;
  }
}

KomentářeComments

Před přidáním komentáře se podívejte na naše pravidla organizace.Before commenting, we ask that you review our House rules.