Uygulamanızı Azure AD’ye kaydetme ve RMS için etkinleştirmeHow to register and RMS enable your app with Azure AD

Bu konu başlığı altında, Azure portalı üzerinden uygulama kaydı ve RMS etkinleştirme için temel işlemlerde ve ardından Azure Active Directory Authentication Library (ADAL) ile kullanıcı kimlik doğrulamasında size yol gösterilir.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).

Kullanıcı kimlik doğrulaması nedirWhat is user authentication

Kullanıcı kimlik doğrulaması cihaz uygulamanız ve RMS altyapısı arasında iletişim kurmak için önemli bir adımdır.User authentication is an essential step to establish communication between your device app and the RMS infrastructure. Bu kimlik doğrulama işleminde, geçerli kullanıcı ve kimlik doğrulama isteği hakkında temel bilgiler gerektiren standart OAuth 2.0 protokolü kullanılır.This authentication process uses the standard OAuth 2.0 protocol which requires key pieces of information about the current user and the authentication request.

Azure portalı üzerinden kayıtRegistration via Azure portal

Azure portalı üzerinden uygulamanızın kaydını yapılandırmak için bu kılavuzu izleyerek işe başlayın: Azure RMS’yi ADAL kimlik doğrulaması için yapılandırma.Begin by following this guide for configuring your app's registration through the Azure portal, Configure Azure RMS for ADAL authentication. Daha sonra kullanmak üzere bu işlemden İstemci Kimliği ve Yeniden Yönlendirme Uri’si değerlerini kopyalayıp sakladığınızdan emin olun.Be sure to copy and save the Client ID and Redirect Uri from this process for use later.

Information Protection Tümleştirme Sözleşmenizi (APIA) tamamlamaComplete your Information Protection Integration Agreement (IPIA)

Uygulamanızı dağıtabilmeniz için önce Microsoft Information Protection ekibiyle bir IPIA’yı tamamlamanız gerekir.Before you can deploy your application, you must complete an IPIA with the Microsoft Information Protection team. Tüm ayrıntılar için Üretime dağıtma konusunun ilk bölümüne bakın.For complete details, see the first section of the topic, Deploy into production.

Uygulamanız için kullanıcı kimlik doğrulaması yapmaImplement user authentication for your app

RMS API'lerinin her birinde, kullanıcının kimlik doğrulamasını etkinleştirmek için uygulanması gereken bir geri çağırma vardır.Each RMS API has a callback that must be implemented in order to enable the user's authentication. Erişim belirtecinizin yenilenmesi gerektiğinde veya erişim belirtecinizin süresi dolduğunda, bir erişim belirteci sunulmaz, RMS SDK 4.2 sonra geri çağırması uygulamanızı kullanır.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.

Kimlik doğrulaması için hangi kitaplık kullanılmalıWhat library to use for authentication

Kimlik doğrulama geri çağırmanızı uygulamak için, uygun bir kitaplık indirmeniz ve geliştirme ortamını bunu kullanmak üzere yapılandırmanız gerekir.In order to implement your authentication callback you will need to download an appropriate library and configure your development environment to use it. Bu platformlar için ADAL kitaplıklarını GitHub'da bulabilirsiniz.You will find the ADAL libraries on GitHub for these platforms.

Aşağıdaki kaynakların her biri, ortamınızın kurulumu ve kitaplık kullanımı için kılavuz içerir.Each of the following resources contains guidance to setup your environment and use the library.

Not

ADAL’lerden birini kullanmanızı öneririz, ancak başka kimlik doğrulama kitaplıkları da kullanabilirsiniz.We recommend that you use one of the ADAL although you may use other authentication libraries.

Kimlik doğrulama parametreleriAuthentication parameters

