Build Java apps with Microsoft Graph

Article
Developer (Beginner)
46 minutes to complete

This tutorial teaches you how to build a Java console app that uses the Microsoft Graph API.

Tip

If you prefer to just download the completed tutorial, you can download or clone the GitHub repository.

Prerequisites

Before you start this tutorial, you should have the Java SE Development Kit (JDK) and Gradle installed on your development machine.

You should also have either a personal Microsoft account with a mailbox on Outlook.com, or a Microsoft work or school account. If you don't have a Microsoft account, there are a couple of options to get a free account:

You can sign up for a new personal Microsoft account.
You can sign up for the Microsoft 365 Developer Program to get a free Microsoft 365 subscription.

Note

This tutorial was written with OpenJDK version 17.0.2 and Gradle 7.4.2. The steps in this guide may work with other versions, but that has not been tested.

Register the app in the portal

45 minutes remaining

In this exercise you will register a new application in Azure Active Directory to enable user authentication. You can register an application using the Azure Active Directory admin center, or by using the Microsoft Graph PowerShell SDK.

Register application for user authentication

In this section you will register an application that will support user authentication using device code flow.

Open a browser and navigate to the Azure Active Directory admin center and login using a personal account (aka: Microsoft Account) or Work or School Account.
Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.
Select New registration. Enter a name for your application, for example, Java Graph Tutorial.

Set Supported account types as desired. The options are:

Option	Who can sign in?
Accounts in this organizational directory only	Only users in your Microsoft 365 organization
Accounts in any organizational directory	Users in any Microsoft 365 organization (work or school accounts)
Accounts in any organizational directory ... and personal Microsoft accounts	Users in any Microsoft 365 organization (work or school accounts) and personal Microsoft accounts

Leave Redirect URI empty.
Select Register. On the application's Overview page, copy the value of the Application (client) ID and save it, you will need it in the next step. If you chose Accounts in this organizational directory only for Supported account types, also copy the Directory (tenant) ID and save it.
Select Authentication under Manage. Locate the Advanced settings section and change the Allow public client flows toggle to Yes, then choose Save.

To use PowerShell, you'll need the Microsoft Graph PowerShell SDK. If you do not have it, see Install the Microsoft Graph PowerShell SDK for installation instructions.

Important

The PowerShell script requires a work/school account with the Application administrator, Cloud application administrator, or Global administrator role. If your account has the Application developer role, you can register in the Azure AD admin center.

