Налаштування Azure AD та автентифікація Microsoft Graph
Aspose.Email for Java забезпечує повну інтеграцію з Microsoft Graph, дозволяючи розробникам керувати повідомленнями, контактами, календарями та завданнями з облікових записів Microsoft 365. Цей посібник проведе вас через створення застосунку Azure AD та налаштування автентифікації для початку роботи з Aspose.Email GraphClient.
Перш ніж використовувати API Microsoft Graph з Aspose.Email, потрібно зареєструвати застосунок в Azure Active Directory (Azure AD) та налаштувати автентифікацію. На цій сторінці розглядаються:
-
Створення застосунку Azure AD (проєкту).
-
Призначення необхідних дозволів Microsoft Graph.
-
Створення облікових даних (client ID, client secret, tenant ID).
-
Автентифікація в Java за допомогою провайдерів токенів Aspose.Email.
Після завершення ви будете готові взаємодіяти з Microsoft Graph зі свого Java‑додатку.
1. Створення застосунку Azure AD
Виконайте наступні кроки, щоб зареєструвати ваш застосунок у порталі Azure:
- Увійдіть у Портал Azure.
- Перейдіть до Azure Active Directory → App Registrations → New Registration.
- Введіть Name вашого застосунку (наприклад, AsposeEmailGraphApp).
- Виберіть підтримувані типи облікових записів:
- Одноорганізаційний (якщо його буде використовувати лише ваша організація)
- Багатокористувацький (якщо кілька організацій потребують доступу)
- За потреби встановіть Redirect URI (потрібно для інтерактивної або веб‑автентифікації).
- Натисніть Register.
2. Створення секрету клієнта
- Після реєстрації перейдіть до Certificates & Secrets → New Client Secret.
- Додайте опис та термін дії.
- Скопіюйте згенероване значення секрету – ви більше не зможете його побачити.
Збережіть client secret у безпеці; він потрібен для автентифікації конфіденційного клієнта.
Ви повинні бачити панель новостворених зареєстрованих застосунків.
3. Налаштування дозволів Microsoft Graph
- Перейдіть до API Permissions → Add a Permission → Microsoft Graph.
- Оберіть тип дозволів: Delegated або Application, залежно від вашого сценарію.
- Додайте дозволи, необхідні для операцій Aspose.Email:
- Contacts.ReadWrite – для керування контактами
- Calendars.ReadWrite – для керування календарями
- Mail.ReadWrite – для читання та надсилання повідомлень
- Tasks.ReadWrite – для керування завданнями
- Натисніть Grant Admin Consent, якщо потрібно.
4. Дозволити потоки публічних клієнтів
Вкажіть, чи є застосунок публічним клієнтом. Підходить для додатків, які використовують потоки видачі токенів без перенаправлення URI.
5. Автентифікація Microsoft Graph
Підтримувані методи автентифікації в Aspose.Email
| Провайдер токенів | Випадок використання | | ——————————– | ————————————————————————————— | | AzureConfidentialTokenProvider | Конфіденційний клієнт (client ID + secret) для серверних додатків | | AzureROPCConfiguration | Облікові дані власника ресурсу (ім’я користувача + пароль) для неінтерактивних сценаріїв | | AzurePublicTokenProvider | Публічний клієнт (інтерактивний вхід) | | AzureTokenProviderBase | Базовий клас для користувацьких реалізацій автентифікації |
Автентифікація за допомогою конфіденційного клієнта
Використайте AzureConfidentialTokenProvider для автентифікації, коли у вас є client ID, client secret та tenant ID:
AzureConfidentialTokenProvider provider = new AzureConfidentialTokenProvider(
tenantId,
clientId,
clientSecret
);
IGraphClient client = GraphClient.getClient(provider, tenantId);
client.setResource(ResourceType.Users);
client.setResourceId(username);
client.setEndpoint("https://graph.microsoft.com");
Це налаштовує повністю автентифікований IGraphClient, готовий до взаємодії з Microsoft Graph.
Автентифікація за допомогою ROPC (ім’я користувача та пароль)
Для випадків, коли у вас є ім’я користувача та пароль, використовуйте AzureROPCConfiguration:
AzureROPCConfiguration ropcConfig = new AzureROPCConfiguration(
tenantId,
clientId,
clientSecret,
username,
password
);
IGraphClient client = GraphClient.getClient(ropcConfig, tenantId);
client.setResource(ResourceType.Users);
client.setResourceId(username);
client.setEndpoint("https://graph.microsoft.com");
Власні постачальники токенів для Microsoft Graph
Aspose.Email for Java інтегрується з Microsoft Graph через IGraphClient інтерфейс. Для автентифікації запитів потрібна реалізація ITokenProvider потрібен. Хоча більшість розробників використовують вбудовані постачальники автентифікації, існують випадки, коли ви можете захотіти створити власний провайдер, наприклад, при роботі з потоком Resource Owner Password Credentials (ROPC).
1. Реалізація ITokenProvider за допомогою AzureROPCTokenProvider
Цей клас надає реалізацію ITokenProvider за допомогою потоку Azure Resource Owner Password Credentials (ROPC). Наступний приклад призначений лише для демонстрації. У виробничому середовищі ми рекомендуємо використовувати більш безпечні потоки, такі як облікові дані клієнта або код авторизації з PKCE.
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.UnsupportedEncodingException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLDecoder;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
/**
* <p>
* Azure resource owner password credential (ROPC) token provider
* https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth-ropc
* https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth
* https://portal.azure.com
* https://developer.microsoft.com/en-us/graph/graph-explorer/#
* token parser https://jwt.io
* </p>
*/
class AzureROPCTokenProvider implements ITokenProvider {
private static final String GRANT_TYPE = "password";
private final String clientId;
private final String clientSecret;
private final String userName;
private final String password;
private final String tenant;
private final String scope;
private OAuthToken token;
public AzureROPCTokenProvider(String tenant, String clientId, String clientSecret,
String userName, String password, String[] scopeAr) {
this.tenant = tenant;
this.clientId = clientId;
this.clientSecret = clientSecret;
this.userName = userName;
this.password = password;
this.scope = joinToStr(scopeAr, " ");
}
public synchronized OAuthToken getAccessToken(boolean ignoreExistingToken) {
if (this.token != null && !this.token.getExpired() && !ignoreExistingToken)
return this.token;
token = null;
Map<String, String> tokenArgs = getToken();
java.util.Calendar c = java.util.Calendar.getInstance();
c.add(java.util.Calendar.SECOND, Integer.parseInt(tokenArgs.get("expires_in")));
token = new OAuthToken(tokenArgs.get("access_token"), TokenType.AccessToken, c.getTime());
return token;
}
public final OAuthToken getAccessToken() {
return getAccessToken(false);
}
public void dispose() {
}
private String getEncodedParameters() {
return "client_id=" + urlEncode(clientId) + "&scope=" + urlEncode(scope) + "&username=" + urlEncode(userName)
+ "&password=" + urlEncode(password) + "&grant_type="
+ urlEncode(GRANT_TYPE);
}
private String getUri() {
if (tenant == null || tenant.trim().isEmpty())
return "https://login.microsoftonline.com/common/oauth2/v2.0/token";
else
return "https://login.microsoftonline.com/" + tenant + "/oauth2/v2.0/token";
}
private Map<String, String> getToken() {
try {
HttpURLConnection connection = (HttpURLConnection) new URL(getUri()).openConnection();
connection.setRequestMethod("POST");
byte[] requestData = getEncodedParameters().getBytes(StandardCharsets.UTF_8);
connection.setUseCaches(false);
connection.setDoInput(true);
connection.setDoOutput(true);
connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
connection.setRequestProperty("Content-Length", "" + requestData.length);
final OutputStream st = connection.getOutputStream();
try {
st.write(requestData, 0, requestData.length);
} finally {
st.flush();
st.close();
}
connection.connect();
if (connection.getResponseCode() >= HttpURLConnection.HTTP_BAD_REQUEST) {
throw new IllegalAccessError("Operation failed: " + connection.getResponseCode() + "/" +
connection.getResponseMessage() + "\r\nDetails:\r\n{2}"
+ readInputStream(connection.getErrorStream()));
}
String responseText = readInputStream(connection.getInputStream());
Map<String, String> result = new HashMap<>();
String[] fromJsonToKeyValue = responseText.replace("{", "").replace("}", "")
.replace("\"", "").replace("\r", "")
.replace("\n", "").split(",");
for (String keyValue : fromJsonToKeyValue) {
String[] pair = keyValue.split(":");
String name = pair[0].trim().toLowerCase();
String value = urlDecode(pair[1].trim());
result.put(name, value);
}
return result;
} catch (IOException e) {
throw new IllegalAccessError(e.getMessage());
}
}
static String urlEncode(String value) {
try {
return URLEncoder.encode(value, StandardCharsets.UTF_8.toString());
} catch (UnsupportedEncodingException e) {
throw new IllegalAccessError(e.getMessage());
}
}
static String urlDecode(String value) {
try {
return URLDecoder.decode(value, StandardCharsets.UTF_8.toString());
} catch (UnsupportedEncodingException e) {
throw new IllegalAccessError(e.getMessage());
}
}
static String readInputStream(InputStream is) {
if (is == null)
return "";
BufferedReader reader = new BufferedReader(new InputStreamReader(is));
StringBuilder result = new StringBuilder();
String line;
try {
while ((line = reader.readLine()) != null) {
result.append(line);
}
} catch (IOException e) {
// ignore
}
return result.toString();
}
static String joinToStr(String[] arr, String sep) {
StringBuilder sb = new StringBuilder();
for (int i = 0; i < arr.length; i++) {
if (i > 0)
sb.append(sep);
sb.append(arr[i]);
}
return sb.toString();
}
}
2. Створення об’єкта ITokenProvider
The IGraphClient інтерфейс відповідає за формування запитів, їх надсилання до Microsoft Graph і обробку відповідей. Щоб створити екземпляр IGraphClient, ви повинні надати реалізацію ITokenProvider. Провайдер токенів автентифікує запити, надаючи дійсний OAuth токен доступу.
Наступний приклад коду демонструє, як створити базову вбудовану реалізацію ITokenProvider інтерфейс, який потрібен для автентифікації запитів Microsoft Graph:
ITokenProvider tokenProvider = new ITokenProvider() {
Date expirationDate = null;
@Override
public void dispose() {
// Clean up resources if necessary
}
@Override
public OAuthToken getAccessToken(boolean ignoreExistingToken) {
// Retrieve an OAuth access token.
// If ignoreExistingToken is true, always request a new token.
// Otherwise, return the existing token if it is valid, or request a new one.
return null;
}
@Override
public OAuthToken getAccessToken() {
// Return a valid OAuth token.
// If no valid token exists, request a new one.
return new OAuthToken("token", expirationDate);
}
};
3. Використання власного постачальника токенів
Як тільки ITokenProvider налаштовано, ви можете створити GraphClient екземпляр. Цей клієнт буде використовувати наданий токен‑провайдер для автентифікації під час виклику Microsoft Graph.
ITokenProvider provider = new AzureROPCTokenProvider(
tenantId,
clientId,
clientSecret,
userName,
password,
new String[] {"https://graph.microsoft.com/.default"}
);
IGraphClient client = GraphClient.getClient(provider, tenantId);
client.setResource(ResourceType.Users);
client.setResourceId(userName);
client.setEndpoint("https://graph.microsoft.com");
// Now you can call Microsoft Graph APIs
var folders = client.listFolders(null);
for (GraphFolderInfo folder : folders) {
System.out.println(folder.getDisplayName());
}
Після створення та автентифікації клієнта ви можете почати надсилати запити до сервісів Microsoft Graph.