Postup při registraci vaší aplikace v rámci služby Azure AD a jejím povolování pro službu RMS
Důležité
Verze sady SDK služby Microsoft Rights Management vydané před březnem 2020 jsou zastaralé; aplikace používající starší verze musí být aktualizovány, aby používaly verzi z března 2020. Úplné podrobnosti najdete v oznámení o vyřazení.
Pro sadu SDK služby Microsoft Rights Management Service se neplánují žádná další vylepšení. Důrazně doporučujeme přijmout sadu Microsoft Information Protection SDK pro klasifikaci, popisky a služby ochrany.
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).
Co je ověření uživatele
Ověření uživatele je základním krokem k navázání komunikace mezi vaší aplikací a infrastrukturou RMS. 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í.
Registrace prostřednictvím portálu Azure
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). 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í.
Uzavření smlouvy IPIA (Information Protection Integration Agreement)
Před nasazením aplikace je nutné uzavřít smlouvu IPIA s týmem Microsoft Information Protection. Podrobnosti o vyplnění a uzavření smlouvy najdete v první části tématu Nasazení do provozu.
Implementace ověřování uživatele pro vaši aplikaci
Každé rozhraní API RMS má k dispozici zpětné volání, které se musí implementovat, aby bylo možné ověřovat uživatele. 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.
- Android – AuthenticationRequestCallback a AuthenticationCompletionCallback – rozhraní.
- iOS / OS X – PROTOKOL MSAuthenticationCallback .
- Windows Phone / Window RT - IAuthenticationCallback rozhraní.
- Linux – IAuthenticationCallback rozhraní.
Jakou knihovnu používat pro ověřování
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í. Na GitHubu najdete knihovny ADAL pro tyto platformy.
U každého z následujících zdrojů informací najdete pokyny k instalaci prostředí a použití knihovny.
- Windows Azure Active Directory Authentication Library (ADAL) pro iOS
- Windows Azure Active Directory Authentication Library (ADAL) pro Mac
- Windows Azure Active Directory Authentication Library (ADAL) pro Android
- Windows Azure Active Directory Authentication Library (ADAL) pro dotnet
- V případě sady Linux SDK je knihovna ADAL v balíčku se zdrojem sady SDK, který je dostupný přes Github.
Poznámka
Doporučujeme používat jednu z knihoven ADAL, můžete ale samozřejmě používat i jiné knihovny ověřování.
Parametry ověřování
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í. Jsou to standardní parametry protokolu OAuth 2.0, které se obecně vyžadují od všech aplikací Azure AD. Aktuální pokyny pro používání knihovny ADAL najdete v souboru README odpovídajících úložišť Github uvedených výše.
- Autorita – Adresa URL pro koncový bod ověřování, obvykle AAD nebo AD FS.
- 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.
- ID uživatele – Hlavní název uživatele (UPN), obvykle e-mailová adresa uživatele, který žádá o přístup k aplikaci. 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. Obvykle se také používá jako nápověda pro výzvu uživateli.
- ID klienta – ID vaší klientské aplikace. Musí se jednat o platné ID aplikace Azure AD. Pochází z předchozího kroku registrace prostřednictvím 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. Pro systémy iOS a Android se vyžadují specifické formáty. Tyto informace jsou vysvětleny v souborech README odpovídajících úložišť Github pro knihovnu ADAL. Tato hodnota pochází z předchozího kroku registrace prostřednictvím Azure Portal.
Poznámka
Scope (Obor) se v současné době nepoužívá. Je vyhrazen pro budoucí použití.
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).
Jak by měla implementace zpětného volání pro ověřování vypadat
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í. Z praktického důvodu jsou tyto příklady kódu uváděny zde a také v jednotlivých odkazovaných tématech.
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.
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());
}
}
});
}
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.
// 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);
}
}
];
}
Ověření uživatele využívajícího Linux – Další informace najdete v tématu Příklady kódu pro systém Linux.
// 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;
}
}