Create a new file named RegisterAppForUserAuth.ps1 and add the following code.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$false,
  HelpMessage="The sign in audience for the app")]
  [ValidateSet("AzureADMyOrg", "AzureADMultipleOrgs", `
  "AzureADandPersonalMicrosoftAccount", "PersonalMicrosoftAccount")]
  [String]
  $SignInAudience = "AzureADandPersonalMicrosoftAccount",

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

# Tenant to use in authentication.
# See https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code#device-authorization-request
$authTenant = switch ($SignInAudience)
{
  "AzureADMyOrg" { "tenantId" }
  "AzureADMultipleOrgs" { "organizations" }
  "AzureADandPersonalMicrosoftAccount" { "common" }
  "PersonalMicrosoftAccount" { "consumers" }
  default { "invalid" }
}

if ($authTenant -eq "invalid")
{
  Write-Host -ForegroundColor Red "Invalid sign in audience:" $SignInAudience
  Exit
}

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop

if ($authTenant -eq "tenantId")
{
  $authTenant = $context.TenantId
}

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience $SignInAudience `
 -IsFallbackPublicClient -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
if ($SignInAudience -ne "PersonalMicrosoftAccount")
{
  New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
   -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "A service principal for the app could not be created."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }

  Write-Host -ForegroundColor Cyan "Service principal created"
}

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Auth tenant: "
Write-Host -ForegroundColor Yellow $authTenant

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Save the file.
Open PowerShell and change the current directory to the location of RegisterAppForUserAuth.ps1.

Run the following command, replacing <audience-value> with the desired value (see table below).

.\RegisterAppForUserAuth.ps1 -AppName "Java Graph Tutorial" -SignInAudience <audience-value>

SignInAudience value	Who can sign in?
`AzureADMyOrg`	Only users in your Microsoft 365 organization
`AzureADMultipleOrgs`	Users in any Microsoft 365 organization (work or school accounts)
`AzureADandPersonalMicrosoftAccount`	Users in any Microsoft 365 organization (work or school accounts) and personal Microsoft accounts
`PersonalMicrosoftAccount`	Only personal Microsoft accounts

Follow the prompt to open https://microsoft.com/devicelogin in a browser, enter the provided code, and complete the authentication process.
Copy the Client ID and Auth tenant values from the script output. You will need these values in the next step.
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

Note

Notice that you did not configure any Microsoft Graph permissions on the app registration. This is because the sample will use dynamic consent to request specific permissions for user authentication.

Create a Java console app

40 minutes remaining

In this section you'll create a basic Java console app.

Open your command-line interface (CLI) in a directory where you want to create the project. Run the following command to create a new Gradle project.
```
gradle init --dsl groovy --test-framework junit --type java-application --project-name graphtutorial --package graphtutorial
```
Once the project is created, verify that it works by running the following command to run the app in your CLI.
```
./gradlew --console plain run
```
If it works, the app should output Hello World..

Install dependencies

Before moving on, add some additional dependencies that you will use later.

Azure Identity client library for Java to authenticate the user and acquire access tokens.
Microsoft Graph SDK for Java to make calls to the Microsoft Graph.

Open ./app/build.gradle. Update the dependencies section to add those dependencies.

dependencies {
    // Use JUnit test framework.
    testImplementation 'junit:junit:4.13.2'

    // This dependency is used by the application.
    implementation 'com.google.guava:guava:30.1.1-jre'
    implementation 'com.azure:azure-identity:1.5.0'
    implementation 'com.microsoft.graph:microsoft-graph:5.22.0'
}

Add the following to the end of ./app/build.gradle.
```
run {
    standardInput = System.in
}
```
The next time you build the project, Gradle will download those dependencies.

Load application settings

In this section you'll add the details of your app registration to the project.

Create a new directory named graphtutorial in the ./app/src/main/resources directory.

Create a new file in the ./app/src/main/resources/graphtutorial directory named oAuth.properties, and add the following text in that file.

app.clientId=YOUR_CLIENT_ID_HERE
app.clientSecret=YOUR_CLIENT_SECRET_HERE_IF_USING_APP_ONLY
app.tenantId=YOUR_TENANT_ID_HERE_IF_USING_APP_ONLY
app.authTenant=common
app.graphUserScopes=user.read,mail.read,mail.send

Update the values according to the following table.

Setting	Value
`app.clientId`	The client ID of your app registration
`app.authTenant`	If you chose the option to only allow users in your organization to sign in, change this value to your tenant ID. Otherwise leave as `common`.

Important

If you're using source control such as git, now would be a good time to exclude the oAuth.properties file from source control to avoid inadvertently leaking your app ID.

Design the app

In this section you will create a simple console-based menu.

Open ./app/src/main/java/graphtutorial/App.java and add the following import statements.

package graphtutorial;

import java.io.IOException;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.InputMismatchException;
import java.util.Properties;
import java.util.Scanner;

import com.microsoft.graph.models.Message;
import com.microsoft.graph.models.User;
import com.microsoft.graph.requests.MessageCollectionPage;
import com.microsoft.graph.requests.UserCollectionPage;

Replace the existing main function with the following.

public static void main(String[] args) {
    System.out.println("Java Graph Tutorial");
    System.out.println();

    final Properties oAuthProperties = new Properties();
    try {
        oAuthProperties.load(App.class.getResourceAsStream("oAuth.properties"));
    } catch (IOException e) {
        System.out.println("Unable to read OAuth configuration. Make sure you have a properly formatted oAuth.properties file. See README for details.");
        return;
    }

    initializeGraph(oAuthProperties);

    greetUser();

    Scanner input = new Scanner(System.in);

    int choice = -1;

    while (choice != 0) {
        System.out.println("Please choose one of the following options:");
        System.out.println("0. Exit");
        System.out.println("1. Display access token");
        System.out.println("2. List my inbox");
        System.out.println("3. Send mail");
        System.out.println("4. List users (required app-only)");
        System.out.println("5. Make a Graph call");

        try {
            choice = input.nextInt();
        } catch (InputMismatchException ex) {
            // Skip over non-integer input
        }

        input.nextLine();

        // Process user choice
        switch(choice) {
            case 0:
                // Exit the program
                System.out.println("Goodbye...");
                break;
            case 1:
                // Display access token
                displayAccessToken();
                break;
            case 2:
                // List emails from user's inbox
                listInbox();
                break;
            case 3:
                // Send an email message
                sendMail();
                break;
            case 4:
                // List users
                listUsers();
                break;
            case 5:
                // Run any Graph code
                makeGraphCall();
                break;
            default:
                System.out.println("Invalid choice");
        }
    }

    input.close();
}

Add the following placeholder methods at the end of the file. You'll implement them in later steps.

private static void initializeGraph(Properties properties) {
    // TODO
}

private static void greetUser() {
    // TODO
}

private static void displayAccessToken() {
    // TODO
}

private static void listInbox() {
    // TODO
}

private static void sendMail() {
    // TODO
}

private static void listUsers() {
    // TODO
}

private static void makeGraphCall() {
    // TODO
}

This implements a basic menu and reads the user's choice from the command line.

Delete ./app/src/test/java/graphtutorial/AppTest.java.

Add user authentication

35 minutes remaining

In this section you will extend the application from the previous exercise to support authentication with Azure AD. This is required to obtain the necessary OAuth access token to call the Microsoft Graph. In this step you will integrate the Azure Identity client library for Java into the application and configure authentication for the Microsoft Graph SDK for Java.

The Azure Identity library provides a number of TokenCredential classes that implement OAuth2 token flows. The Microsoft Graph client library uses those classes to authenticate calls to Microsoft Graph. In this example, we'll use the following TokenCredential classes.

DeviceCodeCredential implements the device code flow for user authentication.
ClientSecretCredential implements the client credentials flow for app-only authentication. You will use this class in the optional app-only sections.

Configure Graph client for user authentication

In this section you will use the DeviceCodeCredential class to request an access token by using the device code flow.

Create a new file in the ./app/src/main/java/graphtutorial directory named Graph.java and add the following code to that file.

package graphtutorial;

import java.util.Arrays;
import java.util.List;
import java.util.Properties;
import java.util.function.Consumer;

import com.azure.core.credential.AccessToken;
import com.azure.core.credential.TokenRequestContext;
import com.azure.identity.ClientSecretCredential;
import com.azure.identity.ClientSecretCredentialBuilder;
import com.azure.identity.DeviceCodeCredential;
import com.azure.identity.DeviceCodeCredentialBuilder;
import com.azure.identity.DeviceCodeInfo;
import com.microsoft.graph.authentication.TokenCredentialAuthProvider;
import com.microsoft.graph.models.BodyType;
import com.microsoft.graph.models.EmailAddress;
import com.microsoft.graph.models.ItemBody;
import com.microsoft.graph.models.Message;
import com.microsoft.graph.models.Recipient;
import com.microsoft.graph.models.User;
import com.microsoft.graph.models.UserSendMailParameterSet;
import com.microsoft.graph.requests.GraphServiceClient;
import com.microsoft.graph.requests.MessageCollectionPage;
import com.microsoft.graph.requests.UserCollectionPage;

import okhttp3.Request;

Add an empty Graph class definition.
```
public class Graph {
}
```

Add the following code to the Graph class.

private static Properties _properties;
private static DeviceCodeCredential _deviceCodeCredential;
private static GraphServiceClient<Request> _userClient;

public static void initializeGraphForUserAuth(Properties properties, Consumer<DeviceCodeInfo> challenge) throws Exception {
    // Ensure properties isn't null
    if (properties == null) {
        throw new Exception("Properties cannot be null");
    }

    _properties = properties;

    final String clientId = properties.getProperty("app.clientId");
    final String authTenantId = properties.getProperty("app.authTenant");
    final List<String> graphUserScopes = Arrays
        .asList(properties.getProperty("app.graphUserScopes").split(","));

    _deviceCodeCredential = new DeviceCodeCredentialBuilder()
        .clientId(clientId)
        .tenantId(authTenantId)
        .challengeConsumer(challenge)
        .build();

    final TokenCredentialAuthProvider authProvider =
        new TokenCredentialAuthProvider(graphUserScopes, _deviceCodeCredential);

    _userClient = GraphServiceClient.builder()
        .authenticationProvider(authProvider)
        .buildClient();
}

Replace the empty initializeGraph function in App.java with the following.

private static void initializeGraph(Properties properties) {
    try {
        Graph.initializeGraphForUserAuth(properties,
            challenge -> System.out.println(challenge.getMessage()));
    } catch (Exception e)
    {
        System.out.println("Error initializing Graph for user auth");
        System.out.println(e.getMessage());
    }
}

This code declares two private properties, a DeviceCodeCredential object and a GraphServiceClient object. The InitializeGraphForUserAuth function creates a new instance of DeviceCodeCredential, then uses that instance to create a new instance of GraphServiceClient. Every time an API call is made to Microsoft Graph through the _userClient, it will use the provided credential to get an access token.

Test the DeviceCodeCredential

Next, add code to get an access token from the DeviceCodeCredential.

Add the following function to the Graph class.

public static String getUserToken() throws Exception {
    // Ensure credential isn't null
    if (_deviceCodeCredential == null) {
        throw new Exception("Graph has not been initialized for user auth");
    }

    final String[] graphUserScopes = _properties.getProperty("app.graphUserScopes").split(",");

    final TokenRequestContext context = new TokenRequestContext();
    context.addScopes(graphUserScopes);

    final AccessToken token = _deviceCodeCredential.getToken(context).block();
    return token.getToken();
}

Replace the empty displayAccessToken function in App.java with the following.

private static void displayAccessToken() {
    try {
        final String accessToken = Graph.getUserToken();
        System.out.println("Access token: " + accessToken);
    } catch (Exception e) {
        System.out.println("Error getting access token");
        System.out.println(e.getMessage());
    }
}

Build and run the app. Enter 1 when prompted for an option. The application displays a URL and device code.

Java Graph Tutorial

Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. List users (requires app-only)
5. Make a Graph call
1
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and
enter the code RB2RUD56D to authenticate.

Open a browser and browse to the URL displayed. Enter the provided code and sign in.

Important

Be mindful of any existing Microsoft 365 accounts that are logged into your browser when browsing to https://microsoft.com/devicelogin. Use browser features such as profiles, guest mode, or private mode to ensure that you authenticate as the account you intend to use for testing.
Once completed, return to the application to see the access token.

Tip

For validation and debugging purposes only, you can decode user access tokens (for work or school accounts only) using Microsoft's online token parser at https://jwt.ms. This can be useful if you encounter token errors when calling Microsoft Graph. For example, verifying that the scp claim in the token contains the expected Microsoft Graph permission scopes.

Get user

30 minutes remaining

In this section you will incorporate the Microsoft Graph into the application. For this application, you will use the Microsoft Graph Java Client Library to make calls to Microsoft Graph.

Open Graph.java and add the following function to the Graph class.

public static User getUser() throws Exception {
    // Ensure client isn't null
    if (_userClient == null) {
        throw new Exception("Graph has not been initialized for user auth");
    }

    return _userClient.me()
        .buildRequest()
        .select("displayName,mail,userPrincipalName")
        .get();
}

Replace the empty greetUser function in App.java with the following.

private static void greetUser() {
    try {
        final User user = Graph.getUser();
        // For Work/school accounts, email is in mail property
        // Personal accounts, email is in userPrincipalName
        final String email = user.mail == null ? user.userPrincipalName : user.mail;
        System.out.println("Hello, " + user.displayName + "!");
        System.out.println("Email: " + email);
    } catch (Exception e) {
        System.out.println("Error getting user");
        System.out.println(e.getMessage());
    }
}

If you run the app now, after you log in the app welcomes you by name.

Hello, Megan Bowen!
Email: MeganB@contoso.com

Code explained

Consider the code in the greetUser function. It's only a few lines, but there are some key details to notice.

Accessing 'me'

The function uses the _userClient.me request builder, which builds a request to the Get user API. This API is accessible two ways:

GET /me
GET /users/{user-id}

In this case, the code will call the GET /me API endpoint. This is a shortcut method to get the authenticated user without knowing their user ID.

Note

Because the GET /me API endpoint gets the authenticated user, it is only available to apps that use user authentication. App-only authentication apps cannot access this endpoint.

Requesting specific properties

The function uses the select method on the request to specify the set of properties it needs. This adds the $select query parameter to the API call.

Strongly-typed return type

The function returns a com.microsoft.graph.models.User object deserialized from the JSON response from the API. Because the code uses select, only the requested properties will have values in the returned User object. All other properties will have default values.

List inbox

25 minutes remaining

In this section you will add the ability to list messages in the user's email inbox.

Open Graph.java and add the following function to the Graph class.

public static MessageCollectionPage getInbox() throws Exception {
    // Ensure client isn't null
    if (_userClient == null) {
        throw new Exception("Graph has not been initialized for user auth");
    }

    return _userClient.me()
        .mailFolders("inbox")
        .messages()
        .buildRequest()
        .select("from,isRead,receivedDateTime,subject")
        .top(25)
        .orderBy("receivedDateTime DESC")
        .get();
}

Replace the empty listInbox function in App.java with the following.

private static void listInbox() {
    try {
        final MessageCollectionPage messages = Graph.getInbox();

        // Output each message's details
        for (Message message: messages.getCurrentPage()) {
            System.out.println("Message: " + message.subject);
            System.out.println("  From: " + message.from.emailAddress.name);
            System.out.println("  Status: " + (message.isRead ? "Read" : "Unread"));
            System.out.println("  Received: " + message.receivedDateTime
                // Values are returned in UTC, convert to local time zone
                .atZoneSameInstant(ZoneId.systemDefault()).toLocalDateTime()
                .format(DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT)));
        }

        final Boolean moreMessagesAvailable = messages.getNextPage() != null;
        System.out.println("\nMore messages available? " + moreMessagesAvailable);
    } catch (Exception e) {
        System.out.println("Error getting inbox");
        System.out.println(e.getMessage());
    }
}

