Skip to content

Commit 77a05af

Browse files
itechedititechedit
authored
Merge pull request #74002 from DennisLee-DennisLee/v-dele-1479690-4
1475459/1479690: Refresh App Management how-to sections
2 parents ce6b443 + 0e39217 commit 77a05af

File tree

10 files changed

+163
-121
lines changed

10 files changed

+163
-121
lines changed

‎articles/active-directory/manage-apps/application-proxy-configure-custom-home-page.md

+98-65
Original file line numberDiff line numberDiff line change
@@ -12,135 +12,168 @@ ms.workload: identity
1212
ms.tgt_pltfrm: na
1313
ms.devlang: na
1414
ms.topic: conceptual
15-
ms.date: 09/08/2017
15+
ms.date: 04/17/2019
1616
ms.author: celested
1717
ms.reviewer: harshja
1818
ms.custom: it-pro
1919
ms.collection: M365-identity-device-management
2020
---
2121
# Set a custom home page for published apps by using Azure AD Application Proxy
2222

23-
This article discusses how to configure apps to direct users to a custom home page. When you publish an application with Application Proxy, you set an internal URL but sometimes that's not the page your users should see first. Set a custom home page so that your users go to the right page when they access the apps. Your users will see the custom home page that you set, whether they access the app from the Azure Active Directory Access Panel or the Office 365 app launcher.
23+
This article discusses how to configure an app to direct a user to a custom home page, which may differ depending on whether they are internal or external. When you publish an app with Application Proxy, you set an internal URL, but sometimes that's not the page a user should see first. Set a custom home page so that a user gets the right page when they access the app. A user will see the custom home page that you set, regardless of whether they access the app from the Azure Active Directory Access Panel or the Office 365 app launcher.
2424

25-
When users launch the app, they're directed by default to the root domain URL for the published app. The landing page is typically set as the home page URL. Use the Azure AD PowerShell module to define custom home page URLs when you want app users to land on a specific page within the app.
25+
When a user launches the app, they're directed by default to the root domain URL for the published app. The landing page is typically set as the home page URL. Use the Azure AD PowerShell module to define a custom home page URL when you want an app user to land on a specific page within the app.
2626

27-
Here's one example of why a company would set a custom home page:
28-
- Inside your corporate network, users go to `https://ExpenseApp/login/login.aspx` to sign in and access your app.
29-
- Because you have other assets like images that Application Proxy needs to access at the top level of the folder structure, you publish the app with `https://ExpenseApp` as the internal URL.
30-
- The default external URL is `https://ExpenseApp-contoso.msappproxy.net`, which doesn't take your users to the sign-in page.
31-
- Set `https://ExpenseApp-contoso.msappproxy.net/login/login.aspx` as the home page URL.
27+
Here's one scenario that explains why your company would set a custom home page, and why it would be different depending on the type of user:
28+
29+
- Because you have other assets (such as images) that Application Proxy needs to access at the top level of the folder structure, you publish the app with `https://ExpenseApp` as the internal URL.
30+
- However, inside your corporate network, a user goes to `https://ExpenseApp/login/login.aspx` to sign in and access your app.
31+
- The default external URL is `https://ExpenseApp-contoso.msappproxy.net`, which doesn't take an external user to the sign-in page.
32+
- You want to set `https://ExpenseApp-contoso.msappproxy.net/login/login.aspx` as the external home page URL instead, so an external user sees the sign-in page first.
3233

