You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -66,119 +66,137 @@ This sample demonstrates how sign in users into a a Node.js & Express web app by
66
66
* An **Azure AD for Customers** tenant. For more information, see: [How to get an Azure AD for Customers tenant](https://github.com/microsoft/entra-previews/blob/PP2/docs/1-Create-a-CIAM-tenant.md)
67
67
* Microsoft Entra ID for customers tenant. If you don't already have one, [sign up for a free trial](https://aka.ms/ciam-free-trial).
68
68
69
-
## Prepare your tenant
70
69
71
-
###Register web application in your tenant
70
+
## Register web application in your tenant
72
71
73
72
To enable your application to sign in users with Microsoft Entra, Microsoft Entra ID for customers must be made aware of the application you create. The app registration establishes a trust relationship between the app and Microsoft Entra. When you register an application, External ID generates a unique identifier known as an **Application (client) ID**, a value used to identify your app when creating authentication requests.
74
73
75
-
You can register an app in your tenant by using two methods:
76
-
77
-
* Use Microsoft Graph PowerShell to automatically register the app. This option automatically creates the applications and related objects app secrets, then modifies your project config files, so you run the app without any further action.
78
-
79
-
<details>
80
-
<summary>Expand this section if you want to use this automation:</summary>
81
-
82
-
> :warning: If you have never used **Microsoft Graph PowerShell** before, we recommend you go through the [App Creation Scripts Guide](./AppCreationScripts/AppCreationScripts.md) once to ensure that you've prepared your environment correctly for this step.
83
-
84
-
1. Ensure that you have PowerShell 7 or later installed.
85
-
1. Run the script to create your Microsoft Entra ID application and configure the code of the sample application accordingly.
86
-
1. For interactive process in PowerShell, run:
87
-
88
-
```PowerShell
89
-
cd .\AppCreationScripts\
90
-
.\Configure.ps1 -TenantId "[Optional] - your tenant id" -AzureEnvironmentName "[Optional] - Azure environment, defaults to 'Global'"
91
-
```
92
-
93
-
> Other ways of running the scripts are described in [App Creation Scripts guide](./AppCreationScripts/AppCreationScripts.md). The scripts also provides a guide to automated application registration, configuration and removal which can help in your CI/CD scenarios.
94
-
95
-
> :information_source: This sample can make use of client certificates. You can use **AppCreationScripts** to register an Microsoft Entra ID application with certificates. For more information see, [Use client certificate for authentication in your Node.js web app instead of client secrets](https://review.learn.microsoft.com/entra/external-id/customers/how-to-web-app-node-use-certificate)
96
-
97
-
</details>
98
-
99
-
* Manually register your apps in Microsoft Entra Admin center. To do, follow these steps:
100
-
101
-
1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least an [Application Developer](~/identity/role-based-access-control/permissions-reference.md#application-developer).
102
-
1. If you have access to multiple tenants, use the **Settings** icon  in the top menu to switch to your customer tenant from the **Directories + subscriptions** menu.
103
-
1. Browse to **Identity** >**Applications** > **App registrations**.
104
-
1. Select **+ New registration**.
105
-
1. In the **Register an application** page that appears;
106
-
107
-
1. Enter a meaningful application **Name** that is displayed to users of the app, for example *ciam-client-app*.
108
-
1. Under **Supported account types**, select **Accounts in this organizational directory only**.
109
-
110
-
1. Select **Register**.
111
-
1. The application's **Overview** pane displays upon successful registration. Record the **Application (client) ID** to be used in your application source code.
112
-
113
-
114
-
#### Create User Flows
115
-
116
-
Please refer to: [Tutorial: Create user flow in Azure Active Directory CIAM](https://github.com/microsoft/entra-previews/blob/PP2/docs/3-Create-sign-up-and-sign-in-user-flow.md)
117
-
118
-
> :information_source: To enable password reset in Customer Identity Access Management (CIAM) in Azure Active Directory (Azure AD), please refer to: [Tutorial: Enable self-service password reset](https://github.com/microsoft/entra-previews/blob/PP2/docs/4-Enable-password-reset.md)
119
-
120
-
#### Add External Identity Providers
121
-
122
-
Please refer to:
123
-
124
-
* [Tutorial: Add Google as an identity provider](https://github.com/microsoft/entra-previews/blob/PP2/docs/6-Add-Google-identity-provider.md)
125
-
* [Tutorial: Add Facebook as an identity provider](https://github.com/microsoft/entra-previews/blob/PP2/docs/7-Add-Facebook-identity-provider.md)
126
-
127
-
#### Register the client app (ciam-msal-node-webapp)
128
-
129
-
1. Navigate to the [Azure portal](https://portal.azure.com) and select the **Azure AD for Customers** service.
130
-
1. Select the **App Registrations** blade on the left, then select **New registration**.
131
-
1. In the **Register an application page** that appears, enter your application's registration information:
132
-
1. In the **Name** section, enter a meaningful application name that will be displayed to users of the app, for example `ciam-msal-node-webapp`.
133
-
1. Under **Supported account types**, select **Accounts in this organizational directory only**
134
-
1. Select **Register** to create the application.
135
-
1. In the **Overview** blade, find and note the **Application (client) ID** and *Directory (tenant) ID**. You use these values in your app's configuration file(s) later in your code.
136
-
1. In the app's registration screen, select the **Authentication** blade to the left.
137
-
1. If you don't have a platform added, select **Add a platform** and select the **Web** option.
138
-
1. In the **Redirect URI** section enter the following redirect URI:
139
-
1. `http://localhost:3000/`
140
-
1. `http://localhost:3000/auth/redirect`
141
-
1. Click **Save** to save your changes.
142
-
1. In the app's registration screen, select the **Certificates & secrets** blade in the left to open the page where you can generate secrets and upload certificates.
143
-
1. In the **Client secrets** section, select **New client secret**:
144
-
1. Type a key description (for instance `app secret`).
145
-
1. Select one of the available key durations (**6 months**, **12 months** or **Custom**) as per your security posture.
146
-
1. The generated key value will be displayed when you select the **Add** button. Copy and save the generated value for use in later steps.
147
-
1. 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.
148
-
> :warning: For enhanced security, consider using **certificates** instead of client secrets. See: [How to use certificates instead of secrets](./README-use-certificate.md).
149
-
1. Since this app signs-in users, we will now proceed to select **delegated permissions**, which is is required by apps signing-in users.
150
-
1. In the app's registration screen, select the **API permissions** blade in the left to open the page where we add access to the APIs that your application needs:
151
-
1. Select the **Add a permission** button and then:
152
-
1. Ensure that the **Microsoft APIs** tab is selected.
153
-
1. In the *Commonly used Microsoft APIs* section, select **Microsoft Graph**
154
-
1. In the **Delegated permissions** section, select **openid**, **offline_access** in the list. Use the search box if necessary.
155
-
1. Select the **Add permissions** button at the bottom.
156
-
1. At this stage, the permissions are assigned correctly, but since it's a CIAM tenant, the users themselves cannot consent to these permissions. To get around this problem, we'd let the [tenant administrator consent on behalf of all users in the tenant](https://docs.microsoft.com/azure/active-directory/develop/v2-admin-consent). Select the **Grant admin consent for {tenant}** button, and then select **Yes** when you are asked if you want to grant consent for the requested permissions for all accounts in the tenant. You need to be a tenant admin to be able to carry out this operation.
157
-
158
-
##### Configure the client app (ciam-msal-node-webapp) to use your app registration
159
-
160
-
Open the project in your IDE (like Visual Studio or Visual Studio Code) to configure the code.
161
-
162
-
> In the steps below, "ClientID" is the same as "Application ID" or "AppId".
163
-
164
-
1. Open the `App\authConfig.js` file.
165
-
1. Find the key `Enter_the_Application_Id_Here` and replace the existing value with the application ID (clientId) of `ciam-msal-node-webapp` app copied from the Azure portal.
166
-
1. Find the placeholder `Enter_the_Tenant_Subdomain_Here` and replace it with the Directory (tenant) subdomain. For instance, if your tenant primary domain is `contoso.onmicrosoft.com`, use `contoso`. If you don't have your tenant domain name, learn how to [read your tenant details](https://review.learn.microsoft.com/azure/active-directory/external-identities/customers/how-to-create-customer-tenant-portal#get-the-customer-tenant-details).
167
-
1. Find the key `Enter_the_Client_Secret_Here` and replace the existing value with the generated secret that you saved during the creation of `ciam-msal-node-webapp` copied from the Azure portal.
168
-
169
-
## Setup the sample
170
-
171
-
### Step 1: Clone or download this repository
74
+
You can register an app in your tenant automatically by using Microsoft Graph PowerShell or Manually register your apps in Microsoft Entra Admin center.
75
+
76
+
When you use Microsoft Graph PowerShell, you automatically register the applications and related objects app secrets, then modifies your project config files, so you run the app without any further action.
77
+
78
+
<details>
79
+
<summary>Expand this section if you want to use this automation:</summary>
80
+
81
+
> :warning: If you have never used **Microsoft Graph PowerShell** before, we recommend you go through the [App Creation Scripts Guide](./AppCreationScripts/AppCreationScripts.md) once to ensure that you've prepared your environment correctly for this step.
82
+
83
+
1. Ensure that you have PowerShell 7 or later installed.
84
+
1. Run the script to create your Microsoft Entra ID application and configure the code of the sample application accordingly.
85
+
1. For interactive process in PowerShell, run:
86
+
87
+
```PowerShell
88
+
cd .\AppCreationScripts\
89
+
.\Configure.ps1 -TenantId "[Optional] - your tenant id" -AzureEnvironmentName "[Optional] - Azure environment, defaults to 'Global'"
90
+
```
91
+
92
+
> Other ways of running the scripts are described in [App Creation Scripts guide](./AppCreationScripts/AppCreationScripts.md). The scripts also provides a guide to automated application registration, configuration and removal which can help in your CI/CD scenarios.
93
+
94
+
> :note: This sample can make use of client certificates. You can use **AppCreationScripts** to register an Microsoft Entra ID application with certificates. For more information see, [Use client certificate for authentication in your Node.js web app instead of client secrets](https://review.learn.microsoft.com/entra/external-id/customers/how-to-web-app-node-use-certificate).
95
+
96
+
</details>
97
+
98
+
To manually register your apps in Microsoft Entra Admin center, follow these steps:
99
+
100
+
1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least an [Application Developer](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#application-developer).
101
+
1. If you have access to multiple tenants, use the **Settings** icon () in the top menu to switch to your customer tenant from the **Directories + subscriptions** menu.
102
+
1. Browse to **Identity** >**Applications** > **App registrations**.
103
+
1. Select **+ New registration**.
104
+
1. In the **Register an application** page that appears;
105
+
106
+
1. Enter a meaningful application **Name** that is displayed to users of the app, for example *ciam-client-app*.
107
+
1. Under **Supported account types**, select **Accounts in this organizational directory only**.
108
+
109
+
1. Select **Register**.
110
+
1. The application's **Overview** pane displays upon successful registration. Record the **Application (client) ID** to be used in your application source code.
111
+
112
+
To specify your app type to your app registration, follow these steps:
113
+
114
+
1. Under **Manage**, select **Authentication**.
115
+
1. On the **Platform configurations** page, select **Add a platform**, and then select **Web** option.
116
+
1. For the **Redirect URIs** enter `http://localhost:3000/auth/redirect`.
117
+
1. Select **Configure** to save your changes.
118
+
119
+
## Add app client secret
120
+
121
+
Create a client secret for the registered application. The application uses the client secret to prove its identity when it requests for tokens:
122
+
123
+
1. From the **App registrations** page, select the application that you created (such as *ciam-client-app*) to open its **Overview** page.
124
+
1. Under **Manage**, select **Certificates & secrets**.
125
+
1. Select **New client secret**.
126
+
1. In the **Description** box, enter a description for the client secret (for example, *ciam app client secret*).
127
+
1. Under **Expires**, select a duration for which the secret is valid (per your organizations security rules), and then select **Add**.
128
+
1. Record the secret's **Value**. You'll use this value for configuration in a later step.
129
+
130
+
> :information_source: The secret value won't be displayed again, and is not retrievable by any means, after you navigate away from the **Certificates and secrets** page, so make sure you record it. For enhanced security, [Use client certificate for authentication in your Node.js web app instead of client secrets](https://learn.microsoft.com/entra/external-id/customers/how-to-web-app-node-use-certificate).
131
+
132
+
## Grant API permissions
133
+
134
+
1. From the **App registrations** page, select the application that you created (such as *ciam-client-app*) to open its **Overview** page.
135
+
1. Under **Manage**, select **API permissions**.
136
+
1. Under **Configured permissions**, select **Add a permission**.
137
+
1. Select **Microsoft APIs** tab.
138
+
1. Under **Commonly used Microsoft APIs** section, select **Microsoft Graph**.
139
+
1. Select **Delegated permissions** option.
140
+
1. Under **Select permissions** section, search for and select both **openid** and **offline_access** permissions.
141
+
1. Select the **Add permissions** button.
142
+
1. At this point, you've assigned the permissions correctly. However, since the tenant is a customer's tenant, the consumer users themselves can't consent to these permissions. You as the admin must consent to these permissions on behalf of all the users in the tenant:
143
+
144
+
1. Select **Grant admin consent for \<your tenant name\>**, then select **Yes**.
145
+
1. Select **Refresh**, then verify that **Granted for \<your tenant name\>** appears under **Status** for both scopes.
146
+
147
+
## Create user Flows
148
+
149
+
Follow these steps to create a user flow a customer can use to sign in or sign up for an application.
150
+
151
+
1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least an [External ID User Flow Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#external-id-user-flow-administrator).
152
+
1. If you have access to multiple tenants, use the **Settings** icon () in the top menu to switch to your customer tenant from the **Directories + subscriptions** menu.
153
+
1. Browse to **Identity** > **External Identities** > **User flows**.
154
+
1. Select **+ New user flow**.
155
+
1. On the **Create** page:
156
+
157
+
1. Enter a **Name** for the user flow, such as *SignInSignUpSample*.
158
+
1. In the **Identity providers** list, select **Email Accounts**. This identity provider allows users to sign-in or sign-up using their email address.
159
+
160
+
> note: Additional identity providers will be listed here only after you set up federation with them. For example, if you set up federation with [Google](https://learn.microsoft.com/entra/external-id/customers/how-to-google-federation-customers) or [Facebook](https://learn.microsoft.com/entra/external-id/customers/how-to-facebook-federation-customers), you'll be able to select those additional identity providers here.
161
+
162
+
1. Under **Email accounts**, you can select one of the two options. For this tutorial, select **Email with password**.
163
+
164
+
- **Email with password**: Allows new users to sign up and sign in using an email address as the sign-in name and a password as their first factor credential.
165
+
- **Email one-time-passcode**: Allows new users to sign up and sign in using an email address as the sign-in name and email one-time passcode as their first factor credential.
166
+
167
+
> note: Email one-time passcode must be enabled at the tenant level (**All Identity Providers** > **Email One-time-passcode**) for this option to be available at the user flow level.
168
+
169
+
1. Under **User attributes**, choose the attributes you want to collect from the user upon sign-up. By selecting **Show more**, you can choose attributes and claims for **Country/Region**, **Display Name**, and **Postal Code**. Select **OK**. (Users are only prompted for attributes when they sign up for the first time.)
170
+
171
+
1. Select **Create**. The new user flow appears in the **User flows** list. If necessary, refresh the page.
172
+
173
+
To enable self-service password reset, use the steps in [Enable self-service password reset](https://learn.microsoft.com/entra/external-id/customers/how-to-enable-password-reset-customers) article.
174
+
175
+
## Associate the web application with the user flow
176
+
177
+
Although many applications can be associated with your user flow, a single application can only be associated with one user flow. A user flow allows configuration of the user experience for specific applications. For example, you can configure a user flow that requires users to sign-in or sign-up with a phone number or email address.
178
+
179
+
1. On the sidebar menu, select **Identity**.
180
+
1. Select **External Identities**, then **User flows**.
181
+
1. In the **User flows** page, select the **User flow name** you created earlier, for example, _SignInSignUpSample_.
182
+
1. Under **Use**, select **Applications**.
183
+
1. Select **Add application**.
184
+
<!--[Screenshot the shows how to associate an application to a user flow.](media/20-create-user-flow-add-application.png)-->
185
+
1. Select the application from the list such as *ciam-client-app* or use the search box to find the application, and then select it.
0 commit comments