Run the app, sign in, and choose option 2 to list your inbox.

Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. List users (requires app-only)
5. Make a Graph call
2
Message: Updates from Ask HR and other communities
  From: Contoso Demo on Yammer
  Status: Read
  Received: 12/30/2021, 4:54:54 AM
Message: Employee Initiative Thoughts
  From: Patti Fernandez
  Status: Read
  Received: 12/28/2021, 5:01:10 PM
Message: Voice Mail (11 seconds)
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021, 5:00:46 PM
Message: Our Spring Blog Update
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021, 4:49:46 PM
Message: Atlanta Flight Reservation
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021, 4:35:42 PM
Message: Atlanta Trip Itinerary - down time
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021, 4:22:04 PM

...

More messages available? true

Code explained

Consider the code in the getInbox function.

Accessing well-known mail folders

The function uses the _userClient.me().mailFolders("inbox").messages() request builder, which builds a request to the List messages API. Because it includes the mailFolders("inbox") request builder, the API will only return messages in the requested mail folder. In this case, because the inbox is a default, well-known folder inside a user's mailbox, it's accessible via its well-known name. Non-default folders are accessed the same way, by replacing the well-known name with the mail folder's ID property. For details on the available well-known folder names, see mailFolder resource type.

Accessing a collection

Unlike the getUser function from the previous section, which returns a single object, this method returns a collection of messages. Most APIs in Microsoft Graph that return a collection do not return all available results in a single response. Instead, they use paging to return a portion of the results while providing a method for clients to request the next "page".

