Penyiapan Azure AD dan Otentikasi Microsoft Graph

Aspose.Email for Java menyediakan integrasi penuh dengan Microsoft Graph, memungkinkan pengembang mengelola pesan, kontak, kalender, dan tugas dari akun Microsoft 365. Panduan ini memandu Anda membuat aplikasi Azure AD dan mengonfigurasi otentikasi untuk mulai mengkode dengan Aspose.Email GraphClient.

Sebelum menggunakan API Microsoft Graph dengan Aspose.Email, Anda harus mendaftarkan aplikasi di Azure Active Directory (Azure AD) dan mengonfigurasi otentikasi. Halaman ini mencakup:

  • Membuat aplikasi Azure AD (proyek).

  • Menetapkan izin Microsoft Graph yang diperlukan.

  • Menghasilkan kredensial (client ID, client secret, tenant ID).

  • Mengautentikasi di Java menggunakan penyedia token Aspose.Email.

Setelah selesai, Anda akan siap berinteraksi dengan Microsoft Graph dari aplikasi Java Anda.

1. Buat Aplikasi Azure AD

Ikuti langkah-langkah berikut untuk mendaftarkan aplikasi Anda di portal Azure:

  1. Masuk ke Portal Azure.
  2. Arahkan ke Azure Active Directory → App Registrations → New Registration.

todo:image_alt_text

  1. Masukkan Name untuk aplikasi Anda (misalnya, AsposeEmailGraphApp).
  2. Pilih jenis akun yang didukung:
    • Single tenant (jika hanya organisasi Anda yang akan menggunakannya)
    • Multitenant (jika beberapa organisasi memerlukan akses)
  3. Opsional, atur Redirect URI (diperlukan untuk otentikasi interaktif atau web).
  4. Klik Register.

todo:image_alt_text

2. Buat Client Secret

  1. Setelah pendaftaran, pergi ke Certificates & Secrets → New Client Secret.
  2. Tambahkan deskripsi dan periode kedaluwarsa.

todo:image_alt_text

  1. Salin nilai rahasia yang dihasilkan - Anda tidak akan melihatnya lagi.

Jaga client secret tetap aman; diperlukan untuk otentikasi klien rahasia.

Anda akan melihat bilah aplikasi yang baru terdaftar.

todo:image_alt_text

3. Konfigurasikan Izin Microsoft Graph

  1. Arahkan ke API Permissions → Add a Permission → Microsoft Graph.
  2. Pilih jenis izin: Delegated atau Application, tergantung pada skenario Anda.
  3. Tambahkan izin yang diperlukan untuk operasi Aspose.Email:
    • Contacts.ReadWrite – untuk mengelola kontak
    • Calendars.ReadWrite – untuk mengelola kalender
    • Mail.ReadWrite – untuk membaca dan mengirim pesan
    • Tasks.ReadWrite – untuk mengelola tugas
  4. Klik Grant Admin Consent jika diperlukan.

todo:image_alt_text

4. Izinkan alur klien publik

Tentukan apakah aplikasi adalah klien publik. Sesuai untuk aplikasi yang menggunakan alur pemberian token yang tidak menggunakan URI pengalihan.

todo:image_alt_text

5. Otentikasi Microsoft Graph

Metode Otentikasi yang Didukung di Aspose.Email

| Penyedia Token | Kasus Penggunaan | | ——————————– | ————————————————————————————— | | AzureConfidentialTokenProvider | Klien rahasia (client ID + secret) untuk aplikasi sisi server | | AzureROPCConfiguration | Kredensial Kata Sandi Pemilik Sumber Daya (nama pengguna + kata sandi) untuk skenario non-interaktif | | AzurePublicTokenProvider | Klien publik (login interaktif) | | AzureTokenProviderBase | Kelas dasar untuk implementasi otentikasi kustom |

Autentikasi Menggunakan Klien Rahasia

Gunakan AzureConfidentialTokenProvider untuk mengautentikasi ketika Anda memiliki client ID, client secret, dan 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");

Ini menyiapkan IGraphClient yang sepenuhnya terautentikasi siap berinteraksi dengan Microsoft Graph.

Autentikasi Menggunakan ROPC (Nama Pengguna & Kata Sandi)

Untuk skenario di mana Anda memiliki nama pengguna dan kata sandi, gunakan 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");

Penyedia Token Kustom untuk Microsoft Graph

Aspose.Email for Java terintegrasi dengan Microsoft Graph melalui IGraphClient antarmuka. Untuk mengautentikasi permintaan, implementasi dari ITokenProvider dibutuhkan. Walaupun kebanyakan pengembang akan menggunakan penyedia otentikasi bawaan, ada skenario di mana Anda mungkin ingin membuat penyedia Anda sendiri, misalnya saat bekerja dengan alur Resource Owner Password Credentials (ROPC).

1. Implementasikan ITokenProvider menggunakan AzureROPCTokenProvider

Kelas ini menyediakan implementasi dari ITokenProvider menggunakan alur Azure Resource Owner Password Credentials (ROPC). Contoh berikut hanya untuk tujuan demonstrasi. Dalam produksi, kami menyarankan penggunaan alur yang lebih aman seperti kredensial klien atau kode otorisasi dengan 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. Buat Objek ITokenProvider

The IGraphClient antarmuka bertanggung jawab untuk membangun permintaan, mengirimnya ke Microsoft Graph, dan menangani respons. Untuk membuat sebuah instance dari IGraphClient, Anda harus menyediakan implementasi dari ITokenProvider. Penyedia token mengautentikasi permintaan dengan menyediakan token akses OAuth yang valid.

Contoh kode berikut menunjukkan cara membuat implementasi inline dasar dari ITokenProvider antarmuka, yang diperlukan untuk mengautentikasi permintaan 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. Menggunakan Penyedia Token Kustom

Setelah ITokenProvider sudah disiapkan, Anda dapat membuat sebuah GraphClient instance. Klien ini akan menggunakan token provider yang diberikan untuk otentikasi saat memanggil 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());
}

Setelah klien dibuat dan diautentikasi, Anda dapat mulai membuat permintaan ke layanan Microsoft Graph.

Bekerja dengan Folder menggunakan Microsoft Graph