이 문서에서는 ADAL(Azure Active Directory 인증 라이브러리)을 사용하는 애플리케이션을 MSAL(Microsoft 인증 라이브러리)으로 마이그레이션하기 위해 수행해야 하는 변경 내용을 강조 표시합니다.
Java용 Microsoft 인증 라이브러리(MSAL4J) 및 ADAL4J(Java용 Azure AD 인증 라이브러리)는 Microsoft Entra 엔터티를 인증하고 Microsoft Entra ID 토큰을 요청하는 데 사용됩니다. 지금까지 대부분의 개발자는 aDAL(Azure AD 인증 라이브러리)을 사용하여 토큰을 요청하여 개발자용 Azure AD(v1.0)와 협력하여 회사 및 학교 계정과 같은 다양한 ID로 인증했습니다.
MSAL은 다음과 같은 이점을 제공합니다.
- 최신 Microsoft ID 플랫폼을 사용하므로 Microsoft Entra ID, Microsoft 계정, Azure AD Business to Consumer(Azure AD B2C)를 통한 소셜 및 로컬 계정, 그리고 Microsoft Entra 외부 ID를 통한 소셜 또는 로컬 고객 계정과 같이 더 다양한 Microsoft ID를 인증할 수 있습니다.
- 사용자는 최상의 Single Sign-On 환경을 얻을 수 있습니다.
- 애플리케이션은 증분 동의를 사용하도록 설정하고 조건부 액세스와 같은 새로운 기능을 지원할 수 있습니다.
Java용 MSAL은 Microsoft ID 플랫폼과 함께 사용할 것을 권장하는 인증 라이브러리입니다. ADAL4J에는 새로운 기능이 구현되지 않습니다. 앞으로의 모든 노력은 MSAL 개선에 초점을 맞추고 있습니다.
MSAL에 대해 자세히 알아보고 Microsoft 인증 라이브러리 개요를 시작할 수 있습니다.
리소스가 아닌 범위
ADAL4J는 리소스에 대한 토큰을 획득하는 반면 Java MSAL은 범위에 대한 토큰을 획득합니다. Java 클래스에 대한 많은 MSAL에는 범위 매개 변수가 필요합니다. 이 매개 변수는 요청된 원하는 권한 및 리소스를 선언하는 문자열 목록입니다. 예제 범위를 보려면 Microsoft Graph 범위를 참조하세요.
리소스에 /.default 범위 접미사를 추가하여 ADAL에서 MSAL로 앱을 마이그레이션할 수 있습니다. 예를 들어 리소스 값의 https://graph.microsoft.com경우 해당하는 범위 값은 다음과 같습니다 https://graph.microsoft.com/.default. 리소스가 URL 형식이 아니지만 XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX 형식의 리소스 ID인 경우에도 XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default를 범위 값으로 계속 사용할 수 있습니다.
다양한 유형의 범위에 대한 자세한 내용은 Microsoft ID 플랫폼의 권한 및 동의 및 v1.0 토큰을 허용하는 웹 API의 범위 문서를 참조하세요.
핵심 클래스
ADAL4J에서 AuthenticationContext 클래스는 Authority를 통해 STS(보안 토큰 서비스), 즉 권한 부여 서버에 대한 연결을 나타냅니다. 그러나 Java MSAL은 클라이언트 애플리케이션을 중심으로 설계되었습니다. 클라이언트 애플리케이션을 PublicClientApplicationConfidentialClientApplication 나타내는 두 개의 별도 클래스를 제공합니다. 후자는 ConfidentialClientApplication디먼 앱의 애플리케이션 식별자와 같은 비밀을 안전하게 유지 관리하도록 설계된 애플리케이션을 나타냅니다.
다음 표에서는 ADAL4J 함수가 Java 함수에 대해 새 MSAL에 매핑되는 방법을 보여 줍니다.
| ADAL4J 메서드 | MSAL4J 메서드 |
|---|---|
| acquireToken(String resource, ClientCredential credential, AuthenticationCallback 콜백) | ClientCredentialParameters |
| acquireToken(String 리소스, ClientAssertion 어설션, AuthenticationCallback 콜백) | ClientCredentialParameters |
| acquireToken(String resource, AsymmetricKeyCredential credential, AuthenticationCallback 콜백) | ClientCredentialParameters |
| acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback) | UserNamePasswordParameters |
| acquireToken(String resource, String clientId, String username, String password=null, AuthenticationCallback callback) | IntegratedWindowsAuthenticationParameters |
| acquireToken(String resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback 콜백) | OnBehalfOfParameters |
| acquireTokenByAuthorizationCode() | AuthorizationCodeParameters |
| acquireDeviceCode() 및 acquireTokenByDeviceCode() | DeviceCodeFlowParameters |
| acquireTokenByRefreshToken() | SilentParameters |
IUser가 아니라 IAccount
ADAL4J는 사용자를 처리했습니다. 사용자는 단일 사용자 또는 소프트웨어 에이전트를 나타내지만 Microsoft ID 시스템에 하나 이상의 계정을 가질 수 있습니다. 예를 들어, 사용자는 여러 개의 Microsoft Entra ID, Azure AD B2C 또는 Microsoft 개인 계정을 가지고 있을 수 있습니다.
MSAL for Java는 IAccount 인터페이스를 통해 Account라는 개념을 정의합니다. 이는 ADAL4J의 호환성이 손상되는 변경입니다. 동일한 사용자가 여러 계정을 가질 수 있고 다른 Microsoft Entra 디렉터리에 있을 수도 있다는 사실을 캡처합니다. Java MSAL은 홈 계정 정보가 제공되므로 게스트 시나리오에서 더 나은 정보를 제공합니다.
캐시 지속성
ADAL4J는 토큰 캐시를 지원하지 않았습니다. msAL for Java 토큰 캐시를 추가하여 가능하면 만료된 토큰을 자동으로 새로 고쳐서 가능하면 사용자가 자격 증명을 제공할 필요가 없도록 하여 토큰 수명 관리를 간소화합니다.
공통 기관
v1.0에서 권한을 사용하는 https://login.microsoftonline.com/common 경우 사용자는 모든 Microsoft Entra 계정(모든 조직의 경우)으로 로그인할 수 있습니다.
v2.0에서 권한을 사용하는 https://login.microsoftonline.com/common 경우 사용자는 모든 Microsoft Entra 조직 또는 MSA(Microsoft 개인 계정)로 로그인할 수 있습니다. Java MSAL에서 Microsoft Entra 계정으로 로그인을 제한하려면 권한(ADAL4J와 동일한 동작)을 사용합니다https://login.microsoftonline.com/organizations. 권한 부여 기관을 지정하려면 PublicClientApplication 클래스의 인스턴스를 만들 때 PublicClientApplication.Builder 메서드에서 authority 매개 변수를 설정합니다.
v1.0 및 v2.0 토큰
v1.0 엔드포인트(ADAL에서 사용)는 v1.0 토큰만 내보낸다.
v2.0 엔드포인트(MSAL에서 사용)는 v1.0 및 v2.0 토큰을 내보낼 수 있습니다. 웹 API의 애플리케이션 매니페스트 속성을 사용하면 개발자가 허용되는 토큰 버전을 선택할 수 있습니다.
애플리케이션 매니페스트 참조 설명서에서 accessTokenAcceptedVersion을(를) 참조하세요.
v1.0 및 v2.0 토큰에 대한 자세한 내용은 Microsoft Entra 액세스 토큰을 참조하세요.
ADAL에서 MSAL로 마이그레이션
ADAL4J에서 새로 고침 토큰이 노출되어 개발자가 이를 캐시할 수 있었습니다. 그런 다음 사용자가 더 이상 연결되지 않을 때 사용자를 대신하여 대시보드를 새로 고치는 장기 실행 서비스를 구현하는 등의 솔루션을 사용하도록 AcquireTokenByRefreshToken() 설정합니다.
Java MSAL은 보안상의 이유로 새로 고침 토큰을 노출하지 않습니다. 대신, MSAL은 사용자 대신 토큰 새로 고침을 처리합니다.
Java용 MSAL은 ADAL4J로 획득한 리프레시 토큰을 ClientApplication: RefreshTokenParameters로 마이그레이션할 수 있도록 하는 API를 제공합니다. 이 메서드를 사용하면 이전에 사용한 새로 고침 토큰을 원하는 범위(리소스)와 함께 제공할 수 있습니다. 새로 고침 토큰은 새 토큰으로 교환되고 애플리케이션에서 사용하기 위해 캐시됩니다.
다음 코드 조각은 기밀 클라이언트 애플리케이션의 간단한 마이그레이션 코드 조각을 보여줍니다.
String rt = GetCachedRefreshTokenForSignedInUser(); // Get refresh token from where you have them stored
Set<String> scopes = Collections.singleton("SCOPE_FOR_REFRESH_TOKEN");
RefreshTokenParameters parameters = RefreshTokenParameters.builder(scopes, rt).build();
PublicClientApplication app = PublicClientApplication.builder(CLIENT_ID) // ClientId for your application
.authority(AUTHORITY) //plug in your authority
.build();
IAuthenticationResult result = app.acquireToken(parameters);
IAuthenticationResult는 액세스 토큰과 ID 토큰을 반환하며, 새 리프레시 토큰은 캐시에 저장됩니다. 이제 애플리케이션에 다음이 포함됩니다.IAccount
Set<IAccount> accounts = app.getAccounts().join();
현재 캐시에 있는 토큰을 사용하려면 다음을 호출합니다.
SilentParameters parameters = SilentParameters.builder(scope, accounts.iterator().next()).build();
IAuthenticationResult result = app.acquireToken(parameters);