Skip to content

Commit ebe7ffe

Browse files
localdenlocalden
authored
Merge pull request #14 from Dickson-Mwendia/configure-docs-crr
Test cross-repo references for msal.js
2 parents cdc8851 + 508467e commit ebe7ffe

12 files changed

+301
-18
lines changed

‎.openpublishing.publish.config.json

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -41,20 +41,12 @@
4141
"sync_notification_subscribers": [],
4242
"branches_to_filter": [],
4343
"need_preview_pull_request": true,
44-
"dependent_repositories": [
45-
{
46-
"path_to_root": "_themes",
47-
"url": "https://github.com/Microsoft/templates.docs.msft",
48-
"branch": "main",
49-
"branch_mapping": {}
50-
}
51-
],
5244
"branch_target_mapping": {},
5345
"docs_build_engine": {},
5446
"skip_source_output_uploading": false,
5547
"JoinTOCPlugin": [
5648
{
57-
"TopLevelTOC": "msal/docs-ref-toc/fxtoc.yml",
49+
"TopLevelTOC": "msal/docs-ref-toc/.yml",
5850
"ReferenceTOC": "msal/docs-ref-autogen/toc.yml",
5951
"ReferenceTOCUrl": "/javascript/api/microsoft-authentication-library-js/toc.json?view=msal-js-latest",
6052
"ConceptualTOCUrl": "/microsoft-authentication-library-js/toc.json",
@@ -67,6 +59,21 @@
6759
}
6860
}
6961
],
62+
"dependent_repositories": [
63+
{
64+
"path_to_root": "_themes",
65+
"url": "https://github.com/Microsoft/templates.docs.msft",
66+
"branch": "main",
67+
"branch_mapping": {}
68+
},
69+
{
70+
"path_to_root": "lib",
71+
"url": "https://github.com/AzureAD/microsoft-authentication-library-for-js",
72+
"branch": "test-cross-repo-reference",
73+
"branch_mapping": {}
74+
}
75+
],
76+
"branch_target_mapping": {},
7077
"dependent_packages": [
7178
{
7279
"id": "opbuild.templates.uref",

‎msal-javascript-conceptual/docfx.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
"LICENSE-CODE",
1919
"ThirdPartyNotices.md",
2020
"SECURITY.md"
21+
"lib/**"
2122
]
2223
}
2324
],

‎msal-javascript-conceptual/index.md

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,12 @@
1-
# Welcome to msal-javascript-conceptual!
1+
---
2+
author: Dickson-Mwendia
3+
ms.service: active-directory
4+
ms.topic: include
5+
ms.date: 04/12/2023
6+
ms.author: dmwendia
7+
---
8+
9+
# Welcome to msal-javascript-conceptual!
10+
11+
12+
J

‎msal/docfx.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,8 @@
4444
"files": [
4545
"**/*.md"
4646
],
47-
"src": "overview",
48-
"dest": "api/overview",
47+
"src": "msal",
48+
"dest": "api",
4949
"exclude": [],
5050
"version": "msal-js-latest"
5151
},

‎msal/docs-ref-toc/fxtoc.yml

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
1-
- name: SDK reference
2-
uid: msal.sdk.landingPage.reference
3-
landingPageType: Root
1+
- name: MSAL.js Overview
42
expanded: true
5-
href: ~/overview/msal-overview.md
6-
children:
7-
- '**'
3+
href: ~/msal/msal-overview.md
4+
- name: MSAL Browser
5+
items:
6+
- name: Initialization of MSAL
7+
href: ~/msal/browser/initialization.md
8+
- name: Sign in users
9+
href: ~/msal/browser/login-user.md
10+
- name: Acquire tokens
11+
href: ~/msal/browser/acquire-token.md

‎msal/overview/PackageStructure.png renamed to ‎msal/msal/PackageStructure.png

File renamed without changes.

‎msal/msal/browser/acquire-token.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Acquire tokens in MSAL Browser
3+
description: Acquire tokens in MSAL Browser
4+
services: active-directory
5+
author: Dickson-Mwendia
6+
manager: CelesteDG
7+
8+
ms.service: active-directory
9+
ms.subservice: develop
10+
ms.topic: reference
11+
ms.workload: identity
12+
ms.date: 04/12/2023
13+
ms.author: dmwendia
14+
---
15+
16+
[!INCLUDE[MSAL Browser token acquisition](~/../lib/msal-browser/docs/includes/acquire-token.md)]

‎msal/msal/browser/initialization.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: MSAL Browser
3+
description: Getting started with MSAL Browser
4+
services: active-directory
5+
author: Dickson-Mwendia
6+
manager: CelesteDG
7+
8+
ms.service: active-directory
9+
ms.subservice: develop
10+
ms.topic: reference
11+
ms.workload: identity
12+
ms.date: 04/12/2023
13+
ms.author: dmwendia
14+
---
15+
16+
17+
# Getting started with MSAL Browser
18+
19+
20+
[!INCLUDE[MSAL Browser initialization](~/../../lib/msal-browser/docs/includes/initialization.md)]