Default page sizes

APIs that use paging implement a default page size. For messages, the default value is 10. Clients can request more (or less) by using the $top query parameter. In getInbox, this is accomplished with the .top(25) method.

Note

The value passed to .top() is an upper-bound, not an explicit number. The API returns a number of messages up to the specified value.

Getting subsequent pages

If there are more results available on the server, collection responses include an @odata.nextLink property with an API URL to access the next page. The .NET client library exposes this as the getNextPage method on collection page objects. If this method returns non-null, there are more results available.

Sorting collections

The function uses the orderBy method on the request to request results sorted by the time the message is received (receivedDateTime property). It includes the DESC keyword so that messages received more recently are listed first. This adds the $orderby query parameter to the API call.

Send mail

20 minutes remaining

In this section you will add the ability to send an email message as the authenticated user.

Open Graph.java and add the following function to the Graph class.

public static void sendMail(String subject, String body, String recipient) throws Exception {
    // Ensure client isn't null
    if (_userClient == null) {
        throw new Exception("Graph has not been initialized for user auth");
    }

    // Create a new message
    final Message message = new Message();
    message.subject = subject;
    message.body = new ItemBody();
    message.body.content = body;
    message.body.contentType = BodyType.TEXT;

    final Recipient toRecipient = new Recipient();
    toRecipient.emailAddress = new EmailAddress();
    toRecipient.emailAddress.address = recipient;
    message.toRecipients = List.of(toRecipient);

    // Send the message
    _userClient.me()
        .sendMail(UserSendMailParameterSet.newBuilder()
            .withMessage(message)
            .build())
        .buildRequest()
        .post();
}

