# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://incident-tracker.gitbook.io/docs/admin-guide/application-information/mobile-app-settings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.