3334
>[!NOTE]
34-
>When you give users access to published apps, the apps are displayed in the [Azure AD Access Panel](../user-help/active-directory-saas-access-panel-introduction.md) and the [Office 365 app launcher](https://blogs.office.com/2016/09/27/introducing-the-new-office-365-app-launcher).
35+
>When you give users access to published apps, the apps are displayed in the [Azure AD Access Panel](../user-help/my-apps-portal-end-user-access.md) and the [Office 365 app launcher](https://www.microsoft.com/microsoft-365/blog/2016/09/27/introducing-the-new-office-365-app-launcher/).
3536
3637
## Before you start
3738

3839
Before you set the home page URL, keep in mind the following requirements:
3940

40-
* Ensure that the path you specify is a subdomain path of the root domain URL.
41+
- The path that you specify must be a subdomain path of the root domain URL.
4142

42-
If the root-domain URL is, for example, https://apps.contoso.com/app1/, the home page URL that you configure must start with https://apps.contoso.com/app1/.
43+
For example, if the root-domain URL is `https://apps.contoso.com/app1/`, the home page URL that you configure must start with `https://apps.contoso.com/app1/`.
4344

44-
* If you make a change to the published app, the change might reset the value of the home page URL. When you update the app in the future, you should recheck and, if necessary, update the home page URL.
45+
- If you make a change to the published app, the change might reset the value of the home page URL. When you update the app in the future, you should recheck and, if necessary, update the home page URL.
4546

46-
## Change the home page in the Azure portal
47+
You can change the external or internal home page either through the Azure portal or by using PowerShell.
4748

48-
1. Sign in to the [Azure portal](https://portal.azure.com) as an administrator.
49-
2. Navigate to **Azure Active Directory** > **App registrations** and choose your application from the list.
50-
3. Select **Properties** from the settings.
51-
4. Update the **Home page URL** field with your new path.
49+
## Change the home page in the Azure portal
5250

53-
![Provide new home page URL](./media/application-proxy-configure-custom-home-page/homepage.png)
51+
To change the external and internal home pages of your app through the Azure AD portal, follow these steps:
5452

55-
5. Select **Save**
53+
1. Sign in to the [Azure Active Directory portal](https://aad.portal.azure.com/). The dashboard of the Azure Active Directory admin center appears.
54+
2. In the sidebar, select **Azure Active Directory**. The Azure AD overview page appears.
55+
3. In the overview sidebar, select **App registrations**. The list of registered apps appears.
56+
4. Choose your app from the list. A page showing the details of the registered app appears.
57+
5. Select the link under **Redirect URIs**, which displays the number of redirect URIs for web and public client types. The authentication page for the registered app appears.
58+
6. In the last row of the **Redirect URIs** table, set the **TYPE** column to **Public client (mobile & desktop)**, and in the **REDIRECT URI** column, type the internal URL you want to use. A new empty row appears below the row you just modified.
59+
7. In the new row, set the **TYPE** column to **Web**, and in the **REDIRECT URI** column, type the external URL you want to use.
60+
8. If you want to delete any existing redirect URI rows, select the **Delete** icon (a garbage can) next to each undesired row.
61+
9. Select **Save**.
5662

5763
## Change the home page with PowerShell
5864

65+
To configure the home page of an app using PowerShell, you need to:
66+
67+
1. Install the Azure AD PowerShell module.
68+
2. Find the ObjectId value of the app.
69+
3. Update the app's home page URL using PowerShell commands.
70+
5971
### Install the Azure AD PowerShell module
6072

61-
Before you define a custom home page URL by using PowerShell, install the Azure AD PowerShell module. You can download the package from the [PowerShell Gallery](https://www.powershellgallery.com/packages/AzureAD/2.0.0.131), which uses the Graph API endpoint. 
73+
Before you define a custom home page URL by using PowerShell, install the Azure AD PowerShell module. You can download the package from the [PowerShell Gallery](https://www.powershellgallery.com/packages/AzureAD/2.0.2.16), which uses the Graph API endpoint.
6274

6375
To install the package, follow these steps:
6476

6577
1. Open a standard PowerShell window, and then run the following command:
6678

67-
```powershell
68-
Install-Module -Name AzureAD
69-
```
79+
```powershell
80+
Install-Module -Name AzureAD
81+
```
7082

7183
If you're running the command as a non-admin, use the `-scope currentuser` option.
72-
2. During the installation, select **Y** to install two packages from Nuget.org. Both packages are required. 
7384

74-
### Find the ObjectID of the app
85+
2. During the installation, select **Y** to install two packages from Nuget.org. Both packages are required.
86+
87+
### Find the ObjectId of the app
7588

76-
Obtain the ObjectID of the app, and then search for the app by its home page.
89+
You get the ObjectId of the app by searching for the app by its display name or home page.
7790

7891
1. In the same PowerShell window, import the Azure AD module.
7992

80-
```powershell
81-
Import-Module AzureAD
82-
```
93+
```powershell
94+
Import-Module AzureAD
95+
```
8396

8497
2. Sign in to the Azure AD module as the tenant administrator.
8598

86-
```powershell
87-
Connect-AzureAD
88-
```
99+
```powershell
100+
Connect-AzureAD
101+
```
89102

90-
3. Find the app based on its home page URL. You can find the URL in the portal by going to **Azure Active Directory** > **Enterprise applications** > **All applications**. This example uses *sharepoint-iddemo*.
103+
3. Find the app. This example uses PowerShell to find the ObjectId by searching for the app with a display name of `SharePoint`.
91104

92-
```powershell
93-
Get-AzureADApplication | Where-Object { $_.Homepage -like "sharepoint-iddemo" } | Format-List DisplayName, Homepage, ObjectID
94-
```
105+
```powershell
106+
Get-AzureADApplication | Where-Object { $_.DisplayName -eq "SharePoint" } | Format-List DisplayName, Homepage, ObjectId
107+
```
95108

96-
4. You should get a result that's similar to the one shown here. Copy the ObjectID GUID to use in the next section.
109+
You should get a result that's similar to the one shown here. Copy the ObjectId GUID to use in the next section.
97110

98-
```
99-
DisplayName : SharePoint
100-
Homepage    : https://sharepoint-iddemo.msappproxy.net/
101-
ObjectId    : 8af89bfa-eac6-40b0-8a13-c2c4e3ee22a4
102-
```
111+
```console
112+
DisplayName : SharePoint
113+
Homepage    : https://sharepoint-iddemo.msappproxy.net/
114+
ObjectId    : 8af89bfa-eac6-40b0-8a13-c2c4e3ee22a4
115+
```
116+
117+
Alternatively, you could just pull the list of all apps, search the list for the app with a specific display name or home page, and copy the app's ObjectId once the app is found.
118+
119+
```powershell
120+
Get-AzureADApplication | Format-List DisplayName, Homepage, ObjectId
121+
```
103122

104123
### Update the home page URL
105124

106-
Create the home page URL, and update your application with that value. Continue using the same PowerShell window to run these commands. Or, if you're using a new PowerShell window, sign in to the Azure AD module again using `Connect-AzureAD`.
125+
Create the home page URL, and update your app with that value. Continue using the same PowerShell window, or if you're using a new PowerShell window, sign in to the Azure AD module again using `Connect-AzureAD`. Then follow these steps:
126+
127+
1. Create a variable to hold the ObjectId value you copied in the previous section. (Replace the ObjectId value used for in this SharePoint example with your app's ObjectId value.)
128+
129+
```powershell
130+
$objguid = "8af89bfa-eac6-40b0-8a13-c2c4e3ee22a4"
131+
```
132+
133+
2. Confirm that you have the correct app by running the following command. The output should be identical to the output you saw in the previous section ([Find the ObjectId of the app](#find-the-objectid-of-the-app)).
134+
135+
```powershell
136+
Get-AzureADApplication -ObjectId $objguid | Format-List DisplayName, Homepage, ObjectId
137+
```
107138

108-
1. Confirm that you have the correct app, and replace *8af89bfa-eac6-40b0-8a13-c2c4e3ee22a4* with the ObjectID that you copied in the preceding section.
139+
3. Create a blank application object to hold the changes that you want to make.
109140

110-
```powershell
111-
Get-AzureADApplication -ObjectId 8af89bfa-eac6-40b0-8a13-c2c4e3ee22a4.
112-
```
141+
```powershell
142+
$appnew = New-Object "Microsoft.Open.AzureAD.Model.Application"
143+
```
113144

114-
Now that you've confirmed the app, you're ready to update the home page, as follows.
145+
4. Set the home page URL to the value that you want. The value must be a subdomain path of the published app. For example, if you change the home page URL from `https://sharepoint-iddemo.msappproxy.net/` to `https://sharepoint-iddemo.msappproxy.net/hybrid/`, app users go directly to the custom home page.
115146

116-
2. Create a blank application object to hold the changes that you want to make. This variable holds the values that you want to update. Nothing is created in this step.
147+
```powershell
148+
$homepage = "https://sharepoint-iddemo.msappproxy.net/hybrid/"
149+
```
117150

118-
```powershell
119-
$appnew = New-Object "Microsoft.Open.AzureAD.Model.Application"
120-
```
151+
5. Make the update of the home page.
121152

122-
3. Set the home page URL to the value that you want. The value must be a subdomain path of the published app. For example, if you change the home page URL from `https://sharepoint-iddemo.msappproxy.net/` to `https://sharepoint-iddemo.msappproxy.net/hybrid/`, app users go directly to the custom home page.
153+
```powershell
154+
Set-AzureADApplication -ObjectId $objguid -Homepage $homepage
155+
```
123156

124-
```powershell
125-
$homepage = "https://sharepoint-iddemo.msappproxy.net/hybrid/"
126-
```
157+
6. To confirm that the change was successful, run the following command from step 2 again.
127158

128-
4. Make the update by using the GUID (ObjectID) that you copied in "Step 1: Find the ObjectID of the app."
159+
```powershell
160+
Get-AzureADApplication -ObjectId $objguid | Format-List DisplayName, Homepage, ObjectId
161+
```
129162

130-
```powershell
131-
Set-AzureADApplication -ObjectId 8af89bfa-eac6-40b0-8a13-c2c4e3ee22a4 -Homepage $homepage
132-
```
163+
For our example, the output should now appear as follows:
133164

134-
5. To confirm that the change was successful, restart the app.
165+
```console
166+
DisplayName : SharePoint
167+
Homepage    : https://sharepoint-iddemo.msappproxy.net/hybrid/
168+
ObjectId    : 8af89bfa-eac6-40b0-8a13-c2c4e3ee22a4
169+
```
135170

136-
```powershell
137-
Get-AzureADApplication -ObjectId 8af89bfa-eac6-40b0-8a13-c2c4e3ee22a4
138-
```
171+
7. Restart the app to confirm that the home page appears as the first screen, as expected.
139172

140173
>[!NOTE]
141174
>Any changes that you make to the app might reset the home page URL. If your home page URL resets, repeat the steps in this section to set it back.
142175
143176
## Next steps
144177

145178
- [Enable remote access to SharePoint with Azure AD Application Proxy](application-proxy-integrate-with-sharepoint-server.md)
146-
- [Enable Application Proxy in the Azure portal](application-proxy-add-on-premises-application.md)
179+
- [Tutorial: Add an on-premises application for remote access through Application Proxy in Azure Active Directory](application-proxy-add-on-premises-application.md)

0 commit comments

Comments
 (0)