Como registar-se e ativar o RMS na aplicação com o Azure ADHow to register and RMS enable your app with Azure AD

Este tópico irá guiá-lo sobre as noções básicas de registo da aplicação e de ativação do RMS através do portal do Azure, seguido da autenticação de utilizador com a 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).

O que é a autenticação de utilizadorWhat is user authentication

A autenticação de utilizador é um passo essencial para estabelecer a comunicação entre a aplicação do dispositivo e a infraestrutura de RMS.User authentication is an essential step to establish communication between your device app and the RMS infrastructure. Este processo de autenticação utiliza o protocolo OAuth 2.0 padrão que requer peças chave de informação acerca do utilizador atual e do pedido de autenticação.This authentication process uses the standard OAuth 2.0 protocol which requires key pieces of information about the current user and the authentication request.

Registo através do portal do AzureRegistration via Azure portal

Comece por seguir este guia para configurar o registo da aplicação através do portal do Azure, Configurar o Azure RMS para a autenticação da ADAL.Begin by following this guide for configuring your app's registration through the Azure portal, Configure Azure RMS for ADAL authentication. Certifique-se de que copia e guarda o ID de cliente e Redireciona o URI a partir deste processo para uma utilização posterior.Be sure to copy and save the Client ID and Redirect Uri from this process for use later.

Preencher o Contrato de Integração do Information Protection (IPIA)Complete your Information Protection Integration Agreement (IPIA)

Para poder implementar a aplicação, tem de preencher um IPIA com a equipa do Microsoft Information Protection.Before you can deploy your application, you must complete an IPIA with the Microsoft Information Protection team. Para obter informações detalhadas completas, veja a primeira secção do tópico, Implementar na produção.For complete details, see the first section of the topic, Deploy into production.

Implementar a autenticação de utilizador para a aplicaçãoImplement user authentication for your app

Cada uma das APIs do RMS tem uma chamada de retorno que tem de ser implementada para ativar a autenticação do utilizador.Each RMS API has a callback that must be implemented in order to enable the user's authentication. O SDK RMS 4.2 utilizará, em seguida, a implementação de uma chamada de retorno quando o utilizador não fornecer um token de acesso, quando o seu token de acesso necessitar de ser atualizado ou quando o token de acesso tiver expirado.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.

Qual biblioteca utilizar para a autenticaçãoWhat library to use for authentication

Para poder implementar a sua chamada de retorno de autenticação, terá de transferir uma biblioteca adequada e configurar o ambiente de desenvolvimento para utilizá-la.In order to implement your authentication callback you will need to download an appropriate library and configure your development environment to use it. Poderá encontrar no GitHub, as bibliotecas ADAL para estas plataformas.You will find the ADAL libraries on GitHub for these platforms.

Cada um dos seguintes recursos contém orientações sobre a configuração do ambiente e a utilização da biblioteca.Each of the following resources contains guidance to setup your environment and use the library.

Nota

Recomendamos que utilize uma das ADAL, embora possa utilizar outras bibliotecas de autenticação.We recommend that you use one of the ADAL although you may use other authentication libraries.

Parâmetros de autenticaçãoAuthentication parameters

A ADAL requer várias informações para autenticar com êxito um utilizador no Azure RMS (ou AD RMS).ADAL requires several pieces of information to successfully authenticate a user to Azure RMS (or AD RMS). Estes são os parâmetros OAuth 2.0 padrão e normalmente são necessários em qualquer aplicação Azure AD.These are standard OAuth 2.0 parameters and are generally required of any Azure AD app. Encontrará as diretrizes atuais para a utilização da ADAL no ficheiro LEIA-ME dos repositórios do Github correspondentes, listados anteriormente.You will find the current guidelines for ADAL usage in the README file of the corresponding Github repositories, listed previously.

  • Autoridade – o URL para o ponto final de autenticação, normalmente AAD ou ADFS.Authority – the URL for the authentication end-point, usually AAD or ADFS.
  • Recurso – o URL/URI da aplicação de serviço à qual está a tentar aceder, normalmente, o Azure RMS ou o AD RMS.Resource - the URL/URI of the service application you are trying to access, usually Azure RMS or AD RMS.
  • ID de Utilizador – o UPN, normalmente o endereço de e-mail do utilizador que pretende aceder à aplicação.User Id – the UPN, usually email address, of the user who wants to access the app. Este parâmetro pode estar vazio se o utilizador ainda não for conhecido e também é utilizado para colocar em cache o token de utilizador ou pedir um token a partir da 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. Também é geralmente utilizado como uma sugestão para consultar o utilizador.It is also generally used as a hint for user prompting.
  • ID de Cliente – a ID da aplicação de cliente.Client Id – the ID of your client app. Tem de ser uma ID da aplicação válida do Azure AD.This must be a valid Azure AD application ID. e provém do passo de registo anterior através do portal do Azure.and comes from the previous registration step via the Azure portal.
  • URI de Redirecionamento – fornece a biblioteca de autenticação com um destino URI para o código de autenticação.Redirect Uri – provides the authentication library with a URI target for the authentication code. São necessários formatos específicos para iOS e para Android.Specific formats are required for iOS and Android. Estes são explicados nos ficheiros LEIA-ME dos repositórios do GitHub correspondentes da ADAL.These are explained in the README files of the corresponding GitHub repositories of ADAL. Este valor provém do passo de registo anterior através do portal do Azure.This value comes from the previous registration step via the Azure portal.
Nota

O âmbito não é utilizado atualmente mas poderá ser e, por isso, está reservado para utilização futura.Scope is not currently used but may be and is therefore reserved for future use.

Android: `msauth://packagename/Base64UrlencodedSignature`

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

Se a aplicação não seguir estas diretrizes, é provável que os fluxos de trabalho do Azure RMS e do Azure AD falhem e não sejam suportados pela 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. Além disso, o Contrato de Licença de Rights Management (RMLA) pode ser violado se uma ID de Cliente inválida for utilizada numa aplicação de produção.Further, the Rights Management License Agreement (RMLA) may be violated if an invalid Client Id is used in a production app.

Qual deverá ser o aspeto de uma implementação de chamada de retorno de autenticaçãoWhat should an authentication callback implementation look like

Exemplos de Código de Autenticação – Este SDK tem o código de exemplo que mostra a utilização de chamadas de retorno de autenticação.Authentication Code Examples - This SDK has example code showing the use of authentication callbacks. Para comodidade do utilizador, estes exemplos de código são representados aqui, bem como em cada um dos seguintes tópicos relacionados.For your convenience, these code examples are represented here as well as in each of the follow linked topics.

Autenticação de utilizador do Android – para obter mais informações, consulte Exemplos de código do Android, Passo 2 do primeiro cenário, “Consumir um ficheiro protegido por 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());
                            }
                        }
                    });
                     }

Autenticação de utilizador do iOS/OS X – para obter mais informações, consulte Exemplos de código do iOS/OS X, Passo 2 do primeiro cenário, “Consumir um ficheiro protegido por 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);
                      }
                  }

    ];
}

Autenticação de utilizador do Linux – para obter mais informações, consulte Exemplos de código do 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;
  }
}

ComentáriosComments

Antes de inserir um comentário, pedimos-lhe que reveja as nossas Regras básicas.Before commenting, we ask that you review our House rules.