Replace the empty sendMail function in App.java with the following.

private static void sendMail() {
    try {
        // Send mail to the signed-in user
        // Get the user for their email address
        final User user = Graph.getUser();
        final String email = user.mail == null ? user.userPrincipalName : user.mail;

        Graph.sendMail("Testing Microsoft Graph", "Hello world!", email);
        System.out.println("\nMail sent.");
    } catch (Exception e) {
        System.out.println("Error sending mail");
        System.out.println(e.getMessage());
    }
}

Run the app, sign in, and choose option 3 to send an email to yourself.
```
Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. List users (requires app-only)
5. Make a Graph call
3

Mail sent.
```
Note

If you are testing with a developer tenant from the Microsoft 365 Developer Program, the email you send may not be delivered, and you may receive a non-delivery report. If this happens to you, please contact support via the Microsoft 365 admin center.

Code explained

Consider the code in the sendMail function.

Sending mail

The function uses the _userClient.me().sendMail() request builder, which builds a request to the Send mail API. The request builder takes a UserSendMailParameterSet object containing the message to send.

Creating objects

Unlike the previous calls to Microsoft Graph that only read data, this call creates data. To do this with the client library you create an instance of the class representing the data (in this case, com.microsoft.graph.models.Message) using the new keyword, set the desired properties, then send it in the API call. Because the call is sending data, the post method is used instead of get.

