-
Notifications
You must be signed in to change notification settings - Fork 0
/
documentation.html
239 lines (223 loc) · 16.9 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
<!DOCTYPE html>
<head>
<title>App Proxy Configuration Discovery Documentation</title>
<!-- Meta -->
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="">
<!-- Global CSS -->
<link rel="stylesheet" href="./lib/css/fontMod.css">
<link rel="stylesheet" href="./lib/fontawesome/css/all.css">
<link rel="stylesheet" href="./lib/css/bootstrap.min.css">
<link rel="stylesheet" href="./lib/css/prettyDocs.css">
<link rel="stylesheet" href="./lib/css/style.css">
<link rel="shortcut icon" type="image/x-icon" href="./lib/favicon.ico"/>
</head>
<body class="body-blue">
<div class="page-wrapper">
<header class="navbar navbar-expand navbar-dark flex-column flex-md-row bd-navbar">
<a class="navbar-brand mr-0 mr-md-2" href="#">
<img class="logoImage" src="./lib/images/microsoftLogo.png"/>
</a>
<div class="pageTitle">
<h4>
<a href="./index.html">App Proxy Configuration Discovery</a>
</h4>
</div>
<h5 class="documentationLink">
<a href="./documentation.html">Documentation</a>
</h5>
<h5 class="feedbackLink">
<a href="https://forms.office.com/Pages/ResponsePage.aspx?id=ehnzVdPTZEKnaxb1WZflTZrlubplpatCmNgccZPmy-1UOEYzNlZCV0dVMFJJQTgwMkk0NlFORUUxVC4u" target="_blank">Leave feedback!</a>
</h5>
</header>
<div class="doc-wrapper">
<div class="container">
<div id="doc-header" class="doc-header text-center">
<h1 class="doc-title"><i class="icon fa fa-paper-plane"></i> Documentation</h1>
<div class="meta"><i class="fa fa-clock-o"></i> Last updated: August 8, 2018</div>
</div><!--//doc-header-->
<div class="doc-body">
<div class="doc-content">
<div class="content-inner">
<section id="download-section" class="doc-section">
<h2 class="section-title">Quick Summary</h2>
<div class="section-block">
<h3 class="block-title">Background</h3>
<p>
Azure AD Application Proxy provides remote access as a service which enables customer to provide their users a cloud experience for their on-premise applications, while leveraging the security of Azure AD.
</p>
<p>
This tool seeks to automate the configuration discovery and diagnosis of potential App Proxy configuration mistakes / requirements necessary to publish on-premise web applications to Azure AD via App Proxy.
</p>
<p>
The input to this tool can vary, but is most likely just the name of your Azure AD connector machine.
The output is either a generated html view containing the configuration analysis or a raw json blob that can be consumed manually.
</p>
</div>
<div class="section-block">
<h3 class="block-title">Intended Audience</h3>
<p>
This tool is intended to be used by those seeking to publish on-premise apps to Azure AD via App Proxy. There is a strong focus on aiding those with Windows Integrated Authentication apps who seek to enable SSO via Kerberos Constrained Delegation (KCD).
</p>
<p>
This tool will be less useful for those seeking to publish claims based / anonymous authentication apps due to the configuration possibilities.
</p>
<p>
The best way to conceptualize this tool is to think of it as a sanity check, helping to find the most common configuration errors. By no means is this tool a one stop fix all.
</p>
</div>
<div class="row">
<div class="col">
<div class="section-block">
<h3 class="block-title">What this offers</h3>
<ul class="list">
<li>Configuration discovery for IIS servers</li>
<li>Connector configuration discovery</li>
<li>Configuration analysis in context of App Proxy</li>
<li>Remediation tips / links</li>
<li>Auto generation of publication scripts for ready sites / apps</li>
</ul>
</div>
</div>
<div class="col">
<div class="section-block">
<h3 class="block-title">Requirements</h3>
<ul class="list">
<li>Admin permissions to IIS Server</li>
<li>IIS server 2008+</li>
<li>PowerShell v4</li>
<li>IE / Edge / Chrome</li>
<li>Internet connection is only needed if the server name hosting the connector service is passed AND the Windows Feature RSAT-AD has not been installed OR if using the auto publish feature in which case you must connect to Azure AD</li>
</ul>
</div>
</div>
</div>
<a href="https://youtu.be/xAMEaitzhpU"> <h3 class="block-title">View the Demo here!</h3></a>
</section><!--//doc-section-->
<section id="howitworks-section" class="doc-section">
<h2 class="section-title">How it Works</h2>
<div class="section-block">
<p>
When the PowerShell script is first executed it will query the relevant configuration data, parsing and building a configuration object along the way.
</p>
<p>
It will then convert this to JSON and inject this json into a js file that will be located in the data directory. When the index.html is opened another js file will parse the json, perform an analysis, then dynamically render the view.
</p>
<p>
From here the generated GUI can be used to find misconfigured settings, then offer assistance on how these settings can be modified such that the application can be published.
</p>
<p>
After modifying the settings such that there are no errors, one can generate a publication script for either just an individual nested application, or the entire site. This can be done by selecting an app in the right side column, or by selecting the site in the right side column.
</p>
</div>
</section><!--//doc-section-->
<section id="installation-section" class="doc-section">
<h2 class="section-title">How to Use</h2>
<div id="step1" class="section-block">
<p>Download the tool or clone the <a href="https://github.com/Avsphere/appProxy" target="_blank"> repository</a>
</p>
<a href="https://github.com/Avsphere/appProxy/archive/master.zip" class="btn btn-green" target="_blank"><i class="fa fa-download"></i> Download Tool</a>
<br/>
<br/>
<p>
Move the tool to your IIS server, open up PowerShell with admin permissions. Navigate to the tool root directory where the .ps1 lives and execute one of the following:
</p>
<div class="code-block">
<h6>If you have already setup your connector, you can pass the servers name:</h6>
<p><code>configurationDiscovery -connectorName "[connector server name here]"</code></p>
<h6>If you have NOT setup your connector:</h6>
<p><code>configurationDiscovery</code></p>
<h6>If you would just like the JSON output:</h6>
<p><code>configurationDiscovery -onlyJson "true"</code></p>
<h6>If you would just like to point to the root directory</h6>
<p><code>configurationDiscovery -dirPath "[path to source]"</code></p>
</div><!--//code-block-->
<div class="code-block">
<h6>If you see an error regarding execution policy you may need to run:</h6>
<code>Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass</code>
</div>
<p>
**Note that currently you can only pass a single connector name. This will attempt to install the Windows feature "RSAT-AD-PowerShell" if it is not installed already. It must do this so that it can query the connectors delegation configuration.
</p>
<p>
Now open the index.html file in edge or chrome to interact with the analysis GUI. The parsed configuration data is stored in the data/ directory.
</p>
</div><!--//section-block-->
<div id="step3" class="section-block">
<h3 class="block-title">Interacting with the GUI</h3>
<p>
There are really only 3 main activities you can preform when interacting with the index.html GUI:
</p>
<ul class="list">
<li>Clicking a site to view a list summary of the checked configuration</li>
<li>Clicking a list item in the summary group to view detailed information and tips on how to remediate</li>
<li>Clicking the "Generate Publication Scripts" button to head over to the bulk automated publication feature of this tool</li>
</ul>
<div class="section-block">
<h6>#index.html - Summary View</h6>
<img class="img-fluid" src="lib/images/summaryView.png" alt="elegant icons">
</div>
<p>
The purpose of this is to show a quick summary of the analysis. Each list item details a specific check performed by the analysis. Clicking one of these items opens up a modal with detailed information.
</p>
<div class="section-block">
<h6>#index.html - Detailed View</h6>
<img class="img-fluid" src="lib/images/siteOrAppDetails.png" alt="elegant icons">
</div>
<p>
The purpose of this is to show more details about the clicked site or app but also possible solutions to help fix failed tips.
</p>
</div><!--//section-block-->
</section><!--//doc-section-->
<section id="installation-section" class="doc-section">
<h2 class="section-title">Technical Details</h2>
<div id="step31" class="section-block">
<h3 class="block-title">Directory Summaries</h3>
<p>
Here is a quick summary on the function of each directory
</p>
<ul class="list">
<li>src/ - These are the main js scripts that are used to run the analysis, and control the views. They are transpiled with babel into main.js which is the stored in the dist directory</li>
<li>dist/ - This directory contains a polyfill script for IE support, along with the transpiled scr/* directory</li>
<li>lib/ - All resources are stored in this directory</li>
</ul>
</div><!--//section-block-->
<div id="step2" class="section-block">
<h3 class="block-title">File Summaries</h3>
<p>
This is more indepth summary of the scripts found in the src/ directory
</p>
<ul class="list">
<li>autoPublish.js - Controls the autoPub.html view. It includes the functions for building this view and for generating the PowerShell script used to auto publish the selected apps</li>
<li>configApi.js - A helper script that is intended to help abstract away some of the work in the analysis scripts. Currently there is just an iis analysis so this script serves a limited purpose</li>
<li>headless.js - Controls the headless.html view. It allows the user to upload the json where it then processes the data identically to if the user had instead went the normal route of letting the PowerShell script inject the data</li>
<li>iisAnalysis.js - Runs the analysis by performing a series of rule based checks depending on the received configuration data.</li>
<li>
main.js - The top level script that decides which set of controls should be used based on the url.
</li>
<li>
viewBuilder.js - Controls all of the rendering of html for most of the views.
</li>
</ul>
</div>
<div id="step3" class="section-block">
<h3 class="block-title">What's Next</h3>
<p>
This tool is currently going through testing in the wild in order to discover unknown bugs and find areas of improvement.
</p>
</div><!--//section-block-->
</section><!--//doc-section-->
</div><!--//content-inner-->
</div><!--//doc-content-->
</div><!--//doc-body-->
</div><!--//container-->
</div><!--//doc-wrapper-->
</div><!--//page-wrapper-->
<!-- Main Javascript -->
<script src="./lib/js/jquery.min.js"></script>
<script src="./lib/js/bootstrap.min.js"></script>
</body>
</html>