Skip to content

Commit e9cc8d8

Browse files
v-ccolinv-ccolin
authored
Merge pull request #208484 from OwenRichards1/or-working-branch
[msid][quickstarts] Create desktop and daemon portal-only quickstarts
2 parents e2c4f00 + b7bc803 commit e9cc8d8

8 files changed

+1161
-3
lines changed

‎articles/active-directory/develop/console-quickstart-portal-nodejs.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: "Quickstart: Call Microsoft Graph from a Node.js console app"
3+
description: In this quickstart, you download and run a code sample that shows how a Node.js console application can get an access token and call an API protected by a Microsoft identity platform endpoint, using the app's own identity
4+
services: active-directory
5+
author: OwenRichards1
6+
manager: CelesteDG
7+
ms.service: active-directory
8+
ms.subservice: develop
9+
ms.topic: portal
10+
ms.date: 08/22/2022
11+
ROBOTS: NOINDEX
12+
ms.author: owenrichards
13+
ms.custom: mode-api
14+
#Customer intent: As an application developer, I want to learn how my Node.js app can get an access token and call an API that is protected by a Microsoft identity platform endpoint using client credentials flow.
15+
---
16+
17+
# Quickstart: Acquire a token and call Microsoft Graph API from a Node.js console app using app's identity
18+
19+
> [!div renderon="docs"]
20+
> Welcome! This probably isn't the page you were expecting. While we work on a fix, this link should take you to the right article:
21+
>
22+
> > [Quickstart: Node.js console app that calls an API](console-app-quickstart.md?pivots=devlang-nodejs)
23+
>
24+
> We apologize for the inconvenience and appreciate your patience while we work to get this resolved.
25+
26+
> [!div renderon="portal" id="display-on-portal" class="sxs-lookup"]
27+
> # Quickstart: Acquire a token and call Microsoft Graph API from a Node.js console app using app's identity
28+
>
29+
> [!div renderon="portal" class="sxs-lookup"]
30+
> In this quickstart, you download and run a code sample that demonstrates how a Node.js console application can get an access token using the app's identity to call the Microsoft Graph API and display a [list of users](/graph/api/user-list) in the directory. The code sample demonstrates how an unattended job or Windows service can run with an application identity, instead of a user's identity.
31+
>
32+
> This quickstart uses the [Microsoft Authentication Library for Node.js (MSAL Node)](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node) with the [client credentials grant](v2-oauth2-client-creds-grant-flow.md).
33+
>
34+
> ## Prerequisites
35+
>
36+
> * [Node.js](https://nodejs.org/en/download/)
37+
> * [Visual Studio Code](https://code.visualstudio.com/download) or another code editor
38+
>
39+
>
40+
> ### Download and configure the sample app
41+
>
42+
> #### Step 1: Configure the application in Azure portal
43+
> For the code sample for this quickstart to work, you need to create a client secret, and add Graph API's **User.Read.All** application permission.
44+
>
45+
> <button id="makechanges" class="nextstepaction configure-app-button"> Make these changes for me </button>
46+
>
47+
> > [!div id="appconfigured" class="alert alert-info"]
48+
> > ![Already configured](media/quickstart-v2-netcore-daemon/green-check.png) Your application is configured with these attributes.
49+
>
50+
> #### Step 2: Download the Node.js sample project
51+
>
52+
> > [!div class="nextstepaction"]
53+
> > <button id="downloadsample" class="download-sample-button">Download the code sample</button>
54+
>
55+
> > [!div class="sxs-lookup"]
56+
> > > [!NOTE]
57+
> > > `Enter_the_Supported_Account_Info_Here`
58+
>
59+
> #### Step 3: Admin consent
60+
>
61+
> If you try to run the application at this point, you'll receive *HTTP 403 - Forbidden* error: `Insufficient privileges to complete the operation`. This error happens because any *app-only permission* requires **admin consent**: a global administrator of your directory must give consent to your application. Select one of the options below depending on your role:
62+
>
63+
> ##### Global tenant administrator
64+
>
65+
> If you are a global administrator, go to **API Permissions** page select **Grant admin consent for > Enter_the_Tenant_Name_Here**
66+
> > > [!div id="apipermissionspage"]
67+
> > > [Go to the API Permissions page]()
68+
>
69+
> ##### Standard user
70+
>
71+
> If you're a standard user of your tenant, then you need to ask a global administrator to grant **admin consent** for your application. To do this, give the following URL to your administrator:
72+
>
73+
> ```url
74+
> https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here
75+
> ```
76+
>
77+
> #### Step 4: Run the application
78+
>
79+
> Locate the sample's root folder (where `package.json` resides) in a command prompt or console. You'll need to install the dependencies of this sample once:
80+
>
81+
> ```console
82+
> npm install
83+
> ```
84+
>
85+
> Then, run the application via command prompt or console:
86+
>
87+
> ```console
88+
> node . --op getUsers
89+
> ```
90+
>
91+
> You should see on the console output some JSON fragment representing a list of users in your Azure AD directory.
92+
>
93+
> ## About the code
94+
>
95+
> Below, some of the important aspects of the sample application are discussed.
96+
>
97+
> ### MSAL Node
98+
>
99+
> [MSAL Node](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node) is the library used to sign in users and request tokens used to access an API protected by Microsoft identity platform. As described, this quickstart requests tokens by application permissions (using the application's own identity) instead of delegated permissions. The authentication flow used in this case is known as [OAuth 2.0 client credentials flow](v2-oauth2-client-creds-grant-flow.md). For more information on how to use MSAL Node with daemon apps, see [Scenario: Daemon application](scenario-daemon-overview.md).
100+
>
101+
> You can install MSAL Node by running the following npm command.
102+
>
103+
> ```console
104+
> npm install @azure/msal-node --save
105+
> ```
106+
>
107+
> ### MSAL initialization
108+
>
109+
> You can add the reference for MSAL by adding the following code:
110+
>
111+
> ```javascript
112+
> const msal = require('@azure/msal-node');
113+
> ```
114+
>
115+
> Then, initialize MSAL using the following code:
116+
>
117+
> ```javascript
118+
> const msalConfig = {
119+
> auth: {
120+
> clientId: "Enter_the_Application_Id_Here",
121+
> authority: "https://login.microsoftonline.com/Enter_the_Tenant_Id_Here",
122+
> clientSecret: "Enter_the_Client_Secret_Here",
123+
> }
124+
> };
125+
> const cca = new msal.ConfidentialClientApplication(msalConfig);
126+
> ```
127+
>
128+
> > | Where: |Description |
129+
> > |---------|---------|
130+
> > | `clientId` | Is the **Application (client) ID** for the application registered in the Azure portal. You can find this value in the app's **Overview** page in the Azure portal. |
131+
> > | `authority` | The STS endpoint for user to authenticate. Usually `https://login.microsoftonline.com/{tenant}` for public cloud, where {tenant} is the name of your tenant or your tenant Id.|
132+
> > | `clientSecret` | Is the client secret created for the application in Azure Portal. |
133+
>
134+
> For more information, please see the [reference documentation for `ConfidentialClientApplication`](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/initialize-confidential-client-application.md)
135+
>
136+
> ### Requesting tokens
137+
>
138+
> To request a token using app's identity, use `acquireTokenByClientCredential` method:
139+
>
140+
> ```javascript
141+
> const tokenRequest = {
142+
> scopes: [ 'https://graph.microsoft.com/.default' ],
143+
> };
144+
>
145+
> const tokenResponse = await cca.acquireTokenByClientCredential(tokenRequest);
146+
> ```
147+
>
148+
> > |Where:| Description |
149+
> > |---------|---------|
150+
> > | `tokenRequest` | Contains the scopes requested. For confidential clients, this should use the format similar to `{Application ID URI}/.default` to indicate that the scopes being requested are the ones statically defined in the app object set in the Azure Portal (for Microsoft Graph, `{Application ID URI}` points to `https://graph.microsoft.com`). For custom web APIs, `{Application ID URI}` is defined under **Expose an API** section in Azure Portal's Application Registration. |
151+
> > | `tokenResponse` | The response contains an access token for the scopes requested. |
152+
>
153+
> [!INCLUDE [Help and support](../../../includes/active-directory-develop-help-support-include.md)]
154+
>
155+
> ## Next steps
156+
>
157+
> To learn more about daemon/console app development with MSAL Node, see the tutorial:
158+
>
159+
> > [!div class="nextstepaction"]
160+
> > [Daemon application that calls web APIs](tutorial-v2-nodejs-console.md)

‎articles/active-directory/develop/daemon-quickstart-portal-java.md

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
title: "Quickstart: Call Microsoft Graph from a Java daemon"
3+
description: In this quickstart, you learn how a Java app can get an access token and call an API protected by Microsoft identity platform endpoint, using the app's own identity
4+
services: active-directory
5+
author: OwenRichards1
6+
manager: CelesteDG
7+
ms.service: active-directory
8+
ms.subservice: develop
9+
ms.topic: portal
10+
ms.workload: identity
11+
ms.date: 08/22/2022
12+
ROBOTS: NOINDEX
13+
ms.author: owenrichards
14+
ms.custom: aaddev, "scenarios:getting-started", "languages:Java", devx-track-java, mode-api
15+
#Customer intent: As an application developer, I want to learn how my Java app can get an access token and call an API that's protected by Microsoft identity platform endpoint using client credentials flow.
16+
---
17+
18+
# Quickstart: Acquire a token and call Microsoft Graph API from a Java console app using app's identity
19+
20+
> [!div renderon="docs"]
21+
> Welcome! This probably isn't the page you were expecting. While we work on a fix, this link should take you to the right article:
22+
>
23+
> > [Quickstart: Java daemon that calls a protected API](console-app-quickstart.md?pivots=devlang-java)
24+
>
25+
> We apologize for the inconvenience and appreciate your patience while we work to get this resolved.
26+
27+
> [!div renderon="portal" id="display-on-portal" class="sxs-lookup"]
28+
> # Quickstart: Acquire a token and call Microsoft Graph API from a Java console app using app's identity
29+
>
30+
> In this quickstart, you download and run a code sample that demonstrates how a Java application can get an access token using the app's identity to call the Microsoft Graph API and display a [list of users](/graph/api/user-list) in the directory. The code sample demonstrates how an unattended job or Windows service can run with an application identity, instead of a user's identity.
31+
>
32+
> ## Prerequisites
33+
>
34+
> To run this sample, you need:
35+
>
36+
> - [Java Development Kit (JDK)](https://openjdk.java.net/) 8 or greater
37+
> - [Maven](https://maven.apache.org/)
38+
>
39+
> > [!div class="sxs-lookup"]
40+
> ### Download and configure the quickstart app
41+
>
42+
> #### Step 1: Configure the application in Azure portal
43+
> For the code sample for this quickstart to work, you need to create a client secret, and add Graph API's **User.Read.All** application permission.
44+
>
45+
> <button id="makechanges" class="nextstepaction configure-app-button"> Make these changes for me </button>
46+
>
47+
> > [!div id="appconfigured" class="alert alert-info"]
48+
> > ![Already configured](media/quickstart-v2-netcore-daemon/green-check.png) Your application is configured with these attributes.
49+
>
50+
> #### Step 2: Download the Java project
51+
>
52+
> > [!div class="nextstepaction"]
53+
> > <button id="downloadsample" class="download-sample-button">Download the code sample</button>
54+
>
55+
> > [!div class="sxs-lookup"]
56+
> > > [!NOTE]
57+
> > > `Enter_the_Supported_Account_Info_Here`
58+
>
59+
> #### Step 3: Admin consent
60+
>
61+
> If you try to run the application at this point, you'll receive *HTTP 403 - Forbidden* error: `Insufficient privileges to complete the operation`. This error happens because any *app-only permission* requires Admin consent: a global administrator of your directory must give consent to your application. Select one of the options below depending on your role:
62+
>
63+
> ##### Global tenant administrator
64+
>
65+
> If you are a global administrator, go to **API Permissions** page select **Grant admin consent for Enter_the_Tenant_Name_Here**.
66+
> > [!div id="apipermissionspage"]
67+
> > [Go to the API Permissions page]()
68+
>
69+
> ##### Standard user
70+
>
71+
> If you're a standard user of your tenant, then you need to ask a global administrator to grant admin consent for your application. To do this, give the following URL to your administrator:
72+
>
73+
> ```url
74+
> https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here
75+
> ```
76+
> #### Step 4: Run the application
77+
>
78+
> You can test the sample directly by running the main method of ClientCredentialGrant.java from your IDE.
79+
>
80+
> From your shell or command line:
81+
>
82+
> ```
83+
> $ mvn clean compile assembly:single
84+
> ```
85+
>
86+
> This will generate a msal-client-credential-secret-1.0.0.jar file in your /targets directory. Run this using your Java executable like below:
87+
>
88+
> ```
89+
> $ java -jar msal-client-credential-secret-1.0.0.jar
90+
> ```
91+
>
92+
> After running, the application should display the list of users in the configured tenant.
93+
>
94+
> > [!IMPORTANT]
95+
> > This quickstart application uses a client secret to identify itself as confidential client. Because the client secret is added as a plain-text to your project files, for security reasons, it is recommended that you use a certificate instead of a client secret before considering the application as production application. For more information on how to use a certificate, see [these instructions](https://github.com/Azure-Samples/ms-identity-java-daemon/tree/master/msal-client-credential-certificate) in the same GitHub repository for this sample, but in the second folder **msal-client-credential-certificate**.
96+
>
97+
> ## More information
98+
>
99+
> ### MSAL Java
100+
>
101+
> [MSAL Java](https://github.com/AzureAD/microsoft-authentication-library-for-java) is the library used to sign in users and request tokens used to access an API protected by Microsoft identity platform. As described, this quickstart requests tokens by using the application own identity instead of delegated permissions. The authentication flow used in this case is known as *[client credentials oauth flow](v2-oauth2-client-creds-grant-flow.md)*. For more information on how to use MSAL Java with daemon apps, see [this article](scenario-daemon-overview.md).
102+
>
103+
> Add MSAL4J to your application by using Maven or Gradle to manage your dependencies by making the following changes to the application's pom.xml (Maven) or build.gradle (Gradle) file.
104+
>
105+
> In pom.xml:
106+
>
107+
> ```xml
108+
> <dependency>
109+
> <groupId>com.microsoft.azure</groupId>
110+
> <artifactId>msal4j</artifactId>
111+
> <version>1.0.0</version>
112+
> </dependency>
113+
> ```
114+
>
115+
> In build.gradle:
116+
>
117+
> ```$xslt
118+
> compile group: 'com.microsoft.azure', name: 'msal4j', version: '1.0.0'
119+
> ```
120+
>
121+
> ### MSAL initialization
122+
>
123+
> Add a reference to MSAL for Java by adding the following code to the top of the file where you will be using MSAL4J:
124+
>
125+
> ```Java
126+
> import com.microsoft.aad.msal4j.*;
127+
> ```
128+
>
129+
> Then, initialize MSAL using the following code:
130+
>
131+
> ```Java
132+
> IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);
133+
>
134+
> ConfidentialClientApplication cca =
135+
> ConfidentialClientApplication
136+
> .builder(CLIENT_ID, credential)
137+
> .authority(AUTHORITY)
138+
> .build();
139+
> ```
140+
>
141+
> > | Where: |Description |
142+
> > |---------|---------|
143+
> > | `CLIENT_SECRET` | Is the client secret created for the application in Azure portal. |
144+
> > | `CLIENT_ID` | Is the **Application (client) ID** for the application registered in the Azure portal. You can find this value in the app's **Overview** page in the Azure portal. |
145+
> > | `AUTHORITY` | The STS endpoint for user to authenticate. Usually `https://login.microsoftonline.com/{tenant}` for public cloud, where {tenant} is the name of your tenant or your tenant Id.|
146+
>
147+
> ### Requesting tokens
148+
>
149+
> To request a token using app's identity, use `acquireToken` method:
150+
>
151+
> ```Java
152+
> IAuthenticationResult result;
153+
> try {
154+
> SilentParameters silentParameters =
155+
> SilentParameters
156+
> .builder(SCOPE)
157+
> .build();
158+
>
159+
> // try to acquire token silently. This call will fail since the token cache does not
160+
> // have a token for the application you are requesting an access token for
161+
> result = cca.acquireTokenSilently(silentParameters).join();
162+
> } catch (Exception ex) {
163+
> if (ex.getCause() instanceof MsalException) {
164+
>
165+
> ClientCredentialParameters parameters =
166+
> ClientCredentialParameters
167+
> .builder(SCOPE)
168+
> .build();
169+
>
170+
> // Try to acquire a token. If successful, you should see
171+
> // the token information printed out to console
172+
> result = cca.acquireToken(parameters).join();
173+
> } else {
174+
> // Handle other exceptions accordingly
175+
> throw ex;
176+
> }
177+
> }
178+
> return result;
179+
> ```
180+
>
181+
> > |Where:| Description |
182+
> > |---------|---------|
183+
> > | `SCOPE` | Contains the scopes requested. For confidential clients, this should use the format similar to `{Application ID URI}/.default` to indicate that the scopes being requested are the ones statically defined in the app object set in the Azure portal (for Microsoft Graph, `{Application ID URI}` points to `https://graph.microsoft.com`). For custom web APIs, `{Application ID URI}` is defined under the **Expose an API** section in **App registrations** in the Azure portal.|
184+
>
185+
> [!INCLUDE [Help and support](../../../includes/active-directory-develop-help-support-include.md)]
186+
>
187+
> ## Next steps
188+
>
189+
> To learn more about daemon applications, see the scenario landing page.
190+
>
191+
> > [!div class="nextstepaction"]
192+
> > [Daemon application that calls web APIs](scenario-daemon-overview.md)

0 commit comments

Comments
 (0)