Optional: configure app-only authentication

15 minutes remaining

In this section you will update the app registration from the previous section to support app-only authentication. App-only authentication is a good choice for background services, and there are also some APIs that only support app-only authentication. You only need to complete this section if you intend to use the app-only portions of this tutorial. If not, you can safely skip to the next step.

I don't need app-only, skip to the end

Important

The steps in this section require a work/school account with the Global administrator role.

Open the app registration from the previous section in the Azure AD admin center.
Select API permissions under Manage.
Remove the default User.Read permission under Configured permissions by selecting the ellipses (...) in its row and selecting Remove permission.
Select Add a permission, then Microsoft Graph.
Select Application permissions.
Select User.Read.All, then select Add permissions.
Select Grant admin consent for..., then select Yes to provide admin consent for the selected permission.
Select Certificates and secrets under Manage, then select New client secret.
Enter a description, choose a duration, and select Add.
Copy the secret from the Value column, you will need it in the next steps.

Important

This client secret is never shown again, so make sure you copy it now.

Create a new file named UpdateAppForAppOnlyAuth.ps1 and add the following code.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The app ID of the app registration")]
  [String]
  $AppId,

  [Parameter(Mandatory=$true,
  HelpMessage="The application permission scopes to configure on the app registration")]
  [String[]]
  $GraphScopes,

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

$graphAppId = "00000003-0000-0000-c000-000000000000"

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All AppRoleAssignment.ReadWrite.All User.Read" `
 -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop

# Get the application and service principal
$appRegistration = Get-MgApplication -Filter ("appId eq '" + $AppId +"'") -ErrorAction Stop
$appServicePrincipal = Get-MgServicePrincipal -Filter ("appId eq '" + $AppId + "'") -ErrorAction Stop

# Lookup available Graph application permissions
$graphServicePrincipal = Get-MgServicePrincipal -Filter ("appId eq '" + $graphAppId + "'") -ErrorAction Stop
$graphAppPermissions = $graphServicePrincipal.AppRoles

$resourceAccess = @()

foreach($scope in $GraphScopes)
{
  $permission = $graphAppPermissions | Where-Object { $_.Value -eq $scope }
  if ($permission)
  {
    $resourceAccess += @{ Id =  $permission.Id; Type = "Role"}
  }
  else
  {
    Write-Host -ForegroundColor Red "Invalid scope:" $scope
    Exit
  }
}

