Skip to content

Commit 0e5566c

Browse files
derisenderisen
committed
incremental readmes added
1 parent 2bc2bf7 commit 0e5566c

7 files changed

Lines changed: 1309 additions & 3 deletions

File tree

‎1-Authentication/1-sign-in/README-incremental.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
---
2+
page_type: sample
3+
languages:
4+
- javascript
5+
products:
6+
- node.js
7+
- microsoft-identity-platform
8+
- azure-active-directory
9+
name: A Node.js & Express Web App authenticating users against Azure AD with MSAL Node
10+
urlFragment: ms-identity-javascript-nodejs-tutorial
11+
description: "This sample demonstrates a Node.js & Express Web App authenticating users against Azure AD with MSAL Node"
12+
---
13+
14+
# A Node.js & Express Web App authenticating users against Azure AD with MSAL Node
15+
16+
1. [Overview](#overview)
17+
1. [Scenario](#scenario)
18+
1. [Contents](#contents)
19+
1. [Prerequisites](#prerequisites)
20+
1. [Setup](#setup)
21+
1. [Registration](#registration)
22+
1. [Running the sample](#running-the-sample)
23+
1. [Explore the sample](#explore-the-sample)
24+
1. [About the code](#about-the-code)
25+
1. [More information](#more-information)
26+
1. [Community Help and Support](#community-help-and-support)
27+
1. [Contributing](#contributing)
28+
29+
## Overview
30+
31+
This sample demonstrates a Node.js & Express web application that authenticates users against Azure AD, with the help of [Microsoft Authentication Library for Node.js [PREVIEW]](https://aka.ms/msalnode) (MSAL Node [PREVIEW]). In doing so, it also illustrates various authentication concepts, such as [OpenID scopes](https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes), [ID Tokens](https://docs.microsoft.com/azure/active-directory/develop/id-tokens), [ID Token validation](https://docs.microsoft.com/azure/active-directory/develop/id-tokens#validating-an-id_token) and more.
32+
33+
## Scenario
34+
35+
1. The client application uses **MSAL Node** to obtain an ID Token from **Azure AD**.
36+
2. The **ID Token** proves that the user has successfully authenticated against **Azure AD**.
37+
38+
![Overview](./ReadmeFiles/topology.png)
39+
40+
## Contents
41+
42+
| File/folder | Description |
43+
|-----------------------|---------------------------------------------------------------|
44+
| `AppCreationScripts/` | Contains Powershell scripts to automate app registration. |
45+
| `ReadmeFiles/` | List of changes to the sample. |
46+
| `App/` | Express application source folder. |
47+
| `app.js` | Application entry point. |
48+
49+
## Prerequisites
50+
51+
- A user account in your **Azure AD** tenant. This sample will not work with a **personal Microsoft account**. Therefore, if you signed in to the [Azure portal](https://portal.azure.com) with a personal account and have never created a user account in your directory before, you need to do that now.
52+
53+
## Setup
54+
55+
### Step 1: Clone or download this repository
56+
57+
From your shell or command line:
58+
59+
```console
60+
git clone https://github.com/Azure-Samples/ms-identity-javascript-nodejs-tutorial.git
61+
```
62+
63+
or download and extract the repository .zip file.
64+
65+
> :warning: To avoid path length limitations on Windows, we recommend cloning into a directory near the root of your drive.
66+
67+
### Step 2: Install project dependencies
68+
69+
Locate the root of the sample folder. Then:
70+
71+
```console
72+
cd 1-Authentication\1-sign-in
73+
npm install
74+
```
75+
76+
## Registration
77+
78+
There is one project in this sample. To register it, you can:
79+
80+
- follow the steps below for manually register your apps
81+
- or use PowerShell scripts that:
82+
- **automatically** creates the Azure AD applications and related objects (passwords, permissions, dependencies) for you.
83+
- modify the projects' configuration files.
84+
85+
<details>
86+
<summary>Expand this section if you want to use this automation:</summary>
87+
88+
> :warning: If you have never used **Azure AD Powershell** before, we recommend you go through the [App Creation Scripts](./AppCreationScripts/AppCreationScripts.md) once to ensure that your environment is prepared correctly for this step.
89+
90+
1. On Windows, run PowerShell as **Administrator** and navigate to the root of the cloned directory
91+
1. If you have never used Azure AD Powershell before, we recommend you go through the [App Creation Scripts](./AppCreationScripts/AppCreationScripts.md) once to ensure that your environment is prepared correctly for this step.
92+
1. In PowerShell run:
93+
94+
```PowerShell
95+
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
96+
```
97+
98+
1. Run the script to create your Azure AD application and configure the code of the sample application accordingly.
99+
1. In PowerShell run:
100+
101+
```PowerShell
102+
cd .\AppCreationScripts\
103+
.\Configure.ps1
104+
```
105+
106+
> Other ways of running the scripts are described in [App Creation Scripts](./AppCreationScripts/AppCreationScripts.md)
107+
> The scripts also provide a guide to automated application registration, configuration and removal which can help in your CI/CD scenarios.
108+
109+
</details>
110+
111+
### Choose the Azure AD tenant where you want to create your applications
112+
113+
As a first step you'll need to:
114+
115+
1. Sign in to the [Azure portal](https://portal.azure.com).
116+
1. If your account is present in more than one Azure AD tenant, select your profile at the top right corner in the menu on top of the page, and then **switch directory** to change your portal session to the desired Azure AD tenant.
117+
118+
### Register the app
119+
120+
1. Navigate to the [Azure portal](https://portal.azure.com) and select the **Azure AD** service.
121+
1. Select the **App Registrations** blade on the left, then select **New registration**.
122+
1. In the **Register an application page** that appears, enter your application's registration information:
123+
- In the **Name** section, enter a meaningful application name that will be displayed to users of the app, for example `ExpressWebApp`.
124+
- Under **Supported account types**, select **Accounts in this organizational directory only**.
125+
- In the **Redirect URI (optional)** section, select **Web** in the combo-box and enter the following redirect URI: `http://localhost:4000/redirect`.
126+
1. Select **Register** to create the application.
127+
1. In the app's registration screen, find and note the **Application (client) ID**. You use this value in your app's configuration file(s) later in your code.
128+
1. Select **Save** to save your changes.
129+
1. In the app's registration screen, select the **Certificates & secrets** blade in the left to open the page where we can generate secrets and upload certificates.
130+
1. In the **Client secrets** section, select **New client secret**:
131+
- Type a key description (for instance `app secret`),
132+
- Select one of the available key durations (**In 1 year**, **In 2 years**, or **Never Expires**) as per your security posture.
133+
- The generated key value will be displayed when you select the **Add** button. Copy the generated value for use in the steps later.
134+
- You'll need this key later in your code's configuration files. This key value will not be displayed again, and is not retrievable by any other means, so make sure to note it from the Azure portal before navigating to any other screen or blade.
135+
136+
#### Configure the app to use your app registration
137+
138+
Open the project in your IDE (like Visual Studio or Visual Studio Code) to configure the code.
139+
140+
> In the steps below, "ClientID" is the same as "Application ID" or "AppId".
141+
142+
1. Open the `auth.json` file.
143+
1. Find the key `ClientId` and replace the existing value with the application ID (clientId) of the application copied from the **Azure Portal**.
144+
1. Find the key `TenantId` and replace the existing value with your Azure AD tenant ID copied from the **Azure Portal**.
145+
1. Find the key `ClientSecret` and replace the existing value with the key you saved during the creation of the application copied from the **Azure Portal**.
146+
1. Find the key `homePageRoute` and replace the existing value with the home page route of your application, e.g. `/home`.
147+
1. Find the key `redirectUri` and replace the existing value with the redirect URI that you have registered on **Azure Portal**, e.g. `http://localhost:4000/redirect`.
148+
1. Find the key `postLogoutRedirectUri` and replace the existing value with the URI of the page that you wish to be redirected after signing-out, e.g `http://localhost:4000/`.
149+
150+
## Running the sample
151+
152+
Locate the root of the sample folder. Then:
153+
154+
```console
155+
npm start
156+
```
157+
158+
## Explore the sample
159+
160+
1. Open your browser and navigate to `http://localhost:4000`.
161+
1. Click the sign-in button on the top right corner.
162+
163+
![Screenshot](./ReadmeFiles/screenshot.png)
164+
165+
> :information_source: Did the sample not work for you as expected? Then please reach out to us using the [GitHub Issues](../../../../issues) page.
166+
167+
## We'd love your feedback!
168+
169+
Were we successful in addressing your learning objective? Consider taking a moment to [share your experience with us](https://forms.office.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR73pcsbpbxNJuZCMKN0lURpUQkRCSVdRSk8wUjdZSkg2NEZGOFFaTkxQVyQlQCN0PWcu).
170+
171+
## About the code
172+
173+
### Configuration
174+
175+
### Sign-in
176+
177+
### ID Token validation
178+
179+
### Sign-out
180+
181+
### National Clouds
182+
183+
## Next Tutorial
184+
185+
Continue with the next tutorial: [Get an Access Token and call Microsoft Graph](../../2-Authorization-I/1-call-graph/README-incremental.md).
186+
187+
## More information
188+
189+
Configure your application:
190+
191+
- [Initialize client applications using MSAL.js](https://docs.microsoft.com/azure/active-directory/develop/msal-js-initializing-client-applications)
192+
- [Single sign-on with MSAL.js](https://docs.microsoft.com/azure/active-directory/develop/msal-js-sso)
193+
- [Handle MSAL.js exceptions and errors](https://docs.microsoft.com/azure/active-directory/develop/msal-handling-exceptions?tabs=javascript)
194+
- [Logging in MSAL.js applications](https://docs.microsoft.com/azure/active-directory/develop/msal-logging?tabs=javascript)
195+
- [Pass custom state in authentication requests using MSAL.js](https://docs.microsoft.com/azure/active-directory/develop/msal-js-pass-custom-state-authentication-request)
196+
- [Prompt behavior in MSAL.js interactive requests](https://docs.microsoft.com/azure/active-directory/develop/msal-js-prompt-behavior)
197+
198+
Learn more about the Microsoft identity platform:
199+
200+
- [Microsoft identity platform (Azure Active Directory for developers)](https://docs.microsoft.com/azure/active-directory/develop/)
201+
- [Overview of Microsoft Authentication Library (MSAL)](https://docs.microsoft.com/azure/active-directory/develop/msal-overview)
202+
- [Understanding Azure AD application consent experiences](https://docs.microsoft.com/azure/active-directory/develop/application-consent-experience)
203+
- [Understand user and admin consent](https://docs.microsoft.com/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant#understand-user-and-admin-consent)
204+
- [Microsoft identity platform and OpenID Connect protocol](https://docs.microsoft.com/azure/active-directory/develop/v2-protocols-oidc)
205+
- [Microsoft Identity Platform ID Tokens](https://docs.microsoft.com/azure/active-directory/develop/id-tokens)
206+
207+
For more information about how OAuth 2.0 protocols work in this scenario and other scenarios, see [Authentication Scenarios for Azure AD](https://docs.microsoft.com/azure/active-directory/develop/authentication-flows-app-scenarios).
208+
209+
## Community Help and Support
210+
211+
Use [Stack Overflow](http://stackoverflow.com/questions/tagged/msal) to get support from the community.
212+
Ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before.
213+
Make sure that your questions or comments are tagged with [`azure-active-directory` `azure-ad-b2c` `ms-identity` `adal` `msal`].
214+
215+
If you find a bug in the sample, raise the issue on [GitHub Issues](../../issues).
216+
217+
To provide feedback on or suggest features for Azure Active Directory, visit [User Voice page](https://feedback.azure.com/forums/169401-azure-active-directory).
218+
219+
## Contributing
220+
221+
If you'd like to contribute to this sample, see [CONTRIBUTING.MD](/CONTRIBUTING.md).
222+
223+
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.

0 commit comments

Comments
 (0)