Microsoft Sign in usage: Difference between revisions

From VoIPmonitor.org
(Add troubleshooting section for SSO behind reverse proxy/SSL termination)
No edit summary
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:How to Set Up Microsoft Sign-In}}
{{DISPLAYTITLE:Microsoft Sign-In (SSO) Configuration}}
[[Category:Configuration]]
[[Category:Configuration]]
[[Category:Authentication]]
[[Category:Authentication]]
{{Warning|1='''Microsoft Sign-In is NOT yet available in the stable VoIPmonitor GUI.''' This feature is scheduled for an upcoming stable release. If you do not see "Enable Microsoft Sign in" in '''Settings > System configuration > Advanced''', your version does not support this feature. Contact VoIPmonitor support to request a development branch package if needed immediately.}}


== Overview ==
== Overview ==


The Microsoft Sign-In integration allows VoIPmonitor GUI users to authenticate using their Microsoft Entra ID (formerly Azure Active Directory) accounts. This provides:
Microsoft Sign-In allows VoIPmonitor GUI users to authenticate using their Microsoft Entra ID (formerly Azure AD) accounts, providing Single Sign-On (SSO) capability.
* Single Sign-On (SSO) capability
* Centralized user management through Microsoft Entra
* Enhanced security with Microsoft's authentication infrastructure


<kroki lang="mermaid">
<kroki lang="mermaid">
Line 16: Line 11:
flowchart LR
flowchart LR
     subgraph Entra["Microsoft Entra"]
     subgraph Entra["Microsoft Entra"]
         A[Register App] --> B[Get Client ID]
         A[Register App] --> B[Get IDs]
         B --> C[Get Tenant ID]
         B --> C[Assign Users]
        C --> D[Assign Users]
     end
     end
     subgraph GUI["VoIPmonitor GUI"]
     subgraph GUI["VoIPmonitor GUI"]
         E[Enable MS Sign-In] --> F[Configure IDs]
         D[Enable MS Sign-In] --> E[Enter IDs]
         F --> G[Map Users]
         E --> F[Map Users]
     end
     end
     D --> E
     C --> D
</kroki>
</kroki>


== Part 1: Register Application in Microsoft Entra ==
=== User Mapping Order ===


This guide walks you through registering a new application in Microsoft Entra ID and configuring it for VoIPmonitor GUI integration.
When a user signs in with Microsoft, VoIPmonitor maps them to a GUI user profile in this order:


=== Step 1: Sign in to Microsoft Entra admin center ===
# '''Direct email match''' - Username in VoIPmonitor matches Microsoft email
# '''Secure users list''' - Microsoft email is listed in user's "Microsoft Sign In emails" field
# '''Default user''' - Falls back to the user marked as "Default Microsoft Sign In account"


