> For the complete documentation index, see [llms.txt](https://incident-tracker.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://incident-tracker.gitbook.io/docs/admin-guide/application-information/mobile-app-settings.md).

# Mobile App Settings

**Admin Setup, PIN Distribution, and Microsoft SSO (Azure) Configuration**

This guide explains how to:

1. Enable the Incident Tracker Mobile app
2. Generate and distribute the required 4-digit activation PIN
3. Configure Microsoft SSO in Azure (if applicable)

***

#### Overview

Before users can sign in to the mobile app, they must:

1. Enter your site's **4-digit PIN**
2. Sign in using your configured authentication method:
   * Standalone (email/password)
   * Microsoft SSO
   * Google SSO

If your site uses **Microsoft SSO**, additional Azure configuration is required for mobile support.

***

#### Part 1 — Enable the Mobile App & Generate the PIN

**Step 1: Enable the Mobile App**

1. Sign in to your Incident Tracker site as an **Admin**
2. Navigate to:\
   **Admin → App Settings**
3. Locate **Incident Tracker Mobile**
4. Ensure the app is **Enabled**

***

**Step 2: Locate or Change the 4-Digit PIN**

Within **Admin → App Settings**, you will see a **4-digit PIN**.

* This PIN is required for all users the first time they log in to the app.
* You may change this PIN at any time.

If you change the PIN:

* Users must be informed of the new PIN
* Previously logged in users may need to re-enter the PIN depending on configuration

<details>

<summary>More About the 4-Digit PIN</summary>

The 4-digit PIN is not a security credential. It simply tells the mobile app which Incident Tracker site to connect to. After entering the PIN, users must still authenticate normally (email/password, Microsoft SSO, or Google SSO). All security enforcement occurs during the login process — not through the PIN.

If a user has access to multiple sites, they can log out, enter a different site's PIN, and sign in to that site.

</details>

***

#### Part 2 — End User Activation Flow

Provide the following instructions to your users:

1. Download **Incident Tracker Mobile** from the App Store or Google Play
2. Open the app
3. Enter the **4-digit PIN** provided by your Admin
4. Sign in using your organization's configured method:
   * Standalone account
   * Microsoft SSO
   * Google SSO

***

#### Part 3 — Microsoft SSO Configuration (Azure)

{% hint style="info" %}
Only required if your Incident Tracker site uses Microsoft SSO.
{% endhint %}

**Important: Enterprise Application vs. App Registration**

When Microsoft SSO was initially configured, Azure created:

* An **Enterprise Application** — used for user assignment and access control
* An **App Registration** — used for authentication settings like Redirect URIs and API permissions

They typically share the same name but are separate objects.

{% hint style="warning" %}
Redirect URIs and API permissions must be added to the **App Registration** — not the Enterprise Application.
{% endhint %}

**Step 1: Open the Correct App Registration**

1. Go to the [Azure Portal](https://portal.azure.com)
2. Navigate to:\
   **Microsoft Entra ID → App registrations**
3. Search for your Incident Tracker SSO app name
4. Open the **App Registration** (not the Enterprise Application)

***

**Step 2: Add Required API Permissions**

The mobile app requires the following **Delegated** Microsoft Graph permissions to authenticate users via SSO:

1. In the App Registration, select **API permissions**
2. Click **Add a permission → Microsoft Graph → Delegated permissions**
3. Add each of the following permissions:
   * **email** — Allows the app to read the user's email address
   * **offline\_access** — Allows the app to maintain access and refresh tokens so users don't have to re-authenticate every session
   * **openid** — Required for OpenID Connect sign-in
   * **profile** — Allows the app to read the user's basic profile (name, etc.)
4. After adding all four, click **Grant admin consent for \[your tenant]**
5. Confirm that each permission shows a green checkmark under **Status** indicating consent has been granted

{% hint style="warning" %}
**Admin consent must be granted before users sign in.** Adding permissions to the App Registration tells Microsoft what the mobile app is allowed to request — but it does not automatically consent to those permissions for the tenant. Clicking **Grant admin consent** writes the actual consent to the Enterprise Application's service principal, which is what Microsoft checks at sign-in time. If this step is skipped, non-admin users will hit an "approval required" screen or a sign-in loop because the mobile app cannot handle the consent-required error gracefully.
{% endhint %}

***

**Step 3: Add the Mobile Redirect URI**

1. In **Authentication**, click **Add a platform**
2. Select **Mobile and desktop applications**
3. Add the following Redirect URI exactly as shown:\
   `com.mckula.incidenttracker.mobile://oauth2redirect/microsoft`
4. Click **Configure** to save

***

**Step 4: Confirm and Test**

1. Under **API permissions**, confirm all four delegated permissions are listed with admin consent granted:
   * `email`
   * `offline_access`
   * `openid`
   * `profile`
2. Under **Authentication**, confirm the Redirect URI is present:
   * `com.mckula.incidenttracker.mobile://oauth2redirect/microsoft`
3. Allow a minute for Azure to propagate the changes
4. Test sign-in on both an iOS and an Android device

{% hint style="info" %}
**Verifying Admin Consent**

After clicking **Grant admin consent** in Step 2, you can verify it took effect by checking **Enterprise Applications → \[Your App] → Permissions**. The same four permissions (`email`, `offline_access`, `openid`, `profile`) should appear there with a granted status. Both portal locations — App Registration → API permissions and Enterprise Application → Permissions — are paths to the same tenant-wide consent. The App Registration is where you configure what the app requests; the Enterprise Application represents the app's instance in the tenant and is where consent is actually stored.
{% endhint %}

{% hint style="warning" %}
**User Assignment**

Tenant-wide admin consent does not necessarily mean every user can access the app. If some users still cannot sign in after consent is granted, check **Enterprise Applications → \[Your App] → Properties** and look at the **Assignment required** setting. If enabled, only users or groups explicitly assigned to the app will be allowed to sign in.
{% endhint %}

{% hint style="info" %}
**Troubleshooting: App Registration vs. Enterprise Application**

All configuration in this guide (API permissions, Redirect URIs) is done in the **App Registration**. The Enterprise Application is where consent is stored and where user assignment is managed. They share the same name but are separate objects in Azure. If sign-in fails after completing these steps, confirm you are looking at the correct object for the task — App Registration for configuration, Enterprise Application for consent verification and user assignment.
{% endhint %}