‎msal/msal/browser/login-user.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Sign in users in MSAL Browser
3+
description: Sign in users in MSAL Browser
4+
services: active-directory
5+
author: Dickson-Mwendia
6+
manager: CelesteDG
7+
8+
ms.service: active-directory
9+
ms.subservice: develop
10+
ms.topic: reference
11+
ms.workload: identity
12+
ms.date: 04/12/2023
13+
ms.author: dmwendia
14+
---
15+
16+
[!INCLUDE[Sign in users](msal-browser/docs/includes/login-user.md)]

‎msal/msal/browser/v1-migration.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Migrating from MSAL 1.x to MSAL 2.x
2+
3+
If you are new to MSAL, you should start [here](./initialization.md).
4+
5+
If you are coming from [MSAL v1.x](../../msal-common/), you can follow this guide to update your code to use [MSAL v2.x](../../msal-browser/).
6+
7+
## 1. Update application registration
8+
9+
Go to the Azure AD portal for your tenant and review the App Registrations. You can create a [new registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-spa-app-registration#create-the-app-registration) for MSAL 2.x or you can [update your existing registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-spa-app-registration#redirect-uri-msaljs-20-with-auth-code-flow) for the registration that you are using for MSAL 1.x.
10+
11+
## 2. Add the msal-browser package to your project
12+
13+
See the [installation section of the README](../README.md#installation).
14+
15+
## 3. Update your code
16+
17+
In MSAL 1.x, you created an application instance as below:
18+
19+
```javascript
20+
import * as msal from "msal";
21+
22+
const msalInstance = new msal.UserAgentApplication(config);
23+
```
24+
25+
In MSAL 2.x, you can update this to use the new `PublicClientApplication` object.
26+
27+
```javascript
28+
import * as msal from "@azure/msal-browser";
29+
30+
const msalInstance = new msal.PublicClientApplication(config);
31+
```
32+
33+
There may be some small differences in the configuration object that is passed in. If you are passing a more advanced configuration to the `UserAgentApplication` object, see [here](./configuration.md) for more information on new app object configuration options.
34+
35+
Request and response object signatures have changed - `acquireTokenSilent` now has a separate object signature from the interactive APIs. Please see [here](./request-response-object.md) for more information on configuring the request APIs.
36+
37+
Most APIs from MSAL 1.x have been carried forward to MSAL 2.x without change. Some functions have been removed:
38+
- `handleRedirectCallback`
39+
- `urlContainsHash`
40+
- `getCurrentConfiguration`
41+
- `getLoginInProgress`
42+
- `getAccount`
43+
- `getAccountState`
44+
- `isCallback`
45+
46+
In MSAL 2.x, handling the response from the hash is an asynchronous operation, as MSAL will perform a token exchange as soon as it parses the authorization code from the response. Because of this, when performing redirect calls, MSAL provides the `handleRedirectPromise` function which will return a promise that resolves when the redirect has been fully handled by MSAL. When using a redirect method, the page used as the `redirectUri` must implement `handleRedirectPromise` to ensure the response is handled and tokens are cached when returning from the redirect.
47+
48+
```javascript
49+
const myMSALObj = new msal.PublicClientApplication(msalConfig);
50+
51+
// Register Callbacks for Redirect flow
52+
myMSALObj.handleRedirectPromise().then((tokenResponse) => {
53+
let accountObj = null;
54+
if (tokenResponse !== null) {
55+
accountObj = tokenResponse.account;
56+
const id_token = tokenResponse.idToken;
57+
const access_token = tokenResponse.accessToken;
58+
} else {
59+
const currentAccounts = myMSALObj.getAllAccounts();
60+
if (!currentAccounts || currentAccounts.length === 0) {
61+
// No user signed in
62+
return;
63+
} else if (currentAccounts.length > 1) {
64+
// More than one user signed in, find desired user with getAccountByUsername(username)
65+
} else {
66+
accountObj = currentAccounts[0];
67+
}
68+
}
69+
70+
const username = accountObj.username;
71+
72+
}).catch((error) => {
73+
handleError(error);
74+
});
75+
76+
function signIn() {
77+
myMSALObj.loginRedirect(loginRequest);
78+
}
79+
80+
async function getTokenRedirect(request) {
81+
return await myMSALObj.acquireTokenSilent(request).catch(error => {
82+
this.logger.info("silent token acquisition fails. acquiring token using redirect");
83+
// fallback to interaction when silent call fails
84+
return myMSALObj.acquireTokenRedirect(request)
85+
});
86+
}
87+
```
88+
89+
During `loginPopup`, `acquireTokenPopup`, or `acquireTokenSilent` calls, you can wait for the promise to resolve.
90+
91+
```javascript
92+
const myMSALObj = new msal.PublicClientApplication(msalConfig);
93+
94+
async function signIn(method) {
95+
try {
96+
const loginResponse = await myMSALObj.loginPopup(loginRequest);
97+
} catch (err) {
98+
handleError(error);
99+
}
100+
101+
const currentAccounts = myMSALObj.getAllAccounts();
102+
if (!currentAccounts || currentAccounts.length === 0) {
103+
// No user signed in
104+
return;
105+
} else if (currentAccounts.length > 1) {
106+
// More than one user signed in, find desired user with getAccountByUsername(username)
107+
} else {
108+
accountObj = currentAccounts[0];
109+
}
110+
}
111+
112+
async function getTokenPopup(request) {
113+
return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
114+
this.logger.info("silent token acquisition fails. acquiring token using popup");
115+
// fallback to interaction when silent call fails
116+
return await myMSALObj.acquireTokenPopup(request).catch(error => {
117+
handleError(error);
118+
});
119+
});
120+
}
121+
```
122+
123+
Please see the [login](./login-user.md) and [acquire token](./acquire-token.md) docs for more detailed information on usage.
124+
125+
Refresh tokens are now returned as part of the token responses, and are used by the library to renew access tokens without interaction or the use of iframes. See the [token lifetimes docs](./token-lifetimes.md) for more information on renewing tokens.
126+
127+
All other APIs should work as before. It is recommended to take a look at the [default sample](../../../samples/msal-browser-samples/VanillaJSTestApp2.0) to see a working example of MSAL 2.0.

‎msal/msal/browser/v2-migration.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Migrating from MSAL 2.x to MSAL 3.x
2+
3+
If you are new to MSAL, you should start [here](initialization.md).
4+
5+
If you are coming from [MSAL v1.x](../../msal-core/), you should check [this guide](v1-migration.md) first to migrate to [MSAL v2.x](../../msal-browser/) and then follow next steps.
6+
7+
If you are coming from [MSAL v2.x](../../msal-browser/), you can follow this guide to update your code to use [MSAL v3.x](../../msal-browser/).
8+
9+
## Update your code
10+
11+
In MSAL v2.x, you created an application instance as below:
12+
13+
```javascript
14+
import * as msal from "@azure/msal-browser";
15+
16+
const msalConfig = {
17+
auth: {
18+
clientId: 'your_client_id'
19+
}
20+
};
21+
22+
const msalInstance = new msal.PublicClientApplication(msalConfig);
23+
```
24+
25+
In MSAL v3.x, you must initialize the application object as well. There are several options at your disposal:
26+
27+
### Option 1
28+
29+
Instantiate a `PublicClientApplication` object and initialize it afterwards. The `initialize` function is asynchronous and must resolve before invoking other MSAL.js APIs.
30+
31+
```javascript
32+
import * as msal from "@azure/msal-browser";
33+
34+
const msalConfig = {
35+
auth: {
36+
clientId: 'your_client_id'
37+
}
38+
};
39+
40+
const msalInstance = new msal.PublicClientApplication(msalConfig);
41+
await msalInstance.initialize();
42+
```
43+
44+
### Option 2
45+
46+
Invoke the `createPublicClientApplication` static method which returns an initialized `PublicClientApplication` object. Note that this function is asynchronous.
47+
48+
```javascript
49+
import * as msal from "@azure/msal-browser";
50+
51+
const msalConfig = {
52+
auth: {
53+
clientId: 'your_client_id'
54+
}
55+
};
56+
57+
const msalInstance = await msal.PublicClientApplication.createPublicClientApplication(msalConfig);
58+
```
59+
60+
All other APIs are backward compatible with [MSAL v2.x](../../msal-browser/). It is recommended to take a look at the [default sample](../../../samples/msal-browser-samples/VanillaJSTestApp2.0) to see a working example of MSAL v3.0.
61+
62+
## Key changes
63+
64+
### Browser support
65+
66+
MSAL.js no longer supports the following browsers:
67+
68+
- IE 11
69+
- Edge (Legacy)
70+
71+
### Package dependencies
72+
73+
Typescript version was bumped from `3.8.3` to `4.9.5`.
74+
75+
### Compiler options
76+
77+
Module/target versions were bumped from `es6`/`es5` to `es2020`/`es2020` respectively.
78+
79+
### CDN
80+
81+
MSAL.js is no longer hosted on a CDN. Check [this doc](cdn-usage.md) for more details.

‎msal/overview/msal-overview.md renamed to ‎msal/msal/msal-overview.md

File renamed without changes.

0 commit comments

Comments
 (0)