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-common/docs/Response.md b/lib/msal-common/docs/Response.md new file mode 100644 index 0000000000..6c1f7b1b1c --- /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 acquire token 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-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..9bdfc2212e --- /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`. 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: ["sample_scope"], + redirectUri: "your_redirect_uri", + }; + + // 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: "authorization_code", + redirectUri: "your_redirect_uri", + scopes: ["sample_scope"], + }; + + // 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/README.md b/lib/msal-node/README.md index 28c5293f63..f65ab9af2f 100644 --- a/lib/msal-node/README.md +++ b/lib/msal-node/README.md @@ -1,50 +1,156 @@ -# 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 -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 +[![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) -```javascript -// Change to the msal-node package directory -cd lib/msal-node/ +| Getting Started | AAD Docs | Library Reference | +| --- | --- | --- | -// Ensure you are using the local build of msal-common -npm link @azure/msal-common +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**. -// To run build only for node package -npm run build +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) + +## About + +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) + +[Coming Soon] In the upcoming quarters we plan to add support for Confidential client flows: + +- [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) + +### Scenarios supported: + +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 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 + +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 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 + +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) + +## Installation + +### Via NPM: +```javascript +npm install @azure/msal-node ``` -TBD: Add lerna bootstrap to build common/node in one step -## Local Development +## Usage -Below is a list of commands you will probably find useful. +### MSAL basics +- 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) -### `npm start` +## Samples +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. -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. +- [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 -Your library will be rebuilt if you make edits. +- 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` -### `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/ + +// To run build only for node package +npm run build + +// Change to the msal-node package directory +cd lib/msal-node/ + +// To run build only for node package +npm run build +``` + +### Local Development +Below is a list of commands you will probably find useful: + +#### `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..a43b16dd50 --- /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 to 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: "", + }, + 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 `""` | + +### 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` | + +## Next Steps +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 new file mode 100644 index 0000000000..d4621c6b62 --- /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](../../msal-common/docs/request.md)