# Add the permissions to required resource access
Update-MgApplication -ApplicationId $appRegistration.Id -RequiredResourceAccess `
 @{ ResourceAppId = $graphAppId; ResourceAccess = $resourceAccess } -ErrorAction Stop
Write-Host -ForegroundColor Cyan "Added application permissions to app registration"

# Add admin consent
foreach ($appRole in $resourceAccess)
{
  New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $appServicePrincipal.Id `
   -PrincipalId $appServicePrincipal.Id -ResourceId $graphServicePrincipal.Id `
   -AppRoleId $appRole.Id -ErrorAction SilentlyContinue -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "Admin consent for one of the requested scopes could not be added."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }
}
Write-Host -ForegroundColor Cyan "Added admin consent"

# Add a client secret
$clientSecret = Add-MgApplicationPassword -ApplicationId $appRegistration.Id -PasswordCredential `
 @{ DisplayName = "Added by PowerShell" } -ErrorAction Stop

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Tenant ID: "
Write-Host -ForegroundColor Yellow $context.TenantId
Write-Host -ForegroundColor Cyan -NoNewline "Client secret: "
Write-Host -ForegroundColor Yellow $clientSecret.SecretText
Write-Host -ForegroundColor Cyan -NoNewline "Secret expires: "
Write-Host -ForegroundColor Yellow $clientSecret.EndDateTime

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Save the file.
Open PowerShell and change the current directory to the location of UpdateAppForAppOnlyAuth.ps1.

Run the following command, replacing <your-client-id> with your client ID.

.\UpdateAppForAppOnlyAuth.ps1 -AppId <your-client-id> -GraphScopes "User.Read.All"

Follow the prompt to open https://microsoft.com/devicelogin in a browser, enter the provided code, and complete the authentication process.

Copy the Tenant ID and Client secret values from the script output. You will need these values in the next step.

SUCCESS
Tenant ID: a795ad0f-7d82-4a3b-a2c0-0713ec72ade7
Client secret: 2jv7Q~8eiOd_QafJ.....
Secret expires: 2/16/2024 9:32:09 PM

Note

Notice that, unlike the steps when registering for user authentication, in this section you did configure Microsoft Graph permissions on the app registration. This is because app-only auth uses the client credentials flow, which requires that permissions be configured on the app registration. See The .default scope for details.

Optional: add app-only authentication

12 minutes remaining

In this section you will add app-only authentication to the application. This section is optional, and requires completion of Optional: configure app-only authentication. These steps can only be completed with a work or school account.

I don't need app-only, skip to the end

Configure Graph client for app-only authentication

In this section you will use the ClientSecretCredential class to request an access token by using the client credentials flow.

Update the values in oAuth.properties according to the following table.

Setting Value

app.tenantId Your organization's tenant ID

app.clientSecret The client secret generated in the previous step

Setting	Value
`app.tenantId`	Your organization's tenant ID
`app.clientSecret`	The client secret generated in the previous step

Open Graph.java and add the following code to the Graph class.

private static ClientSecretCredential _clientSecretCredential;
private static GraphServiceClient<Request> _appClient;

private static void ensureGraphForAppOnlyAuth() throws Exception {
    // Ensure _properties isn't null
    if (_properties == null) {
        throw new Exception("Properties cannot be null");
    }

    if (_clientSecretCredential == null) {
        final String clientId = _properties.getProperty("app.clientId");
        final String tenantId = _properties.getProperty("app.tenantId");
        final String clientSecret = _properties.getProperty("app.clientSecret");

        _clientSecretCredential = new ClientSecretCredentialBuilder()
            .clientId(clientId)
            .tenantId(tenantId)
            .clientSecret(clientSecret)
            .build();
    }

    if (_appClient == null) {
        final TokenCredentialAuthProvider authProvider =
            new TokenCredentialAuthProvider(
                List.of("https://graph.microsoft.com/.default"), _clientSecretCredential);

        _appClient = GraphServiceClient.builder()
            .authenticationProvider(authProvider)
            .buildClient();
    }
}

Optional: list users

10 minutes remaining

In this section you will add the ability to list all users in your Azure Active Directory using app-only authentication. This section is optional, and requires completion of Optional: configure app-only authentication and Optional: add app-only authentication. These steps can only be completed with a work or school account.

I don't need app-only, skip to the end