ADAL, bir kullanıcının kimliğini Azure RMS’ye (veya AD RMS) başarıyla doğrulamak için bazı bilgiler gerektirir.ADAL requires several pieces of information to successfully authenticate a user to Azure RMS (or AD RMS). Bunlar, standart OAuth 2.0 parametreleridir ve genellikle tüm Azure AD uygulamalarında gerekir.These are standard OAuth 2.0 parameters and are generally required of any Azure AD app. ADAL kullanımı için güncel kılavuzları, daha önce listelenmiş olan ilgili Github depolarının README dosyasında bulursunuz.You will find the current guidelines for ADAL usage in the README file of the corresponding Github repositories, listed previously.

  • Yetkili – Genellikle AAD veya ADFS olan kimlik doğrulama uç noktası için URL.Authority – the URL for the authentication end-point, usually AAD or ADFS.
  • Kaynak - genelde Azure RMS veya AD RMS olan, erişmeye çalıştığınız hizmet uygulamasının URL/URI'si.Resource - the URL/URI of the service application you are trying to access, usually Azure RMS or AD RMS.
  • Kullanıcı Kimliği – Uygulamaya erişmek isteyen kullanıcının UPN’si, genelde e-posta adresi.User Id – the UPN, usually email address, of the user who wants to access the app. Bu parametre, kullanıcı henüz bilinmiyorsa boş olabilir ve kullanıcı simgesinin önbelleğe alınması veya önbellekten bir simge istemek için de kullanılabilir.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. Bu ayrıca genellikle, kullanıcıdan istemek için ipucu olarak da kullanılır.It is also generally used as a hint for user prompting.
  • İstemci kimliği – istemci uygulamanızın kimliği.Client Id – the ID of your client app. Bu, geçerli bir Azure uygulama kimliği olmalıdırThis must be a valid Azure AD application ID. ve Azure portalı üzerinden yapılan önceki kayıt adımından gelir.and comes from the previous registration step via the Azure portal.
  • Yeniden yönlendirme Uri'si – kimlik doğrulama kodu için, URI hedefiyle kimlik doğrulama kitaplığını sağlar.Redirect Uri – provides the authentication library with a URI target for the authentication code. iOS ve Android için özel biçimler gerekir.Specific formats are required for iOS and Android. Bunlar, ADAL’nin ilgili GitHub depolarının README dosyalarında açıklanır.These are explained in the README files of the corresponding GitHub repositories of ADAL. Bu değer Azure portalı üzerinden yapılan önceki kayıt adımından gelir.This value comes from the previous registration step via the Azure portal.

Not

Kapsam şu anda kullanılmamaktadır ancak kullanılabilir ve bu nedenle gelecekteki kullanım için saklanmıştır.Scope is not currently used but may be and is therefore reserved for future use.

Android: `msauth://packagename/Base64UrlencodedSignature`

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

Not

Uygulamanız bu kılavuzları izlemiyorsa, Azure RMS ve Azure AD iş akışları olasılıkla başarısız olur ve Microsoft.com tarafından desteklenmez.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. Ayrıca, bir üretim uygulamasında geçersiz bir İstemci Kimliği kullanılırsa, Hak Yönetimi Lisans Sözleşmesi (RMLA) ihlal edilebilir.Further, the Rights Management License Agreement (RMLA) may be violated if an invalid Client Id is used in a production app.

Bir kimlik doğrulama geri çağırma uygulaması neye benzemelidirWhat should an authentication callback implementation look like

Kimlik Doğrulaması Kodu Örnekleri - Bu SDK’de, kimlik doğrulama geri çağırmaları kullanımını gösteren kod örneği vardır.Authentication Code Examples - This SDK has example code showing the use of authentication callbacks. Size kolaylık sağlamak için, bu kod örnekleri, burada ve sonraki bağlı konuların her birinde verilmiştir.For your convenience, these code examples are represented here as well as in each of the follow linked topics.

Android kullanıcı kimlik doğrulaması - daha fazla bilgi için, bkz. ilk senaryoda 2. Adım, "RMS korumalı dosya kullanma", Android kod örnekleri.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());
                            }
                        }
                    });
                     }

iOS/OS X kullanıcı kimlik doğrulaması - daha fazla bilgi için, bkz. ilk senaryoda 2. Adım, "RMS korumalı dosya kullanma", iOS/OS X kod örnekleri.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);
                      }
                  }

    ];
}

Linux kullanıcı kimlik doğrulaması - daha fazla bilgi için, bkz. Linux kod örnekleri.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;
  }
}