Azure AD でアプリの登録と RMS の有効化を行う方法How to register and RMS enable your app with Azure AD

このトピックでは、Azure ポータルによるアプリ登録と RMS 有効化の基本事項を説明した後、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).

ユーザー認証とはWhat is user authentication

ユーザー認証は、デバイス アプリケーションと RMS インフラストラクチャ間の通信を確立するために不可欠な手順です。User authentication is an essential step to establish communication between your device app and the RMS infrastructure. この認証プロセスでは、標準の OAuth 2.0 プロトコルを使用します。これには、現在のユーザーと認証要求に関する重要な情報が必要になります。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 ポータルでの登録Registration via Azure portal

まず、Azure ポータルでアプリの登録を構成するためのガイド「Configure Azure RMS for ADAL authentication (Azure RMS の ADAL 認証を構成する)」に従ってください。Begin by following this guide for configuring your app's registration through the Azure portal, Configure Azure RMS for ADAL authentication. 後で使用するために、このプロセスでのクライアント IDリダイレクト URI をコピーして保存しておいてください。Be sure to copy and save the Client ID and Redirect Uri from this process for use later.

Information Protection Integration Agreement (IPIA) を完了するComplete your Information Protection Integration Agreement (IPIA)

アプリケーションを展開する前に、Microsoft Information Protection チームとの IPIA を完了する必要があります。Before you can deploy your application, you must complete an IPIA with the Microsoft Information Protection team. 完全な詳細については、トピック「運用環境にデプロイする」の最初のセクションを参照してください。For complete details, see the first section of the topic, Deploy into production.

アプリのユーザー認証の実装Implement user authentication for your app

各 RMS API には、ユーザーの認証を有効にするために実装する必要があるコールバックがあります。Each RMS API has a callback that must be implemented in order to enable the user's authentication. RMS SDK 4.2 は、アクセス トークンを指定しなかった場合、アクセス トークンを更新する必要がある場合、またはアクセス トークンの有効期限が切れている場合に、このコールバックの実装を使用します。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.

認証に使用するライブラリWhat library to use for authentication

認証コールバックを実装するには、適切なライブラリをダウンロードして、それを使用するように開発環境を構成する必要があります。In order to implement your authentication callback you will need to download an appropriate library and configure your development environment to use it. これらのプラットフォーム用の ADAL ライブラリが GitHub に用意されています。You will find the ADAL libraries on GitHub for these platforms.

次の各リソースには、環境をセットアップして、ライブラリを使用するためのガイダンスが含まれています。Each of the following resources contains guidance to setup your environment and use the library.

注意

他の認証ライブラリも使用できますが、ADAL のいずれかを使用することをお勧めします。We recommend that you use one of the ADAL although you may use other authentication libraries.

認証パラメーターAuthentication parameters

ADAL は、Azure RMS (または AD RMS) に対してユーザーを認証するために、いくつかの情報を必要とします。ADAL requires several pieces of information to successfully authenticate a user to Azure RMS (or AD RMS). これらの情報は標準の OAuth 2.0 パラメーターであり、一般にどの Azure AD アプリにも求められます。These are standard OAuth 2.0 parameters and are generally required of any Azure AD app. ADAL 使用法の現行のガイドラインについては、前に記載された対応する Github リポジトリの README ファイルをご覧ください。You will find the current guidelines for ADAL usage in the README file of the corresponding Github repositories, listed previously.

  • 権限 – 認証エンドポイントの URL。通常は AAD または ADFS です。Authority – the URL for the authentication end-point, usually AAD or ADFS.
  • リソース - アクセスしようとしているサービス アプリケーション (通常 Azure RMS または AD RMS) の URL/URI。Resource - the URL/URI of the service application you are trying to access, usually Azure RMS or AD RMS.
  • ユーザー ID – UPN。通常は、アプリにアクセスするユーザーの電子メール アドレスです。User Id – the UPN, usually email address, of the user who wants to access the app. このパラメーターは、ユーザーが不明の場合は空にできます。また、ユーザー トークンをキャッシュしたり、キャッシュからトークンを要求したりする場合にも使用できます。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. 一般的に、ユーザー プロンプトのヒントとしても使用されます。It is also generally used as a hint for user prompting.
  • クライアント ID – クライアント アプリの ID。Client Id – the ID of your client app. 有効な Azure AD アプリケーションの ID である必要があります。This must be a valid Azure AD application ID. また、前述の Azure ポータルでの登録手順で取得したものです。and comes from the previous registration step via the Azure portal.
  • リダイレクト URI – 認証コードの対象の URI で認証ライブラリを指定します。Redirect Uri – provides the authentication library with a URI target for the authentication code. iOS および Android では、特定の形式が必要になります。Specific formats are required for iOS and Android. これらの形式については、ADAL の対応する GitHub リポジトリの README ファイルで説明されています。These are explained in the README files of the corresponding GitHub repositories of ADAL. この値は、前述の Azure ポータルでの登録手順で取得したものです。This value comes from the previous registration step via the Azure portal.

注意

範囲は現在使用されていませんが、今後の使用のために予約されています。Scope is not currently used but may be and is therefore reserved for future use.

Android: `msauth://packagename/Base64UrlencodedSignature`

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

注意

アプリがこれらのガイドラインを遵守しない場合、Azure RMS および Azure AD ワークフローが失敗することがあり、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. また、運用アプリケーションで無効なクライアント ID を使用した場合、Rights Management License Agreement (RMLA) 違反が発生する可能性があります。Further, the Rights Management License Agreement (RMLA) may be violated if an invalid Client Id is used in a production app.

認証コールバックの実装の例What should an authentication callback implementation look like

認証コード例 - この SDK には、認証コールバックの使用を示すコード例が含まれています。Authentication Code Examples - This SDK has example code showing the use of authentication callbacks. ご参考のためにここに、また以下のリンクされたトピックでいくつかのコード例を紹介します。For your convenience, these code examples are represented here as well as in each of the follow linked topics.

Android ユーザー認証 - 詳しくは、「Android のコード例、最初のシナリオのステップ 2、「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());
                            }
                        }
                    });
                     }

iOS/OS X ユーザー認証 - 詳しくは、「iOS/OS X のコード例」の最初のシナリオ「RMS 保護ファイルを使用する」のステップ 2 をご覧ください。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 ユーザー認証 - 詳しくは、「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;
  }
}