From b3c8646cc5848ba5ec7600c3adf295861ab9a4be Mon Sep 17 00:00:00 2001 From: sameerag Date: Mon, 6 Jul 2020 18:15:57 -0700 Subject: [PATCH 1/7] Update docs --- lib/msal-common/docs/Response.md | 9 + lib/msal-node/README.md | 166 +++++++++++++++--- lib/msal-node/docs/configuration.md | 90 ++++++++++ .../initialize-public-client-application.md | 65 +++++++ lib/msal-node/docs/request.md | 39 ++++ 5 files changed, 345 insertions(+), 24 deletions(-) create mode 100644 lib/msal-common/docs/Response.md create mode 100644 lib/msal-node/docs/configuration.md create mode 100644 lib/msal-node/docs/initialize-public-client-application.md create mode 100644 lib/msal-node/docs/request.md diff --git a/lib/msal-common/docs/Response.md b/lib/msal-common/docs/Response.md new file mode 100644 index 0000000000..95386d4898 --- /dev/null +++ b/lib/msal-common/docs/Response.md @@ -0,0 +1,9 @@ +MSAL will return an `AuthenticationResult.ts` object as a response to all public request APIs: + +#### `msal-browser` public APIs for token acquisition: +`loginPopup`, `acquireTokenPopup`, `acquireTokenSilent` or `handleRedirectPromise` + +#### `msal-node` public APIs for token acquisition: +`acquireTokenByCode`, `acquireTokenSilent`, `acquireTokenByRefreshToken`, `acquireTokenByDeviceCode` + +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). diff --git a/lib/msal-node/README.md b/lib/msal-node/README.md index 28c5293f63..f721e02f8a 100644 --- a/lib/msal-node/README.md +++ b/lib/msal-node/README.md @@ -1,50 +1,168 @@ -# Microsoft Authentication Library for JavaScript for Node(msal-node) for Node.js based Web apps +# (Alpha) Microsoft Authentication Library for JavaScript for Node(msal-node) for Node.js based Web apps + +| Getting Started | AAD Docs | Library Reference | +| --- | --- | --- | --- | Currently `msal-node` library is under development, Please track the project progress [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/projects/4). -### Build Library -```javascript -// Change to the msal-node package directory -cd lib/msal-node/ +1. [About](#about) +2. [FAQ](#faq) +3. [Releases](#releases) +4. [Prerequisites](#prerequisites) +5. [Installation](#installation) +6. [Usage](#usage) +7. [Samples](#samples) +8. [Build Library](#build-and-test) +9. [Security Reporting](#security-reporting) +10. [License](#license) +11. [Code of Conduct](#we-value-and-adhere-to-the-microsoft-open-source-code-of-conduct) -// Ensure you are using the local build of msal-common -npm link @azure/msal-common +## About -// To run build only for node package -npm run build +The MSAL library for Node.js enables desktop and web applications for Node.js to authenticate users using [Azure AD](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-overview) work and school accounts (AAD), Microsoft personal accounts (MSA) and social identity providers like Facebook, Google, LinkedIn, Microsoft accounts, etc. through [Azure AD B2C](https://docs.microsoft.com/en-us/azure/active-directory-b2c/active-directory-b2c-overview#identity-providers) service. It also enables your app to get tokens to access [Microsoft Cloud](https://www.microsoft.com/enterprise) services such as [Microsoft Graph](https://graph.microsoft.io). + +The `@azure/msal-node` package has a dependency on `@azure/msal-common` package, which is the common engine for all future javascript based libraries. + +### OAuth grant types supported and upcoming: + +The current alpha version supports the below OAuth grant types: + +- [Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) with [PKCE](https://oauth.net/2/pkce/) +- [Device Code Grant](https://oauth.net/2/grant-types/device-code/) +- [Refresh Token Grant](https://oauth.net/2/grant-types/refresh-token/) +- Silent Flow (user convenience flow to acquire a token silently) + +In the upcoming quarters we plan to add support for: + +- Client Credentials flow +- Confidential client flow (authorization code flow with client secret) + +More details on different grant types supported by Microsoft authentication libraries in general can be found [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows) + +### App models supported: + +The app models supported with this library are: +- Destop app that calls web APIs +- Web app that calls web APIs (upcoming) +- Web APIs that call web APIs (upcoming) +- Daemon apps (upcoming) + +More details on APP models and the authentication flows that map to each of them can be found [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-flows-app-scenarios) + +## FAQ + +See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/FAQ.md). + +## Releases + +*Expect us to detail our major and minor releases moving forward, while leaving out our patch releases. Patch release notes can be found in our change log.* + +| Date | Release | Announcement | Main features | +| ------| ------- | ---------| --------- | +| July 6th, 2020 (Tentative) | @azure/msal-node v0.0.1-alpha | No release notes yet | Full version of the `@azure/msal-node` package; relies on `@azure/msal-common` v1.0.0 | + +## Prerequisites + +Before using `@azure/msal-node` you will need to register your app in the azure portal to get a valid `clientId` for configuration, and to register the routes that your app will accept redirect traffic on if applicable. Currently we support the below app registrations for `@azure/msal-node`: + +- [Desktop app that calls web APIs: App registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-desktop-app-registration) +- [Protected web API: App registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-protected-web-api-app-registration) + +## Installation + +### Via NPM: +```javascript +npm install @azure/msal-node ``` -TBD: Add lerna bootstrap to build common/node in one step -## Local Development +## Usage + +### MSAL basics +- Initialize a Public Client Application +- Acquire a token (Signin your desktop app) +- Acquire an access token to access a resource (Microsoft Graph, External resource) +- Refresh a token when expired +- Managing Token Lifetimes (should this go to msal-common?) +- Remove an account + +### Advanced Topics +- Configuration options +- Request types + - [AuthorizationCodeRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-common/modules/_src_request_authorizationcoderequest_.html) + +- [Response](lib/msal-common/docs/Response.md) +- Cache [Coming soon] + - Cache internals + - Serialization to disk + - Extension library +- Scopes +- CorrelationId + +## Samples +There are multiple [samples](samples/msal-node-samples) included in the repository that use MSAL Node to acquire tokens. These samples are currently used for manual testing, and are not meant to be a reference of best practices, therefore use judgement and do not blindly copy this code to any production applications. + +- [msal-node-auth-code](samples/msal-node-samples/msal-node-auth-code): Express app using OAuth2.0 authorization code flow. +- [msal-node-device-code](samples/msal-node-samples/msal-node-device-code): Command line app using OAuth 2.0 device code flow. +- [msal-node-refresh-token](samples/msal-node-samples/msal-node-refresh-token): Command line app using OAuth 2.0 refresh flow. +- [msal-node-silent-flow](samples/msal-node-samples/msal-node-silent-flow): Express app using OAuth2.0 authorization code flow and refresh token flow to demonstrate silent retrieval of tokens when already logged in or when the app provides a in-disk cache for Single sign on experience +- msal-node-extensions (Coming soon): Uses the msal-extensions library to write the MSAL in-memory token cache to a disk. + +## Build and Test + +- If you don't have [lerna](https://github.com/lerna/lerna) installed, run `npm install -g lerna` +- Run `lerna bootstrap` from anywhere within `microsoft-authentication-library-for-js.git`. +- Navigate to `microsoft-authentication-library-for-js/lib/msal-common` and run `npm run build` +- Navigate to `microsoft-authentication-library-for-js/lib/msal-node` and run `npm run build` -Below is a list of commands you will probably find useful. +```javascript +// Change to the msal-node package directory +cd lib/msal-common/ -### `npm start` +// To run build only for node package +npm run build + +// Change to the msal-node package directory +cd lib/msal-node/ -Runs the project in development/watch mode. Your project will be rebuilt upon changes. TSDX has a special logger for you convenience. Error messages are pretty printed and formatted for compatibility VS Code's Problems tab. +// To run build only for node package +npm run build - +// to link msal-node and msal-common packages +lerna bootstrap +``` -Your library will be rebuilt if you make edits. +### Local Development +Below is a list of commands you will probably find useful: -### `npm run build` +#### `npm run build:modules:watch` +Runs the project in development/watch mode. Your project will be rebuilt upon changes. TSDX has a special logger for you convenience. Error messages are pretty printed and formatted for compatibility VS Code's Problems tab. The library will be rebuilt if you make edits. +#### `npm run build` Bundles the package to the `dist` folder. The package is optimized and bundled with Rollup into multiple formats (CommonJS, UMD, and ES Module). - - -### `npm run lint` +#### `lerna bootstrap` +If you are running the project in development/watch mode, or have made changes in `msal-common` and need them reflecting across the project, please run `lerna bootstrap` to link all the symbols. Please note that `npm install` will unlink all the code, hence it is advised to run `lerna bootstrap` post installation. +#### `npm run lint` Runs eslint with Prettier -### `npm test`, `npm run test:coverage`, `npm run test:watch` - +#### `npm test`, `npm run test:coverage`, `npm run test:watch` Runs the test watcher (Jest) in an interactive mode. By default, runs tests related to files changed since the last commit. Generate code coverage by adding the flag --coverage. No additional setup needed. Jest can collect code coverage information from entire projects, including untested files. -## TSDX Bootstrap +## Security Reporting + +If you find a security issue with our libraries or services please report it to [secure@microsoft.com](mailto:secure@microsoft.com) with as much detail as possible. Your submission may be eligible for a bounty through the [Microsoft Bounty](http://aka.ms/bugbounty) program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting [this page](https://technet.microsoft.com/security/dd252948) and subscribing to Security Advisory Alerts. + +## License + +Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License (the "License"); + +## We Value and Adhere to the Microsoft Open Source Code of Conduct + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + -This project was bootstrapped with [TSDX](https://github.com/jaredpalmer/tsdx). diff --git a/lib/msal-node/docs/configuration.md b/lib/msal-node/docs/configuration.md new file mode 100644 index 0000000000..12199ad704 --- /dev/null +++ b/lib/msal-node/docs/configuration.md @@ -0,0 +1,90 @@ +# Configuration Options + +Before you start here, make sure you understand how to [initialize an app object](./Initialize-PublicClientApplication.md). + +The MSAL library has a set of configuration options that can be used to customize the behavior of your authentication flows. These options can be set either in the constructor of the `PublicClientApplication` object or as part of the [request APIs](./Request.md). Here we describe the configuration object that can be passed into the `PublicClientApplication` constructor. + +In this document: +- [Usage](#usage) +- [Options](#options) + +## Usage + +The configuration object can be passed into the `PublicClientApplication` constructor. The only required config parameter is the `client_id` of the application. Everything else is optional, but may be required depending on your authentication flow, tenant and application model. + +[Configuration](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/modules/_src_config_configuration_.html#configuration) object with all supported parameters is as below: + +```javascript + +// Call back API tp read from the cache in .json format +const readFromStorage = () => { + return fs.readFile("cache_file_path", "utf-8"); +}; + +// Call back API to write to the cache in .json format +const writeToStorage = (getMergedState) => { + return readFromStorage().then(oldFile =>{ + const mergedState = getMergedState(oldFile); + return fs.writeFile("cache_file_path", mergedState); + }) +}; + +// Cache Plugin +const cachePlugin = { + readFromStorage, + writeToStorage +}; + +const msalConfig = { + auth: { + clientId: "enter_client_id_here", + authority: "https://login.microsoftonline.com/common", + knownAuthorities: [], + cloudDiscoveryMetadata: "", + redirectUri: "enter_redirect_uri_here", + }, + cache: { + cachePlugin // your implementation of cache plugin + }, + system: { + loggerOptions: { + loggerCallback(loglevel, message, containsPii) { + console.log(message); + }, + piiLoggingEnabled: false, + logLevel: msal.LogLevel.Verbose, + } + } +} + +const msalInstance = new PublicClientApplication(msalConfig); +``` + +## Options + +### Auth Config Options +| Option | Description | Format | Default Value | +| ------ | ----------- | ------ | ------------- | +| `clientId` | App ID of your application. Can be found in your [portal registration](../README#prerequisites). | UUID/GUID | None. This parameter is required in order for MSAL to perform any actions. | +| `authority` | URI of the tenant to authenticate and authorize with. Usually takes the form of `https://{uri}/{tenantid}`. | String in URI format with tenant - `https://{uri}/{tenantid}` | `https://login.microsoftonline.com/common` | +| `knownAuthorities` | An array of URIs that are known to be valid. Used in B2C scenarios. | Array of strings in URI format | Empty array `[]` | +| `cloudDiscoveryMetadata` | A string containing the cloud discovery response. Used in AAD scenarios. See performance.md for more info | string | Empty string `""` | +| `redirectUri` | URI where the authorization code response is sent back to. Whatever location is specified here must have the MSAL library available to handle the response. | String in URI format | Login request page (`window.location.href` of page which made auth request) | +`redirectUri` is the same as the original request location, this flag should be set to false. | boolean | `true` | + +### Cache Config Options +| Option | Description | Format | Default Value | +| ------ | ----------- | ------ | ------------- | +| `cachePlugin` | Cache plugin with call backs to reading and writing into the cache file| [ICachePlugin](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/interfaces/_src_cache_icacheplugin_.icacheplugin.html) | null + +### System Config Options +| Option | Description | Format | Default Value | +| ------ | ----------- | ------ | ------------- | +| `loggerOptions` | Config object for logger. | See [below](#logger-config-options). | See [below](#logger-config-options). | +| `NetworkClient` | Custom HTTP implementation | INetworkModule | Coming Soon | + +### Logger Config Options +| Option | Description | Format | Default Value | +| ------ | ----------- | ------ | ------------- | +| `loggerCallback` | Callback function which handles the logging of MSAL statements. | Function - `loggerCallback: (level: LogLevel, message: string, containsPii: boolean): void` | See [above](#using-the-config-object). | +| `piiLoggingEnabled` | If true, personally identifiable information (PII) is included in logs. | boolean | `false` | diff --git a/lib/msal-node/docs/initialize-public-client-application.md b/lib/msal-node/docs/initialize-public-client-application.md new file mode 100644 index 0000000000..d12d4f151c --- /dev/null +++ b/lib/msal-node/docs/initialize-public-client-application.md @@ -0,0 +1,65 @@ +# Initialization of MSAL + +Before you get started, please ensure you have completed all the [prerequisites](../README.md#prerequisites). + +In this document: +- [Initializing the PublicClientApplication object](#initializing-the-publicclientapplication-object) +- [Configuration](#configuration_basics) +- [(Optional) Configure Authority](#optional-configure-authority) +- [(Optional) Advanced Configuration](#advanced-configuration) + +## Initializing the PublicClientApplication object + +In order to use MSAL.js, you need to instantiate a [PublicClientApplication](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/classes/_src_client_publicclientapplication_.publicclientapplication.html) object. + +```javascript +import * as msal from "@azure/msal-node"; + +const publicClientConfig = { + auth: { + clientId: "your_client_id", + authority: "your_authority", + // mandatory only for authorization code flow + redirectUri: "your_redirect_uri", + }, + cache: { + cachePlugin + }, +}; +const pca = new msal.PublicClientApplication(publicClientConfig); +``` + +## Configuration Basics + +[Configuration](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/modules/_src_config_configuration_.html#configuration) options for node have `common` parameters and `specific` paremeters per authentication flow. + +- `client_id` is mandatory to initializae a public client application +- `authority` defaults to `https://login.microsoftonline.com/common/` if the user does not set it during configuration + +## Configure Authority + +By default, MSAL is configured with the `common` tenant, which is used for multi-tenant applications and applications allowing personal accounts (not B2C). +```javascript +const msalConfig = { + auth: { + clientId: 'your_client_id', + authority: 'https://login.microsoftonline.com/common/' + } +}; +``` + +If your application audience is a single tenant, you must provide an authority with your tenant id like below: +```javascript +const msalConfig = { + auth: { + clientId: 'your_client_id', + authority: 'https://login.microsoftonline.com/{your_tenant_id}' + } +}; +``` + +## Advanced Configuration +[Configuration](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/modules/_src_config_configuration_.html#configuration) has more options which are documented [here](./configuration.md). + +## Next Steps +Proceed to understand the public APIs provided by `msal-node` for acquiring tokens [here](./request.md) diff --git a/lib/msal-node/docs/request.md b/lib/msal-node/docs/request.md new file mode 100644 index 0000000000..530f0527e6 --- /dev/null +++ b/lib/msal-node/docs/request.md @@ -0,0 +1,39 @@ +# Request + +Since MSAL Node supports various authorization code grants, there is support for different public APIs per grant and the corresponding request. + +## Authorization Code Flow + +### Public APIs +- [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). +The application is sent a URL that can be used to generate an `authorization code` by any browser of choice, and then proceed to call the below API for the `token acquisition` . + +- [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`. + +``` javascript + + const authCodeUrlParameters = { + scopes: ["user.read"], + redirectUri: ["http://localhost:3000/redirect"], + }; + + // get url to sign user in and consent to scopes needed for application + pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => { + console.log(response); + }).catch((error) => console.log(JSON.stringify(error))); + + const tokenRequest = { + code: req.query.code, + redirectUri: "http://localhost:3000/redirect", + scopes: ["user.read"], + }; + + // acquire a token by exchanging the code + pca.acquireTokenByCode(tokenRequest).then((response) => { + console.log("\nResponse: \n:", response); + }).catch((error) => { + console.log(error); + }); +``` + +### From e2128beaf81aed21e03149b72b4983ab1604b44d Mon Sep 17 00:00:00 2001 From: sameerag Date: Mon, 6 Jul 2020 18:27:45 -0700 Subject: [PATCH 2/7] more Read me changes --- lib/msal-node/README.md | 24 +++++------------------- lib/msal-node/docs/request.md | 1 - 2 files changed, 5 insertions(+), 20 deletions(-) diff --git a/lib/msal-node/README.md b/lib/msal-node/README.md index f721e02f8a..d246e876c2 100644 --- a/lib/msal-node/README.md +++ b/lib/msal-node/README.md @@ -59,7 +59,8 @@ See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/bl | Date | Release | Announcement | Main features | | ------| ------- | ---------| --------- | -| July 6th, 2020 (Tentative) | @azure/msal-node v0.0.1-alpha | No release notes yet | Full version of the `@azure/msal-node` package; relies on `@azure/msal-common` v1.0.0 | +| July 13th, 2020 (Tentative) | @azure/msal-node v1.0.0-alpha.1 | No release notes yet | Full version of the `@azure/msal-node` package; relies on `@azure/msal-common` v1.0.0 | +| July 6th, 2020 | @azure/msal-node v1.0.0-alpha.0| No release notes yet | Full version of the `@azure/msal-node` package; relies on `@azure/msal-common` v1.0.0-beta.4 | ## Prerequisites @@ -78,25 +79,10 @@ npm install @azure/msal-node ## Usage ### MSAL basics -- Initialize a Public Client Application -- Acquire a token (Signin your desktop app) -- Acquire an access token to access a resource (Microsoft Graph, External resource) -- Refresh a token when expired -- Managing Token Lifetimes (should this go to msal-common?) -- Remove an account - -### Advanced Topics -- Configuration options -- Request types - - [AuthorizationCodeRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-common/modules/_src_request_authorizationcoderequest_.html) - +- Initialize a Public Client Application(./docs/initialize-public-client-application.md) +- [Configuration](./docs/configuration.md) +- [Request](./docs/request.md) - [Response](lib/msal-common/docs/Response.md) -- Cache [Coming soon] - - Cache internals - - Serialization to disk - - Extension library -- Scopes -- CorrelationId ## Samples There are multiple [samples](samples/msal-node-samples) included in the repository that use MSAL Node to acquire tokens. These samples are currently used for manual testing, and are not meant to be a reference of best practices, therefore use judgement and do not blindly copy this code to any production applications. diff --git a/lib/msal-node/docs/request.md b/lib/msal-node/docs/request.md index 530f0527e6..d43c442b9b 100644 --- a/lib/msal-node/docs/request.md +++ b/lib/msal-node/docs/request.md @@ -36,4 +36,3 @@ The application is sent a URL that can be used to generate an `authorization cod }); ``` -### From 96d3d2aedb483ec2d634305a73a3959c7b76b24a Mon Sep 17 00:00:00 2001 From: sameerag Date: Mon, 6 Jul 2020 18:59:02 -0700 Subject: [PATCH 3/7] More docs: Request and Response for msal-node and msal-common --- lib/msal-common/docs/initialization.md | 3 - lib/msal-common/docs/request.md | 191 +++++++++++++++++++++++++ lib/msal-node/docs/configuration.md | 3 + lib/msal-node/docs/request.md | 38 ----- 4 files changed, 194 insertions(+), 41 deletions(-) delete mode 100644 lib/msal-common/docs/initialization.md create mode 100644 lib/msal-common/docs/request.md delete mode 100644 lib/msal-node/docs/request.md diff --git a/lib/msal-common/docs/initialization.md b/lib/msal-common/docs/initialization.md deleted file mode 100644 index e57855329d..0000000000 --- a/lib/msal-common/docs/initialization.md +++ /dev/null @@ -1,3 +0,0 @@ -# Initializing the MSAL Common library - - diff --git a/lib/msal-common/docs/request.md b/lib/msal-common/docs/request.md new file mode 100644 index 0000000000..8cb68010df --- /dev/null +++ b/lib/msal-common/docs/request.md @@ -0,0 +1,191 @@ +# Request + +Since MSAL Node supports various authorization code grants, there is support for different public APIs per grant and the corresponding request. + +## Authorization Code Flow + +### Public APIs +- [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). +The application is sent a URL that can be used to generate an `authorization code` by any browser of choice, and then proceed to call the below API for the `token acquisition` . + +- [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`. + +``` javascript + + const authCodeUrlParameters = { + scopes: ["user.read"], + redirectUri: ["http://localhost:3000/redirect"], + }; + + // get url to sign user in and consent to scopes needed for application + pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => { + console.log(response); + }).catch((error) => console.log(JSON.stringify(error))); + + const tokenRequest = { + code: req.query.code, + redirectUri: "http://localhost:3000/redirect", + scopes: ["user.read"], + }; + + // acquire a token by exchanging the code + pca.acquireTokenByCode(tokenRequest).then((response) => { + console.log("\nResponse: \n:", response); + }).catch((error) => { + console.log(error); + }); +``` + +## Device Code Flow + +### Public APIs +- [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. + +``` javascript +const msalConfig = { + auth: { + clientId: "your_client_id_here", + authority: "your_authority_here", + } +}; + +const pca = new msal.PublicClientApplication(msalConfig); + +const deviceCodeRequest = { + deviceCodeCallback: (response) => (console.log(response.message)), + scopes: ["user.read"], +}; + +pca.acquireTokenByDeviceCode(deviceCodeRequest).then((response) => { + console.log(JSON.stringify(response)); +}).catch((error) => { + console.log(JSON.stringify(error)); +}); + +``` + +## Refresh Token Flow + +### Public APIs +- [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. + +``` javascript +const config = { + auth: { + clientId: "your_client_id_here", + authority: "your_authority_here", + } +}; + +const pca = new msal.PublicClientApplication(config); + +const refreshTokenRequest = { + refreshToken: "", + scopes: ["user.read"], +}; + +pca.acquireTokenByRefreshToken(refreshTokenRequest).then((response) => { + console.log(JSON.stringify(response)); +}).catch((error) => { + console.log(JSON.stringify(error)); +}); +``` + +## Silent Flow + +### Public APIs +- [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. + +``` javascript +/** + * Cache Plugin configuration + */ +const cachePath = "./data/example.cache.json"; // Replace this string with the path to your valid cache file. + +const readFromStorage = () => { + return fs.readFile(cachePath, "utf-8"); +}; + +const writeToStorage = (getMergedState) => { + return readFromStorage().then(oldFile =>{ + const mergedState = getMergedState(oldFile); + return fs.writeFile(cachePath, mergedState); + }) +}; + +const cachePlugin = { + readFromStorage, + writeToStorage +}; + +/** + * Public Client Application Configuration + */ +const publicClientConfig = { + auth: { + clientId: "your_client_id_here", + authority: "your_authority_here", + redirectUri: "your_redirectUri_here", + }, + cache: { + cachePlugin + }, +}; + +/** Request Configuration */ + +const scopes = ["your_scopes"]; + +const authCodeUrlParameters = { + scopes: scopes, + redirectUri: "your_redirectUri_here", +}; + +const pca = new msal.PublicClientApplication(publicClientConfig); +const msalCacheManager = pca.getCacheManager(); +let accounts; + +pca.getAuthCodeUrl(authCodeUrlParameters) + .then((response) => { + console.log(response); + }).catch((error) => console.log(JSON.stringify(error))); + +const tokenRequest = { + code: req.query.code, + redirectUri: "http://localhost:3000/redirect", + scopes: scopes, +}; + +pca.acquireTokenByCode(tokenRequest).then((response) => { + console.log("\nResponse: \n:", response); + return msalCacheManager.writeToPersistence(); +}).catch((error) => { + console.log(error); +}); + +// get Accounts +accounts = msalCacheManager.getAllAccounts(); +console.log("Accounts: ", accounts); + +// Build silent request +const silentRequest = { + account: accounts[1], // Index must match the account that is trying to acquire token silently + scopes: scopes, +}; + +// Acquire Token Silently to be used in MS Graph call +pca.acquireTokenSilent(silentRequest).then((response) => { + console.log("\nSuccessful silent token acquisition:\nResponse: \n:", response); + return msalCacheManager.writeToPersistence(); +}).catch((error) => { + console.log(error); +}); +``` +## Next Steps +Proceed to understand the public APIs provided by `msal-node` for acquiring tokens [here](./response.md) + + + + + + diff --git a/lib/msal-node/docs/configuration.md b/lib/msal-node/docs/configuration.md index 12199ad704..e603326a46 100644 --- a/lib/msal-node/docs/configuration.md +++ b/lib/msal-node/docs/configuration.md @@ -88,3 +88,6 @@ const msalInstance = new PublicClientApplication(msalConfig); | ------ | ----------- | ------ | ------------- | | `loggerCallback` | Callback function which handles the logging of MSAL statements. | Function - `loggerCallback: (level: LogLevel, message: string, containsPii: boolean): void` | See [above](#using-the-config-object). | | `piiLoggingEnabled` | If true, personally identifiable information (PII) is included in logs. | boolean | `false` | + +## Next Steps +Proceed to understand the public APIs provided by `msal-node` for acquiring tokens [here](./request.md) diff --git a/lib/msal-node/docs/request.md b/lib/msal-node/docs/request.md deleted file mode 100644 index d43c442b9b..0000000000 --- a/lib/msal-node/docs/request.md +++ /dev/null @@ -1,38 +0,0 @@ -# Request - -Since MSAL Node supports various authorization code grants, there is support for different public APIs per grant and the corresponding request. - -## Authorization Code Flow - -### Public APIs -- [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). -The application is sent a URL that can be used to generate an `authorization code` by any browser of choice, and then proceed to call the below API for the `token acquisition` . - -- [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`. - -``` javascript - - const authCodeUrlParameters = { - scopes: ["user.read"], - redirectUri: ["http://localhost:3000/redirect"], - }; - - // get url to sign user in and consent to scopes needed for application - pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => { - console.log(response); - }).catch((error) => console.log(JSON.stringify(error))); - - const tokenRequest = { - code: req.query.code, - redirectUri: "http://localhost:3000/redirect", - scopes: ["user.read"], - }; - - // acquire a token by exchanging the code - pca.acquireTokenByCode(tokenRequest).then((response) => { - console.log("\nResponse: \n:", response); - }).catch((error) => { - console.log(error); - }); -``` - From 15496610f97f9ad3c053db84648af88b7b3d4a78 Mon Sep 17 00:00:00 2001 From: sameerag Date: Mon, 6 Jul 2020 19:09:44 -0700 Subject: [PATCH 4/7] Changing Readme paths and sample paths --- README.md | 6 +++++ lib/msal-node/README.md | 22 +++++++++---------- lib/msal-node/docs/configuration.md | 2 +- .../initialize-public-client-application.md | 2 +- 4 files changed, 19 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 9e5d5ad7ba..d6116bff2f 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,12 @@ The Microsoft Authentication Library for JavaScript enables client-side JavaScri 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. +- [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): + - [Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) with [PKCE](https://oauth.net/2/pkce/) + - [Device Code Grant](https://oauth.net/2/grant-types/device-code/) + - [Refresh Token Grant](https://oauth.net/2/grant-types/refresh-token/) + - [Client Credential Grant](https://oauth.net/2/grant-types/client-credentials/) (Coming soon) + - [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). - [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). diff --git a/lib/msal-node/README.md b/lib/msal-node/README.md index d246e876c2..d996e49be0 100644 --- a/lib/msal-node/README.md +++ b/lib/msal-node/README.md @@ -34,7 +34,7 @@ The current alpha version supports the below OAuth grant types: In the upcoming quarters we plan to add support for: -- Client Credentials flow +- [Client Credential Grant](https://oauth.net/2/grant-types/client-credentials/) (`Coming soon`) - Confidential client flow (authorization code flow with client secret) More details on different grant types supported by Microsoft authentication libraries in general can be found [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows) @@ -79,19 +79,19 @@ npm install @azure/msal-node ## Usage ### MSAL basics -- Initialize a Public Client Application(./docs/initialize-public-client-application.md) -- [Configuration](./docs/configuration.md) -- [Request](./docs/request.md) -- [Response](lib/msal-common/docs/Response.md) +- Initialize a Public Client Application(https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/initialize-public-client-application.md) +- [Configuration](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md) +- [Request](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-common/docs/request.md) +- [Response](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-common/docs/response.md) ## Samples -There are multiple [samples](samples/msal-node-samples) included in the repository that use MSAL Node to acquire tokens. These samples are currently used for manual testing, and are not meant to be a reference of best practices, therefore use judgement and do not blindly copy this code to any production applications. +There are multiple [samples](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-node-samples) included in the repository that use MSAL Node to acquire tokens. These samples are currently used for manual testing, and are not meant to be a reference of best practices, therefore use judgement and do not blindly copy this code to any production applications. -- [msal-node-auth-code](samples/msal-node-samples/msal-node-auth-code): Express app using OAuth2.0 authorization code flow. -- [msal-node-device-code](samples/msal-node-samples/msal-node-device-code): Command line app using OAuth 2.0 device code flow. -- [msal-node-refresh-token](samples/msal-node-samples/msal-node-refresh-token): Command line app using OAuth 2.0 refresh flow. -- [msal-node-silent-flow](samples/msal-node-samples/msal-node-silent-flow): Express app using OAuth2.0 authorization code flow and refresh token flow to demonstrate silent retrieval of tokens when already logged in or when the app provides a in-disk cache for Single sign on experience -- msal-node-extensions (Coming soon): Uses the msal-extensions library to write the MSAL in-memory token cache to a disk. +- [auth-code](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-node-samples/auth-code): Express app using OAuth2.0 authorization code flow. +- [device-code](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-node-samples/device-code): Command line app using OAuth 2.0 device code flow. +- [refresh-token](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-node-samples/refresh-token): Command line app using OAuth 2.0 refresh flow. +- [silent-flow](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-node-samples/silent-flow): Express app using OAuth2.0 authorization code flow and refresh token flow to demonstrate silent retrieval of tokens when already logged in or when the app provides a in-disk cache for Single sign on experience +- msal-node-extensions (`Coming soon`): Uses the msal-extensions library to write the MSAL in-memory token cache to a disk. ## Build and Test diff --git a/lib/msal-node/docs/configuration.md b/lib/msal-node/docs/configuration.md index e603326a46..ca80f903f0 100644 --- a/lib/msal-node/docs/configuration.md +++ b/lib/msal-node/docs/configuration.md @@ -90,4 +90,4 @@ const msalInstance = new PublicClientApplication(msalConfig); | `piiLoggingEnabled` | If true, personally identifiable information (PII) is included in logs. | boolean | `false` | ## Next Steps -Proceed to understand the public APIs provided by `msal-node` for acquiring tokens [here](./request.md) +Proceed to understand the public APIs provided by `msal-node` for acquiring tokens [here](../../msal-common/docs/request.md) diff --git a/lib/msal-node/docs/initialize-public-client-application.md b/lib/msal-node/docs/initialize-public-client-application.md index d12d4f151c..d4621c6b62 100644 --- a/lib/msal-node/docs/initialize-public-client-application.md +++ b/lib/msal-node/docs/initialize-public-client-application.md @@ -62,4 +62,4 @@ const msalConfig = { [Configuration](https://azuread.github.io/microsoft-authentication-library-for-js/ref/msal-node/modules/_src_config_configuration_.html#configuration) has more options which are documented [here](./configuration.md). ## Next Steps -Proceed to understand the public APIs provided by `msal-node` for acquiring tokens [here](./request.md) +Proceed to understand the public APIs provided by `msal-node` for acquiring tokens [here](../../msal-common/docs/request.md) From bcfe954e18d44edf7a93dfd8ccb0190f141e153a Mon Sep 17 00:00:00 2001 From: sameerag Date: Mon, 6 Jul 2020 19:12:20 -0700 Subject: [PATCH 5/7] Remove extra table entry --- lib/msal-node/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/msal-node/README.md b/lib/msal-node/README.md index d996e49be0..30381a46a1 100644 --- a/lib/msal-node/README.md +++ b/lib/msal-node/README.md @@ -1,7 +1,7 @@ # (Alpha) Microsoft Authentication Library for JavaScript for Node(msal-node) for Node.js based Web apps | Getting Started | AAD Docs | Library Reference | -| --- | --- | --- | --- | +| --- | --- | --- | Currently `msal-node` library is under development, Please track the project progress [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/projects/4). From 80b5520de4c523e185a2faec9a009a1670e42169 Mon Sep 17 00:00:00 2001 From: sameerag Date: Mon, 6 Jul 2020 19:32:31 -0700 Subject: [PATCH 6/7] Addressing feedback --- lib/msal-common/docs/Response.md | 2 +- lib/msal-common/docs/request.md | 12 ++++++------ lib/msal-node/README.md | 24 +++++++++++++----------- lib/msal-node/docs/configuration.md | 5 +---- 4 files changed, 21 insertions(+), 22 deletions(-) diff --git a/lib/msal-common/docs/Response.md b/lib/msal-common/docs/Response.md index 95386d4898..6c1f7b1b1c 100644 --- a/lib/msal-common/docs/Response.md +++ b/lib/msal-common/docs/Response.md @@ -1,4 +1,4 @@ -MSAL will return an `AuthenticationResult.ts` object as a response to all public request APIs: +MSAL will return an `AuthenticationResult.ts` object as a response to all acquire token APIs: #### `msal-browser` public APIs for token acquisition: `loginPopup`, `acquireTokenPopup`, `acquireTokenSilent` or `handleRedirectPromise` diff --git a/lib/msal-common/docs/request.md b/lib/msal-common/docs/request.md index 8cb68010df..9bdfc2212e 100644 --- a/lib/msal-common/docs/request.md +++ b/lib/msal-common/docs/request.md @@ -6,15 +6,15 @@ Since MSAL Node supports various authorization code grants, there is support for ### Public APIs - [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). -The application is sent a URL that can be used to generate an `authorization code` by any browser of choice, and then proceed to call the below API for the `token acquisition` . +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. - [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`. ``` javascript const authCodeUrlParameters = { - scopes: ["user.read"], - redirectUri: ["http://localhost:3000/redirect"], + scopes: ["sample_scope"], + redirectUri: "your_redirect_uri", }; // get url to sign user in and consent to scopes needed for application @@ -23,9 +23,9 @@ The application is sent a URL that can be used to generate an `authorization cod }).catch((error) => console.log(JSON.stringify(error))); const tokenRequest = { - code: req.query.code, - redirectUri: "http://localhost:3000/redirect", - scopes: ["user.read"], + code: "authorization_code", + redirectUri: "your_redirect_uri", + scopes: ["sample_scope"], }; // acquire a token by exchanging the code diff --git a/lib/msal-node/README.md b/lib/msal-node/README.md index 30381a46a1..17a127808c 100644 --- a/lib/msal-node/README.md +++ b/lib/msal-node/README.md @@ -1,9 +1,11 @@ # (Alpha) Microsoft Authentication Library for JavaScript for Node(msal-node) for Node.js based Web apps +[![npm version](https://img.shields.io/npm/v/@azure/msal-node.svg?style=flat)](https://www.npmjs.com/package/@azure/msal-node/)[![npm version](https://img.shields.io/npm/dm/@azure/msal-node.svg)](https://nodei.co/npm/@azure/msal-node/)[![Coverage Status](https://coveralls.io/repos/github/AzureAD/microsoft-authentication-library-for-js/badge.svg?branch=dev)](https://coveralls.io/github/AzureAD/microsoft-authentication-library-for-js?branch=dev) + | Getting Started | AAD Docs | Library Reference | | --- | --- | --- | -Currently `msal-node` library is under development, Please track the project progress [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/projects/4). +Currently `msal-node` library is under development, Please track the project progress [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/projects/4). This documentation is also in progress and will be changing as we release our `alpha` patches. 1. [About](#about) 2. [FAQ](#faq) @@ -32,22 +34,23 @@ The current alpha version supports the below OAuth grant types: - [Refresh Token Grant](https://oauth.net/2/grant-types/refresh-token/) - Silent Flow (user convenience flow to acquire a token silently) -In the upcoming quarters we plan to add support for: +[Coming Soon] In the upcoming quarters we plan to add support for Confidential client flows: -- [Client Credential Grant](https://oauth.net/2/grant-types/client-credentials/) (`Coming soon`) -- Confidential client flow (authorization code flow with client secret) +- [Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) with client secret +- [Client Credential Grant](https://oauth.net/2/grant-types/client-credentials/) +- [On-behalf-of flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow) More details on different grant types supported by Microsoft authentication libraries in general can be found [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows) -### App models supported: +### Scenarios supported: -The app models supported with this library are: +The scenarios supported with this library are: - Destop app that calls web APIs - Web app that calls web APIs (upcoming) - Web APIs that call web APIs (upcoming) - Daemon apps (upcoming) -More details on APP models and the authentication flows that map to each of them can be found [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-flows-app-scenarios) +More details on scenarios and the authentication flows that map to each of them can be found [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-flows-app-scenarios) ## FAQ @@ -67,7 +70,6 @@ See [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/bl Before using `@azure/msal-node` you will need to register your app in the azure portal to get a valid `clientId` for configuration, and to register the routes that your app will accept redirect traffic on if applicable. Currently we support the below app registrations for `@azure/msal-node`: - [Desktop app that calls web APIs: App registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-desktop-app-registration) -- [Protected web API: App registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-protected-web-api-app-registration) ## Installation @@ -101,6 +103,9 @@ There are multiple [samples](https://github.com/AzureAD/microsoft-authentication - Navigate to `microsoft-authentication-library-for-js/lib/msal-node` and run `npm run build` ```javascript +// to link msal-node and msal-common packages +lerna bootstrap + // Change to the msal-node package directory cd lib/msal-common/ @@ -112,9 +117,6 @@ cd lib/msal-node/ // To run build only for node package npm run build - -// to link msal-node and msal-common packages -lerna bootstrap ``` ### Local Development diff --git a/lib/msal-node/docs/configuration.md b/lib/msal-node/docs/configuration.md index ca80f903f0..a43b16dd50 100644 --- a/lib/msal-node/docs/configuration.md +++ b/lib/msal-node/docs/configuration.md @@ -16,7 +16,7 @@ The configuration object can be passed into the `PublicClientApplication` constr ```javascript -// Call back API tp read from the cache in .json format +// Call back API to read from the cache in .json format const readFromStorage = () => { return fs.readFile("cache_file_path", "utf-8"); }; @@ -41,7 +41,6 @@ const msalConfig = { authority: "https://login.microsoftonline.com/common", knownAuthorities: [], cloudDiscoveryMetadata: "", - redirectUri: "enter_redirect_uri_here", }, cache: { cachePlugin // your implementation of cache plugin @@ -69,8 +68,6 @@ const msalInstance = new PublicClientApplication(msalConfig); | `authority` | URI of the tenant to authenticate and authorize with. Usually takes the form of `https://{uri}/{tenantid}`. | String in URI format with tenant - `https://{uri}/{tenantid}` | `https://login.microsoftonline.com/common` | | `knownAuthorities` | An array of URIs that are known to be valid. Used in B2C scenarios. | Array of strings in URI format | Empty array `[]` | | `cloudDiscoveryMetadata` | A string containing the cloud discovery response. Used in AAD scenarios. See performance.md for more info | string | Empty string `""` | -| `redirectUri` | URI where the authorization code response is sent back to. Whatever location is specified here must have the MSAL library available to handle the response. | String in URI format | Login request page (`window.location.href` of page which made auth request) | -`redirectUri` is the same as the original request location, this flag should be set to false. | boolean | `true` | ### Cache Config Options | Option | Description | Format | Default Value | From afb3497248d017a13517bbca9aba58d085f5508d Mon Sep 17 00:00:00 2001 From: sameerag Date: Mon, 6 Jul 2020 19:34:30 -0700 Subject: [PATCH 7/7] Add disclaimer --- lib/msal-node/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/msal-node/README.md b/lib/msal-node/README.md index 17a127808c..f65ab9af2f 100644 --- a/lib/msal-node/README.md +++ b/lib/msal-node/README.md @@ -5,7 +5,7 @@ | Getting Started | AAD Docs | Library Reference | | --- | --- | --- | -Currently `msal-node` library is under development, Please track the project progress [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/projects/4). This documentation is also in progress and will be changing as we release our `alpha` patches. +Currently `msal-node` library is under development, Please track the project progress [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/projects/4). This documentation is also in progress and will be changing as we release our `alpha` patches. **We do not recommend using this in a production environment yet**. 1. [About](#about) 2. [FAQ](#faq)