Skip to content

Commit add727b

Browse files
sameeragsameerag
authored
Merge pull request #1902 from AzureAD/msal-node-documentation-latest
[msal-node] documentation
2 parents c715551 + 58f0284 commit add727b

File tree

7 files changed

+492
-28
lines changed

7 files changed

+492
-28
lines changed

‎README.md

+6
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@ The Microsoft Authentication Library for JavaScript enables client-side JavaScri
88

99
The [`lib`](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib) folder contains the source code for all of our libraries. You will also find all the details about **installing the libraries**, in their respective README.md.
1010

11+
- [Microsoft Authentication Library for Node.js v1.x (Alpha)](lib/msal-node/): A [Node.js](https://nodejs.org/en/) library that enables authentication and token acquisition with the Microsoft Identity platform in JavaScript applications. Implements the following OAuth 2.0 protocols and is [OpenID-compliant](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc):
12+
- [Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) with [PKCE](https://oauth.net/2/pkce/)
13+
- [Device Code Grant](https://oauth.net/2/grant-types/device-code/)
14+
- [Refresh Token Grant](https://oauth.net/2/grant-types/refresh-token/)
15+
- [Client Credential Grant](https://oauth.net/2/grant-types/client-credentials/) (Coming soon)
16+
1117
- [Microsoft Authentication Library for JavaScript v2.x (Preview)](lib/msal-browser/): A browser-based, framework-agnostic browser library that enables authentication and token acquisition with the Microsoft Identity platform in JavaScript applications. Implements the OAuth 2.0 [Authorization Code Flow with PKCE](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow), and is [OpenID-compliant](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc).
1218

1319
- [Microsoft Authentication Library for JavaScript v1.x](lib/msal-core/): A browser-based, framework-agnostic core library that enables authentication and token acquisition with the Microsoft Identity platform in JavaScript applications. Implements the OAuth 2.0 [Implicit Grant Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-implicit-grant-flow), and is [OpenID-compliant](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc).

‎lib/msal-common/docs/Response.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
MSAL will return an `AuthenticationResult.ts` object as a response to all acquire token APIs:
2+
3+
#### `msal-browser` public APIs for token acquisition:
4+
`loginPopup`, `acquireTokenPopup`, `acquireTokenSilent` or `handleRedirectPromise`
5+
6+
#### `msal-node` public APIs for token acquisition:
7+
`acquireTokenByCode`, `acquireTokenSilent`, `acquireTokenByRefreshToken`, `acquireTokenByDeviceCode`
8+
9+
Reference docs for `AuthenticationResult` expanding on each parameter can be found [here](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-common/classes/_src_response_authenticationresult_.authenticationresult.html).

‎lib/msal-common/docs/initialization.md

-3
This file was deleted.

‎lib/msal-common/docs/request.md

+191
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Request
2+
3+
Since MSAL Node supports various authorization code grants, there is support for different public APIs per grant and the corresponding request.
4+
5+
## Authorization Code Flow
6+
7+
### Public APIs
8+
- [getAuthCodeUrl()](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/classes/_src_client_publicclientapplication_.publicclientapplication.html#getauthcodeurl): This API is the first leg of the `authorization code grant` for MSAL Node. The request is of the type [AuthorizationUrlRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-common/modules/_src_request_authorizationurlrequest_.html).
9+
The application is sent a URL that can be used to generate an `authorization code`. This `URL` can be opened in a browser of choice, where the user can input their credential, and will be redirected back to the `redirectUri` (registered during the [app registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-desktop-app-registration)) with an `authorization code`. The `authorization code` can now be redeemed for a `token` with the following step.
10+
11+
- [acquireTokenByCode()](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/classes/_src_client_publicclientapplication_.publicclientapplication.html#acquiretokenbycode): This API is the second leg of the `authorization code grant` for MSAL Node. The request constructed here should be of the type [AuthorizationCodeRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-common/modules/_src_request_authorizationcoderequest_.html). The application passed the `authorization code` received as a part of the above step and exchanges it for a `token`.
12+
13+
``` javascript
14+
15+
const authCodeUrlParameters = {
16+
scopes: ["sample_scope"],
17+
redirectUri: "your_redirect_uri",
18+
};
19+
20+
// get url to sign user in and consent to scopes needed for application
21+
pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => {
22+
console.log(response);
23+
}).catch((error) => console.log(JSON.stringify(error)));
24+
25+
const tokenRequest = {
26+
code: "authorization_code",
27+
redirectUri: "your_redirect_uri",
28+
scopes: ["sample_scope"],
29+
};
30+
31+
// acquire a token by exchanging the code
32+
pca.acquireTokenByCode(tokenRequest).then((response) => {
33+
console.log("\nResponse: \n:", response);
34+
}).catch((error) => {
35+
console.log(error);
36+
});
37+
```
38+
39+
## Device Code Flow
40+
41+
### Public APIs
42+
- [acquireTokenByDeviceCode()](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/classes/_src_client_publicclientapplication_.publicclientapplication.html#acquiretokenbydevicecode): This API lets the application acquire a token with Device Code grant. The request is of the type [DeviceCodeRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-common/modules/_src_request_devicecoderequest_.html). This API acquires a `token` from the authority using OAuth2.0 device code flow. This flow is designed for devices that do not have access to a browser or have input constraints. The authorization server issues a DeviceCode object with a verification code, an end-user code, and the end-user verification URI. The DeviceCode object is provided through a callback, and the end-user should be instructed to use another device to navigate to the verification URI to input credentials. Since the client cannot receive incoming requests, it polls the authorization server repeatedly until the end-user completes input of credentials.
43+
44+
``` javascript
45+
const msalConfig = {
46+
auth: {
47+
clientId: "your_client_id_here",
48+
authority: "your_authority_here",
49+
}
50+
};
51+
52+
const pca = new msal.PublicClientApplication(msalConfig);
53+
54+
const deviceCodeRequest = {
55+
deviceCodeCallback: (response) => (console.log(response.message)),
56+
scopes: ["user.read"],
57+
};
58+
59+
pca.acquireTokenByDeviceCode(deviceCodeRequest).then((response) => {
60+
console.log(JSON.stringify(response));
61+
}).catch((error) => {
62+
console.log(JSON.stringify(error));
63+
});
64+
65+
```
66+
67+
## Refresh Token Flow
68+
69+
### Public APIs
70+
- [acquireTokenByRefreshToken](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/classes/_src_client_publicclientapplication_.publicclientapplication.html#acquiretokenbyrefreshtoken): This API acquires a token by exchanging the refresh token provided for a new set of tokens. The request is of the type [RefreshTokenRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-common/modules/_src_request_refreshtokenrequest_.html). The `refresh token` is never returned to the user in a response, but can be accessed from the user cache. It is recommended that you use acquireTokenSilent() for silent scenarios. When using acquireTokenSilent(), MSAL will handle the caching and refreshing of tokens automatically.
71+
72+
``` javascript
73+
const config = {
74+
auth: {
75+
clientId: "your_client_id_here",
76+
authority: "your_authority_here",
77+
}
78+
};
79+
80+
const pca = new msal.PublicClientApplication(config);
81+
82+
const refreshTokenRequest = {
83+
refreshToken: "",
84+
scopes: ["user.read"],
85+
};
86+
87+
pca.acquireTokenByRefreshToken(refreshTokenRequest).then((response) => {
88+
console.log(JSON.stringify(response));
89+
}).catch((error) => {
90+
console.log(JSON.stringify(error));
91+
});
92+
```
93+
94+
## Silent Flow
95+
96+
### Public APIs
97+
- [acquireTokenSilent](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/classes/_src_client_publicclientapplication_.publicclientapplication.html#acquiretokensilent): This API acquires a token silently, in case cache is provided by the user, or when cache is created by preceding this call with any other interactive flow (eg: authorization code flow). The request is of the type [SilentFlowRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-common/modules/_src_request_silentflowrequest_.html). The `token` is acquired silently when a user specifies the account the token is requested for.
98+
99+
``` javascript
100+
/**
101+
* Cache Plugin configuration
102+
*/
103+
const cachePath = "./data/example.cache.json"; // Replace this string with the path to your valid cache file.
104+
105+
const readFromStorage = () => {
106+
return fs.readFile(cachePath, "utf-8");
107+
};
108+
109+
const writeToStorage = (getMergedState) => {
110+
return readFromStorage().then(oldFile =>{
111+
const mergedState = getMergedState(oldFile);
112+
return fs.writeFile(cachePath, mergedState);
113+
})
114+
};
115+
116+
const cachePlugin = {
117+
readFromStorage,
118+
writeToStorage
119+
};
120+
121+
/**
122+
* Public Client Application Configuration
123+
*/
124+
const publicClientConfig = {
125+
auth: {
126+
clientId: "your_client_id_here",
127+
authority: "your_authority_here",
128+
redirectUri: "your_redirectUri_here",
129+
},
130+
cache: {
131+
cachePlugin
132+
},
133+
};
134+
135+
/** Request Configuration */
136+
137+
const scopes = ["your_scopes"];
138+
139+
const authCodeUrlParameters = {
140+
scopes: scopes,
141+
redirectUri: "your_redirectUri_here",
142+
};
143+
144+
const pca = new msal.PublicClientApplication(publicClientConfig);
145+
const msalCacheManager = pca.getCacheManager();
146+
let accounts;
147+
148+
pca.getAuthCodeUrl(authCodeUrlParameters)
149+
.then((response) => {
150+
console.log(response);
151+
}).catch((error) => console.log(JSON.stringify(error)));
152+
153+
const tokenRequest = {
154+
code: req.query.code,
155+
redirectUri: "http://localhost:3000/redirect",
156+
scopes: scopes,
157+
};
158+
159+
pca.acquireTokenByCode(tokenRequest).then((response) => {
160+
console.log("\nResponse: \n:", response);
161+
return msalCacheManager.writeToPersistence();
162+
}).catch((error) => {
163+
console.log(error);
164+
});
165+
166+
// get Accounts
167+
accounts = msalCacheManager.getAllAccounts();
168+
console.log("Accounts: ", accounts);
169+
170+
// Build silent request
171+
const silentRequest = {
172+
account: accounts[1], // Index must match the account that is trying to acquire token silently
173+
scopes: scopes,
174+
};
175+
176+
// Acquire Token Silently to be used in MS Graph call
177+
pca.acquireTokenSilent(silentRequest).then((response) => {
178+
console.log("\nSuccessful silent token acquisition:\nResponse: \n:", response);
179+
return msalCacheManager.writeToPersistence();
180+
}).catch((error) => {
181+
console.log(error);
182+
});
183+
```
184+
## Next Steps
185+
Proceed to understand the public APIs provided by `msal-node` for acquiring tokens [here](./response.md)
186+
187+
188+
189+
190+
191+

0 commit comments

Comments
 (0)