Skip to content

Commit c8a1df0

Browse files
elliot-huffmanelliot-huffman
authored
Merge pull request #44 from Software-Hardware-Integration-Lab/susdocs
Initial SHI - URL Shortener documentation. More to come!
2 parents 5d80cdb + 6ebd08e commit c8a1df0

File tree

15 files changed

+255
-16
lines changed

15 files changed

+255
-16
lines changed

‎docs/URL-Shortener/Getting-Started.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Getting Started
2+
3+
This page outlines how to deploy SUS.
4+
5+
## Steps
6+
7+
Coming soon!

‎docs/URL-Shortener/Prerequisites/Authorization-&-RBAC.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Authorization & RBAC
2+
3+
The service expects upstream authentication (e.g., bearer token from Entra ID). These permissions are app roles defined on the ```End User Login``` app registration.
4+
5+
Elevated (Privileged) User Permissions:
6+
7+
| Scope Value | Description |
8+
|-------------------------|-------------|
9+
| Everything.ReadWrite.All | Grants the principal the ability to read and write everything in SUS. This role is designed for moderation of all links created by all users as by default only the creating user has access to the link. This role can also be used as break glass access. This is a highly privileged role and should not be used normally. Please use the fine-grained roles where possible. |
10+
| Redirect.ReadWrite.All | Create, read, update and delete all URL redirects. Bypasses any RBAC and lets you see everything (no constraints). Do not use this for general access, please use the built-in RBAC. This is meant for automation and privileged admin/access. |
11+
| Domain.ReadWrite.All | Create, read, update and delete items from the list of domains allowed to be used for vanity URLs. Bypasses any RBAC and lets you see everything (no constraints). Do not use this for general access, please use the built-in RBAC. This is meant for automation and privileged admin/access. |
12+
| BanList.ReadWrite.All | Create, read, update and delete items on the banned term list. Bypasses any RBAC and lets you see everything (no constraints). Do not use this for general access, please use the built-in RBAC. This is meant for automation and privileged admin/access. |
13+
| Rbac.ReadWrite.All | Create, read, update and delete RBAC Assignments. Bypasses any RBAC and lets you see everything (no constraints). Do not use this for general access, please use the built-in RBAC. This is meant for automation and privileged admin/access. |
14+
15+
RBAC assignments are available to allow dynamic delegation without full superuser elevation.

