OAuth 2.0 / OpenID Connect Setup

Mango supports single sign-on (SSO) using OAuth 2.0 / OpenID Connect. Users can log in with their existing corporate credentials from identity providers such as Google Workspace or Microsoft Entra ID (formerly Azure Active Directory).

Google Workspace

Step 1: Create OAuth Consent Screen

1. Open the Google APIs Console.
2. Create an OAuth consent screen.
3. On the Scopes page, add openid, email, and profile.

Step 2: Create OAuth Client ID

1. Go to the Credentials page and click Create Credentials > OAuth client ID.
2. Choose Web Application.
3. In Authorized JavaScript Origins, enter your Mango URL (e.g., https://mango.example.com).
4. In Authorized redirect URIs, enter:

   https://mango.example.com/rest/v2/authentication/login/oauth2/code/mycompany

   Replace mycompany with your chosen registration ID.

Step 3: Configure Mango

Add the following to your mango.properties file:

authentication.oauth2.enabled=true
oauth2.client.registrationIds=mycompany
oauth2.client.registration.mycompany.clientId=YOUR_CLIENT_ID
oauth2.client.registration.mycompany.clientSecret=YOUR_CLIENT_SECRET

Optional: Restrict to a G Suite Domain

To limit login to users from a specific Google Workspace domain:

oauth2.client.registration.mycompany.authorizationUri=https://accounts.google.com/o/oauth2/v2/auth?hd=example.com

---

Microsoft Entra ID (Azure AD)

Applies to Mango v5.6.x and v5.5.7.

Step 1: Register an Application in Entra

1. Sign in to the Azure portal and go to Microsoft Entra ID.
2. Navigate to App registrations → New registration.
3. Enter:
   • Name: e.g. Mango-SSO
   • Supported account types: Typically "Accounts in this organizational directory only (Single tenant)"
   • Redirect URI (Web):

     https://<your-mango-host>/rest/v2/authentication/login/oauth2/code/radixiot

     Replace <your-mango-host> with your Mango URL and radixiot with your chosen registration ID.
4. Click Register.

From the app overview page, record:

• Application (client) ID — used as clientId in Mango
• Directory (tenant) ID — used in the Entra endpoints

important

The path segment in the redirect URI (radixiot) must exactly match the value in oauth2.client.registrationIds and the registration prefix oauth2.client.registration.radixiot.* in mango.properties.

Step 2: Create a Client Secret

1. In the app registration, go to Certificates & secrets → Client secrets.
2. Click New client secret, add a description, and choose an expiration.
3. Copy the Value immediately — it is only shown once.

Step 3: Configure Role Mapping in Entra (Optional)

To control Mango permissions based on Entra groups or app roles, configure one of the following:

Option A: Security Groups

1. In Microsoft Entra ID, create groups (e.g., Mango Admins, Mango Operators).
2. Add users to the appropriate groups.
3. In the app registration, go to Token configuration and add a Groups claim so group membership is included in the token.

Option B: App Roles

1. In the app registration, go to App roles and create roles (e.g., MangoAdmin, MangoOperator).
2. Assign these roles to users or groups under Enterprise Applications → Users and groups.

note

Only "Users & Security groups" can be assigned to app roles, not "Microsoft 365" groups.

Step 4: Configure Mango (mango.properties)

Replace <TENANT_ID>, <CLIENT_ID>, and <CLIENT_SECRET> with your values:

# Enable OAuth2 / OpenID Connect login
authentication.oauth2.enabled=true
oauth2.client.registrationIds=radixiot

# Associate with the Microsoft provider
oauth2.client.registration.radixiot.provider=microsoft

# Microsoft Entra endpoints (v2.0)
oauth2.client.registration.radixiot.authorizationUri=https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize
oauth2.client.registration.radixiot.tokenUri=https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token
oauth2.client.registration.radixiot.jwkSetUri=https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys
oauth2.client.registration.radixiot.issuerUri=https://login.microsoftonline.com/<TENANT_ID>/v2.0

# Credentials
oauth2.client.registration.radixiot.clientId=<CLIENT_ID>
oauth2.client.registration.radixiot.clientSecret=<CLIENT_SECRET>

# Optional: login button label and branding
oauth2.client.registration.radixiot.clientName=Sign in with Microsoft

Step 5: Configure Role Synchronization

Add the following role mapping properties to mango.properties:

# Mango role XIDs that can be assigned from Entra
oauth2.resourceserver.microsoft.jwt.roles=superadmin,operator,viewer

# Role sync behavior (see note below)
oauth2.client.default.userMapping.roles.sync=true

# Advanced options (uncomment and adjust as needed)
#oauth2.client.default.userMapping.roles.ignore=
#oauth2.client.default.userMapping.roles.prefix=
#oauth2.client.default.userMapping.roles.suffix=
#oauth2.client.default.userMapping.roles.map.MangoAdmin=superadmin
#oauth2.client.default.userMapping.roles.add=

Role sync: version-specific behavior

Setting	Mango v5.5.7	Mango v5.6.x
roles.sync=true	Syncs roles from Entra on every login	Syncs roles from Entra on every login
roles.sync=false	Mango manages roles locally, Entra does not override	Known issues in some builds — test with a non-admin user before relying on this

If you are on v5.6.x and need strict local role management: test roles.sync=false in a staging environment with a non-admin test user before deploying to production.

Role sync strategies

Centralize in Entra — set roles.sync=true. Entra group/app role membership determines Mango roles on every login. Use when permissions are managed centrally in your identity provider.

Manage locally in Mango — set roles.sync=false. Entra authenticates the user (controls who can log in), but Mango administrators assign roles manually. Use when role assignment must be controlled inside Mango.

Step 6: Grant Admin Consent (Optional)

To remove the individual user consent prompt, go to API permissions in the app registration and click Grant admin consent. This pre-authorizes the app for all users in your directory.

---

Testing the Integration

1. Restart Mango after saving mango.properties.
2. Open your Mango URL in a browser.
3. The login page should show an SSO button for your configured provider.
4. Sign in with a user from your identity provider.
5. Confirm the user is logged in and has the expected Mango roles.

Troubleshooting

Symptom	Check
Login button does not appear	Verify authentication.oauth2.enabled=true and Mango restarted
Redirect URI mismatch error	Confirm the URI in Entra exactly matches Mango's — including https, host, and registration ID
User logs in but has wrong roles	Check the roles or groups claim in the token (use jwt.io to decode)
Role sync not working on v5.6.x	Test roles.sync=false behavior — see version note above
OAuth errors in Mango logs	Verify all four Entra endpoint URIs use the correct <TENANT_ID>

---

Related Pages

• LDAP Configuration — Alternative SSO using LDAP or Active Directory
• Users and Permissions — Manage Mango user accounts and role assignments
• Mango Properties Reference — Full reference for mango.properties
• Reverse Proxy Configuration — Configure forwarded headers when OAuth callbacks pass through a proxy