Open a web browser and navigate to [https://entra.microsoft.com entra.microsoft.com].
== Quick Reference ==


Sign in using an account with administrative privileges.
{| class="wikitable"
|-
! Parameter !! Where to Get !! Where to Enter
|-
| '''Client ID''' || Microsoft Entra > App registration > Overview > ''Application (client) ID'' || GUI > Settings > System configuration > Advanced
|-
| '''Tenant ID''' || Microsoft Entra > App registration > Overview > ''Directory (tenant) ID'' || GUI > Settings > System configuration > Advanced
|-
| '''Redirect URI''' || Your VoIPmonitor GUI URL || Microsoft Entra > App registration > Redirect URIs
|}


=== Step 2: Navigate to App registrations ===
== Part 1: Microsoft Entra Configuration ==


In the left-hand menu, go to '''App registrations'''.
=== Register the Application ===


=== Step 3: Create new registration ===
# Go to [https://entra.microsoft.com entra.microsoft.com] > '''App registrations''' > '''+ New registration'''
# Configure:
#* '''Name:''' e.g., "VoIPmonitor SSO"
#* '''Supported account types:''' "Accounts in this organizational directory only"
#* '''Redirect URI - Platform:''' '''Single page application'''
#* '''Redirect URI - URL:''' Your VoIPmonitor GUI URL
# Click '''Register'''
# Note the '''Application (client) ID''' and '''Directory (tenant) ID''' from the Overview page


At the top of the page, click the '''+ New registration''' button.
{{Note|1='''Redirect URI format:'''
* Correct: <code>https://voipmonitor.example.com</code>
* Wrong: <code>https://voipmonitor.example.com/</code> (trailing slash)
* Wrong: <code>https://voipmonitor.example.com/admin.php</code> (page name)}}


=== Step 4: Configure Application Settings ===
=== Assign Users ===


; Name
In Microsoft Entra, go to '''Users''' and add users who should have access to VoIPmonitor via Microsoft Sign-In.
: Enter a meaningful name for your application (e.g., "VoIPmonitor SSO").


; Supported account types
== Part 2: VoIPmonitor GUI Configuration ==
: Choose who can use the application. For internal use, select ''Accounts in this organizational directory only''.


; Redirect URI - Platform
=== Enable Microsoft Sign-In ===
: Choose '''Single page application'''.


; Redirect URI - URL
# Go to '''Settings > System configuration > Advanced'''
: Enter the URL where your VoIPmonitor GUI is installed.
# Enable '''Enable Microsoft Sign in'''
# Enter:
#* '''Microsoft client ID''' - from Entra
#* '''Microsoft tenant ID''' - from Entra
#* '''Redirect URI''' - leave empty (auto-detected)


{{Note|1='''Redirect URI rules:'''
=== Map Users ===
* Do '''not''' include ''admin.php'' or ''index.php'' at the end
* Do '''not''' include a trailing slash (/) at the end}}


<syntaxhighlight lang="text">
For each user who will use Microsoft Sign-In:
# Correct format:
https://voipmonitor.yourdomain.com


# Incorrect formats:
# Go to '''Users & Audit > Users''' > edit user
https://voipmonitor.yourdomain.com/
# '''Secure users''' tab > fill '''Microsoft Sign In emails''' with their Microsoft email
https://voipmonitor.yourdomain.com/admin.php
https://voipmonitor.yourdomain.com/index.php
</syntaxhighlight>


Click the '''Register''' button to complete registration.
=== Default User (Optional) ===


=== Step 5: Note the Application IDs ===
To set a fallback user for unmapped Microsoft accounts:


After registration, you will be taken to the application's Overview page. Note the following values (you will need them for GUI configuration):
# Edit the desired user > '''Basic data''' tab
* '''Application (client) ID''' - Used as "Microsoft client ID" in VoIPmonitor
# Check '''Default Microsoft Sign In account'''
* '''Directory (tenant) ID''' - Used as "Microsoft tenant ID" in VoIPmonitor


== Part 2: Assign Users to the Application ==
== Troubleshooting ==


After registering the application, you must assign the users who will be allowed to sign in.
=== SSO Fails Behind Reverse Proxy ===


=== Step 1: Navigate to Users ===
'''Symptom:''' Redirect loops or "too many redirects" errors when using AWS ALB, Nginx, or other reverse proxies with SSL termination.


In the Microsoft Entra left-hand menu, go to '''Users'''.
'''Cause:''' The proxy terminates HTTPS but forwards HTTP to the backend, breaking the OAuth callback flow.


=== Step 2: Add Users ===
'''Solution:''' Pass the original protocol via <code>X-Forwarded-Proto</code> header:


Click '''+ Add user''' and follow the wizard to add users who should have access to VoIPmonitor through Microsoft Sign-In.
<syntaxhighlight lang="nginx">
# Nginx configuration
proxy_set_header X-Forwarded-Proto $scheme;
</syntaxhighlight>


== Part 3: VoIPmonitor GUI Configuration ==
For AWS ALB, this header is automatic but ensure intermediate proxies pass it through. See [[Nginx]] for complete configuration.


{{Note|This section requires a GUI version that supports Microsoft Sign-In (development branch or future stable release).}}
== See Also ==
 
=== Step 1: Enable Microsoft Sign-In ===


# Navigate to '''Settings > System configuration'''
* [[Google_Sign_in_usage]] - Google OAuth integration
# Scroll down to the '''Advanced''' section
* [[User_Management]] - User account management
# Enable the option '''Enable Microsoft Sign in'''
* [[WEB_API#Custom_Login|Custom Login]] - LDAP/custom authentication scripts
# Fill in the configuration fields:
#* '''Microsoft client ID''': Enter the ''Application (client) ID'' from Microsoft Entra
#* '''Microsoft tenant ID''': Enter the ''Directory (tenant) ID'' from Microsoft Entra
#* '''Redirect URI for Microsoft Sign in''': Leave empty (auto-detected). Only fill if automatic detection fails.
 
=== Step 2: Configure User Mappings ===
 
Navigate to '''Users & Audit > Users'''.
 
For each user who should use Microsoft Sign-In:
 
# Edit their user profile
# Go to the '''Secure users''' tab
# Fill in the '''Microsoft Sign In emails''' field with their Microsoft account email
 
=== Step 3: Configure Default User (Optional) ===
 
If you want to define a default user for Microsoft Sign-In (for users who are not explicitly mapped):
 
# Edit the desired default user's profile
# Go to the '''Basic data''' tab
# Check the '''Default Microsoft Sign In account''' option
 
== Troubleshooting ==
 
=== SSO Fails Behind Reverse Proxy (AWS ALB, Nginx, etc.) ===
; Problem: Microsoft Sign-In fails or causes redirect loops when the VoIPmonitor GUI is accessed through a reverse proxy (e.g., AWS Application Load Balancer) that handles SSL termination. Users may see errors like "too many redirects" or lose their session after authentication.
:* '''Cause:''' The reverse proxy terminates HTTPS and forwards requests to the backend GUI over HTTP. Without the correct headers, the GUI believes it is running on an insecure protocol and generates HTTP URLs or redirects, breaking the OAuth callback flow.
:* '''Solution:''' Configure your reverse proxy to pass the original protocol via the <code>X-Forwarded-Proto</code> header. For Nginx, add this to your proxy configuration:
<pre>
proxy_set_header  X-Forwarded-Proto $scheme;
</pre>
For AWS ALB, this header is automatically included, but ensure any intermediate proxies pass it through. Also check for any Apache <code>RewriteRule</code> directives that redirect HTTP to HTTPS and modify them to exclude internal proxy traffic. See [[Nginx]] for complete configuration details.


== AI Summary for RAG ==
== AI Summary for RAG ==


'''Summary:''' This guide documents the Microsoft Sign-In (SSO) integration for VoIPmonitor GUI, which is currently in development and not yet available in stable releases. The setup requires three main steps: (1) Register an application in Microsoft Entra (formerly Azure AD) by creating a new app registration with Single Page Application platform type, noting the Client ID and Tenant ID, and ensuring the Redirect URI matches the VoIPmonitor GUI URL exactly without trailing slashes or page names. (2) Assign users in Microsoft Entra who should have access. (3) Configure VoIPmonitor GUI by enabling Microsoft Sign-In in Settings > System configuration > Advanced, entering the Client ID and Tenant ID, and mapping VoIPmonitor users to their Microsoft email addresses in the Secure users tab. A default Microsoft Sign-In account can be configured for unmapped users.
'''Summary:''' Microsoft Sign-In (SSO) integration for VoIPmonitor GUI using Microsoft Entra ID (formerly Azure AD). Currently in development branch only. Setup requires: (1) Register application in Microsoft Entra as Single Page Application, get Client ID and Tenant ID. (2) Configure GUI in Settings > System configuration > Advanced with IDs. (3) Map users via Secure users tab or set default fallback user. User mapping order: direct email match, Secure users list, default user. Redirect URI must be exact GUI URL without trailing slash or page names. For reverse proxy setups (AWS ALB, Nginx), configure X-Forwarded-Proto header to prevent redirect loops.


'''Keywords:''' Microsoft Sign-In, SSO, Single Sign-On, Microsoft Entra, Azure AD, Azure Active Directory, authentication, OIDC, OAuth, GUI login, enterprise authentication, Microsoft integration, tenant ID, client ID, redirect URI, user mapping
'''Keywords:''' Microsoft Sign-In, SSO, Single Sign-On, Microsoft Entra, Azure AD, Azure Active Directory, authentication, OIDC, OAuth, GUI login, enterprise authentication, tenant ID, client ID, redirect URI, user mapping, X-Forwarded-Proto, reverse proxy, AWS ALB


'''Key Questions:'''
'''Key Questions:'''
Line 150: Line 126:
* Is Microsoft Sign-In available in the stable GUI version?
* Is Microsoft Sign-In available in the stable GUI version?
* How do I set up a default user for Microsoft Sign-In?
* How do I set up a default user for Microsoft Sign-In?
* Why can't I see the Microsoft Sign-In option in my GUI?
* Why does Microsoft Sign-In fail behind a reverse proxy?
 
* What is the user mapping order for Microsoft Sign-In?
== See Also ==
 
* [[WEB_API#Custom_Login_.28LDAP.29_-_scripts.2Fcustom_login.php|Custom Login (LDAP)]] - Custom login scripts for LDAP integration

Latest revision as of 17:06, 8 January 2026


Overview

Microsoft Sign-In allows VoIPmonitor GUI users to authenticate using their Microsoft Entra ID (formerly Azure AD) accounts, providing Single Sign-On (SSO) capability.

User Mapping Order

When a user signs in with Microsoft, VoIPmonitor maps them to a GUI user profile in this order:

  1. Direct email match - Username in VoIPmonitor matches Microsoft email
  2. Secure users list - Microsoft email is listed in user's "Microsoft Sign In emails" field
  3. Default user - Falls back to the user marked as "Default Microsoft Sign In account"

Quick Reference

Parameter Where to Get Where to Enter
Client ID Microsoft Entra > App registration > Overview > Application (client) ID GUI > Settings > System configuration > Advanced
Tenant ID Microsoft Entra > App registration > Overview > Directory (tenant) ID GUI > Settings > System configuration > Advanced
Redirect URI Your VoIPmonitor GUI URL Microsoft Entra > App registration > Redirect URIs

Part 1: Microsoft Entra Configuration

Register the Application

  1. Go to entra.microsoft.com > App registrations > + New registration
  2. Configure:
    • Name: e.g., "VoIPmonitor SSO"
    • Supported account types: "Accounts in this organizational directory only"
    • Redirect URI - Platform: Single page application
    • Redirect URI - URL: Your VoIPmonitor GUI URL
  3. Click Register
  4. Note the Application (client) ID and Directory (tenant) ID from the Overview page

ℹ️ Note: Redirect URI format:

Assign Users

In Microsoft Entra, go to Users and add users who should have access to VoIPmonitor via Microsoft Sign-In.

Part 2: VoIPmonitor GUI Configuration

Enable Microsoft Sign-In

  1. Go to Settings > System configuration > Advanced
  2. Enable Enable Microsoft Sign in
  3. Enter:
    • Microsoft client ID - from Entra
    • Microsoft tenant ID - from Entra
    • Redirect URI - leave empty (auto-detected)

Map Users

For each user who will use Microsoft Sign-In:

  1. Go to Users & Audit > Users > edit user
  2. Secure users tab > fill Microsoft Sign In emails with their Microsoft email

Default User (Optional)

To set a fallback user for unmapped Microsoft accounts:

  1. Edit the desired user > Basic data tab
  2. Check Default Microsoft Sign In account

Troubleshooting

SSO Fails Behind Reverse Proxy

Symptom: Redirect loops or "too many redirects" errors when using AWS ALB, Nginx, or other reverse proxies with SSL termination.

Cause: The proxy terminates HTTPS but forwards HTTP to the backend, breaking the OAuth callback flow.

Solution: Pass the original protocol via X-Forwarded-Proto header: 

# Nginx configuration
proxy_set_header X-Forwarded-Proto $scheme;

For AWS ALB, this header is automatic but ensure intermediate proxies pass it through. See Nginx for complete configuration.

See Also

AI Summary for RAG

Summary: Microsoft Sign-In (SSO) integration for VoIPmonitor GUI using Microsoft Entra ID (formerly Azure AD). Currently in development branch only. Setup requires: (1) Register application in Microsoft Entra as Single Page Application, get Client ID and Tenant ID. (2) Configure GUI in Settings > System configuration > Advanced with IDs. (3) Map users via Secure users tab or set default fallback user. User mapping order: direct email match, Secure users list, default user. Redirect URI must be exact GUI URL without trailing slash or page names. For reverse proxy setups (AWS ALB, Nginx), configure X-Forwarded-Proto header to prevent redirect loops.

Keywords: Microsoft Sign-In, SSO, Single Sign-On, Microsoft Entra, Azure AD, Azure Active Directory, authentication, OIDC, OAuth, GUI login, enterprise authentication, tenant ID, client ID, redirect URI, user mapping, X-Forwarded-Proto, reverse proxy, AWS ALB

Key Questions:

  • How do I enable Microsoft Sign-In in VoIPmonitor?
  • How do I configure SSO with Microsoft Entra for VoIPmonitor?
  • What is the correct Redirect URI format for Microsoft Sign-In?
  • Where do I find the Microsoft client ID and tenant ID?
  • How do I map VoIPmonitor users to Microsoft accounts?
  • Is Microsoft Sign-In available in the stable GUI version?
  • How do I set up a default user for Microsoft Sign-In?
  • Why does Microsoft Sign-In fail behind a reverse proxy?
  • What is the user mapping order for Microsoft Sign-In?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Microsoft_Sign_in_usage&oldid=10225"