‎docs/URL-Shortener/Prerequisites/Graph-API-Permissions.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Required Permissions
2+
3+
The application is broken up into two parts, the server and the end user experience. The server has permissions granted to it so that it can validate the incoming data. The end user experience has permissions so that the end user is able to provide IDs to the server for user and group assignments.
4+
5+
## Server - Service Principal
6+
7+
The following Entra ID Service Principal permissions are required to run the service. These are mandatory at all times.
8+
9+
| Graph API Permission| Permission Type |Description |
10+
|--------------------------------------------------------------------------------------|-----------------|-----------------------------------------------------------------------------|
11+
| [`Group.Read.All`](https://learn.microsoft.com/en-us/graph/permissions-reference#groupreadall){:target="_blank"} | Application | Used to validate group Object IDs provided as part of an RBAC assignment. |
12+
| [`User.Read.All`](https://learn.microsoft.com/en-us/graph/permissions-reference#userreadall){:target="_blank"} | Application | Used to retrieve user's transitive group membership list for RBAC assignment validation. |
13+
14+
## End User Auth - Service Principal
15+
16+
| Graph API Permission | Permission Type | Description |
17+
|--------------------------------------------------------------------------------------|-----------------|-----------------------------------------------------------------------------|
18+
| [`profile`](https://learn.microsoft.com/en-us/graph/permissions-reference#profile){:target="_blank"} | Delegated | Used to authenticate the end user. |
19+
| [`User.Read.All`](https://learn.microsoft.com/en-us/graph/permissions-reference#userreadall){:target="_blank"} | Delegated | Used to authenticate the end user and retrieve their profile picture. |
20+
| [`Group.Read.All`](https://learn.microsoft.com/en-us/graph/permissions-reference#groupreadall){:target="_blank"} | Delegated | Used to retrieve the list of groups that can be assigned in an RBAC assignment. |

‎docs/URL-Shortener/Prerequisites/index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## System Requirements
2+
3+
### Hosting Environment
4+
5+
- **Platform**: Azure App Service
6+
- **Runtime**: Node.js 22 LTS (or latest stable version)
7+
- **Deployment Mode**: Code deploy mode
8+
- **Identity Configuration**:
9+
- **System-assigned Managed Identity**: Must be enabled
10+
- This identity will be used to authenticate against Microsoft Graph API for identity-aware redirection and access control.
11+
12+
---
13+
14+
The application is broken up into two parts, the server and the end user experience. The server has permissions granted to it so that it can validate the incoming data. The end user experience has permissions so that the end user is able to provide IDs to the server for user and group assignments.

‎docs/URL-Shortener/Reference/Development/OpenAPI.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# OpenAPI Specification
2+
3+
The SUS service is documented using the OpenAPI version 3 specification format. This ensures seamless integration with automation tools, SDK generators, and client libraries.
4+
5+
All concrete route definitions, schemas, and status codes are maintained in the OpenAPI spec, which serves as the authoritative source for the HTTP surface.
6+
7+
Spec Location:
8+
<https://specs.shilab.com/>
9+
Please reach out to the SHI Lab team for guidance on best practices, integration support, and usage recommendations.

‎docs/URL-Shortener/Reference/Development/Server-Setup.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
This section describes setting up a production instance of the URL redirect server.
2+
3+
Deploy the bicep template (urlShortener.bicep) found in the ./infrastructureTemplates folder. To deploy the template, you will need the Entra ID Cloud Application Administrator role or higher.
4+
5+
How to deploy bicep templates:
6+
```https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deploy-powershell```
7+
8+
If you want to set this up on-prem or in a different environment, please refer to the configurations in the bicep template for infra specific configurations. If you wish to not authenticate with a managed identity, please see here for alternate authentication configurations:
9+
```https://www.npmjs.com/package/@azure/identity#environment-variables```

‎docs/URL-Shortener/Reference/Settings/Environment-Variables-Reference.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Environmental Variable Reference
2+
3+
Environmental variables are used to configure core behaviors/configurations of the server software.
4+
5+
The configurations are exposed as environmental variables rather than config files or registry keys to provide maximum support for wherever the server is hosted.
6+
Config files don't work well in serverless environments where the state should not change, and the registry is only available on Windows.
7+
Serverless, Windows, and Linux all share a common option: Environmental Variables. This works equally well across all of them.
8+
9+
Below is a list of all environmental variable configurations that the server can use. There are data format examples and descriptions so that you are not going blind to what a config can look like and does.
10+
11+
The title of the section is the name of the environmental variable.
12+
13+
For authentication configuration, please see here for more environmental variables that are supported by SUS via the Microsoft Authentication Library for Node.JS [@azure/identity](https://www.npmjs.com/package/@azure/identity#environment-variables){:target="_blank"}.
14+
15+
---
16+
17+
## `SUS_TenantId`
18+
19+
- Mandatory: `true`
20+
- Expected string format: GUID
21+
- Allowed values: GUID
22+
- Default Value: `00000000-0000-0000-0000-000000000000`
23+
- Description: Tenant ID of the tenant that the app considers home/authenticates to. Defaults to NULL if not defined and should be overridden during authentication engine start.
24+
25+
## `SUS_DB_Host`
26+
27+
- Mandatory: `false`
28+
- Expected string format: string
29+
- Allowed values: string
30+
- Default Value: `localhost`
31+
- Description: Host name of the Azure SQL DB that should be used for storing simple data.
32+
33+
## `SUS_DB_Name`
34+
35+
- Mandatory: `false`
36+
- Expected string format: string
37+
- Allowed values: string
38+
- Default Value: `UrlShortener`
39+
- Description: Name of the DB to access and use for relational data storage. This is necessary for Azure SQL DBs as the DB has to be created ahead of time and shouldn't be created inline as a best practice.
40+
41+
## `SUS_Debug`
42+
43+
- Mandatory: `false`
44+
- Expected string format: boolean
45+
- Allowed values: true
46+
- Default Value: `false`
47+
- Description: Flag that indicates if the API service should be in debug mode.
48+
49+
## `SUS_Headless`
50+
51+
- Mandatory: `false`
52+
- Expected string format: boolean
53+
- Allowed values: true
54+
- Default Value: `false`
55+
- Description: Flag that indicates the system should run with no user interface render.
56+
57+
## `SUS_LocalDb`
58+
59+
- Mandatory: `false`
60+
- Expected string format: boolean
61+
- Allowed values: true
62+
- Default Value: `false`
63+
- Description: Flag that indicates the SQLite should be used for the ORM. All other functions are untouched.
64+
65+
## `SUS_Local`
66+
67+
- Mandatory: `false`
68+
- Expected string format: boolean
69+
- Allowed values: true
70+
- Default Value: `false`
71+
- Description: Flag that controls if the server should run with local resources only. This uses SQLite and prevents external resource calls allowing for a true local only execution experience.
72+
73+
## `SUS_DefaultTarget`
74+
75+
- Mandatory: `false`
76+
- Expected string format: URL
77+
- Allowed values: URL
78+
- Default Value: `https://shi.com`
79+
- Description: Location that the service will redirect to if a match is not found.
80+
81+
## `SUS_AuthAudience`
82+
83+
- Mandatory: `true`
84+
- Expected string format: GUID
85+
- Allowed values: GUID
86+
- Default Value: `00000000-0000-0000-0000-000000000000`
87+
- Description: Application ID of the app registration to use as the audience value in the access token validation. Not mandatory if in debug mode as auth is not enforced in debug mode.
88+
89+
## `SUS_Test`
90+
91+
- Mandatory: `false`
92+
- Expected string format: boolean
93+
- Allowed values: true
94+
- Default Value: `false`
95+
- Description: Flag that indicates if the application should have special behavior based on if the system is running through automated QA.

‎docs/URL-Shortener/Usage-Guide.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Usage Guide
2+
3+
This guide explains how to operate SUS once it's been deployed. It covers core Redirect URL creation, RBAC Assignments, Domain Configuration, Banned Terms, and links to detailed task-level workflows.

‎docs/URL-Shortener/index.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# URL Shortener
2+
3+
## Overview
4+
5+
The **SHI - URL Shortener (SUS)** is a security-focused, privacy respecting, compliance-ready URL redirection service. SUS provides controlled creation and management of short URLs, delegated administration through RBAC, strong input validation, and guardrails to prevent misuse (e.g., banned terms, domain scoping).
6+
7+
## Audience
8+
9+
This documentation is primarily intended for technical users who are responsible for deploying, configuring, and maintaining the URL Shortener service within customer environments. While the content is geared toward technical implementation, it is written to be accessible to non-technical stakeholders as well.
10+
11+
## SUS in the Security Landscape
12+
13+
- Zero trust: Every request re‑validated (types, UUID formats, filter shapes).
14+
- Strong runtime validation: Uses structural equality/type guards to reject malformed inputs early (400).
15+
- Principle of least privilege: Distinct scopes required for privileged sets (e.g., domain & ban list modifications).
16+
- Protective lists: Banned terms and controlled domains for fine grained control over what is created by end users.
17+
- Separation of concerns: Routing layer delegates business logic to a Redirect Engine singleton.
18+
- Minimal disclosure: Nonexistent management records yield 404 without leaking broader state.
19+
- Auditable mutation points: Create/Update/Delete paths are centralized for logging.
20+
21+
## Prerequisites
22+
23+
Check out this page for more details: [Getting Started - Prerequisites](Prerequisites/index.md)
24+
25+
## Summary
26+
27+
In the rest of the documentation, we will provide detailed instructions on how to install, configure, and use SUS to achieve these benefits.

‎docs/assets/Styles/common.css‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,16 @@
1+
.susIcon {
2+
/* Detaches the icon from being dependant on other HTML elements for its render. */
3+
display: inline-block;
4+
/* Size of the icon to be rendered. */
5+
font-size: 1.5em;
6+
/* Prevent the line from getting larger as the icon does. */
7+
line-height: 1;
8+
/* Prevent the line from getting larger as the icon does. */
9+
height: 1em;
10+
/* Ensure that the icon renders in the center of the line, equal with the following text. */
11+
vertical-align: middle;
12+
}
13+
114
/* Light mode */
215
[data-md-color-scheme="default"] {
316
--md-default-bg-color: white;
@@ -25,4 +38,4 @@
2538
[data-md-color-scheme="slate"] .md-tooltip--active {
2639
color: black;
2740
background-color: white;
28-
}
41+
}

0 commit comments

Comments
 (0)