Open Graph.java and add the following function to the Graph class.

public static UserCollectionPage getUsers() throws Exception {
    ensureGraphForAppOnlyAuth();

    return _appClient.users()
        .buildRequest()
        .select("displayName,id,mail")
        .top(25)
        .orderBy("displayName")
        .get();
}

Replace the empty listUsers function in App.java with the following.

private static void listUsers() {
    try {
        final UserCollectionPage users = Graph.getUsers();

        // Output each user's details
        for (User user: users.getCurrentPage()) {
            System.out.println("User: " + user.displayName);
            System.out.println("  ID: " + user.id);
            System.out.println("  Email: " + user.mail);
        }

        final Boolean moreUsersAvailable = users.getNextPage() != null;
        System.out.println("\nMore users available? " + moreUsersAvailable);
    } catch (Exception e) {
        System.out.println("Error getting users");
        System.out.println(e.getMessage());
    }
}

Run the app, sign in, and choose option 4 to list users.

Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. List users (requires app-only)
5. Make a Graph call
4
User: Adele Vance
  ID: 05fb57bf-2653-4396-846d-2f210a91d9cf
  Email: AdeleV@contoso.com
User: Alex Wilber
  ID: a36fe267-a437-4d24-b39e-7344774d606c
  Email: AlexW@contoso.com
User: Allan Deyoung
  ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0
  Email: AllanD@contoso.com
User: Bianca Pisani
  ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49
  Email: NO EMAIL
User: Brian Johnson (TAILSPIN)
  ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4
  Email: BrianJ@contoso.com

...

More users available? True

Code explained

Consider the code in the getUsers function. It is very similar to the code in getInbox:

It gets a collection of users
It uses select to request specific properties
It uses top to limit the number of users returned
It uses orderBy to sort the response

The key difference is that this code uses the _appClient, not the _userClient. Both clients use the same syntax and request builders, but were configured with different credentials.

Optional: add your own code

5 minutes remaining

In this section you will add your own Microsoft Graph capabilities to the application. This could be a code snippet from Microsoft Graph documentation or Graph Explorer, or code that you created. This section is optional.

Update the app

Open Graph.java and add the following function to the Graph class.

public static void makeGraphCall() {
    // INSERT YOUR CODE HERE
    // Note: if using _appClient, be sure to call ensureGraphForAppOnlyAuth
    // before using it.
    // ensureGraphForAppOnlyAuth();
}

Replace the empty MakeGraphCallAsync function in App.java with the following.

private static void makeGraphCall() {
    try {
        Graph.makeGraphCall();
    } catch (Exception e) {
        System.out.println("Error making Graph call");
        System.out.println(e.getMessage());
    }
}

Choose an API

Find an API in Microsoft Graph you'd like to try. For example, the Create event API. You can use one of the examples in the API documentation, or you can customize an API request in Graph Explorer and use the generated snippet.

Configure permissions

Check the Permissions section of the reference documentation for your chosen API to see which authentication methods are supported. Some APIs don't support app-only, or personal Microsoft accounts, for example.

To call an API with user authentication (if the API supports user (delegated) authentication), add the required permission scope in oAuth.properties.
To call an API with app-only authentication (if the API supports it), add the required permission scope in the Azure AD admin center.

Add your code

Copy your code into the makeGraphCallAsync function in Graph.java. If you're copying a snippet from documentation or Graph Explorer, be sure to rename the GraphServiceClient to the appropriate client: _userClient or _appClient.

Sep	OCT	Nov
	13
2021	2022	2023

Build Java apps with Microsoft Graph

Prerequisites

Register the app in the portal

Register application for user authentication

Create a Java console app

Install dependencies

Load application settings

Design the app

Add user authentication

Configure Graph client for user authentication

Test the DeviceCodeCredential

Get user

Code explained

Accessing 'me'

Requesting specific properties

Strongly-typed return type

List inbox

Code explained

Accessing well-known mail folders

Accessing a collection

Default page sizes

Getting subsequent pages

Sorting collections

Send mail

Code explained

Sending mail

Creating objects

Optional: configure app-only authentication

Optional: add app-only authentication

Configure Graph client for app-only authentication

Optional: list users

Code explained

Optional: add your own code

Update the app

Choose an API

Configure permissions

Add your code

Congratulations!

Java samples