OAuth 2.0 / OpenID Connect Setup

Since Mango 5.2

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).

New in Mango 5.7

Mango 5.7 adds configurable connect and read timeouts for OAuth2/OIDC HTTP clients via oauth2.client.connectTimeout=30 seconds and oauth2.client.readTimeout=30 seconds in mango.properties. These settings apply to all OAuth2/OIDC HTTP clients used during login. Increase the read timeout if your identity provider's token or userinfo endpoints occasionally exceed 30 seconds.

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/oauth2/callback/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>/oauth2/callback/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 registration ID in the redirect URI (radixiot in /oauth2/callback/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.

Bearer token roles (resource server)

The oauth2.resourceserver.{provider}.jwt.* properties apply to bearer tokens presented to the Mango REST API — a separate path from the interactive browser login configured in the steps above.

New in Mango 5.7.4

Mango roles for OAuth 2.0 bearer tokens can be mapped from a claim in the token — such as groups or roles — via oauth2.resourceserver.{provider}.jwt.roles-claim. The claim may be a JSON array or a space-separated string. Claim values map to the Mango role with the same XID, and can be remapped, filtered or decorated with ...jwt.roles-claim.map.{value}, .ignore, .prefix and .suffix. This is applied independently of map-scope, and the results are combined with the static ...jwt.roles list.

# Read roles from a claim in the token (JSON array or space-separated string)
oauth2.resourceserver.microsoft.jwt.roles-claim=groups

# Remap a claim value to one or more Mango roles
#oauth2.resourceserver.microsoft.jwt.roles-claim.map.MangoAdmins=superadmin
# Claim values to ignore
#oauth2.resourceserver.microsoft.jwt.roles-claim.ignore=
# Add a prefix/suffix to claim values when mapping them to Mango roles
#oauth2.resourceserver.microsoft.jwt.roles-claim.prefix=
#oauth2.resourceserver.microsoft.jwt.roles-claim.suffix=

Changed in Mango 5.7.4

In Mango 5.7.3 and earlier, ...jwt.map-scope.{scope} was the only way to derive roles from a bearer token, and the authenticated principal's name was the token's entire set of claims. Starting in 5.7.4, scope mapping is documented as a sound authorization source only for client-credentials (machine-to-machine) tokens — an identity provider such as Keycloak grants an optional scope because it was requested, without consulting the user's own privileges — so use roles-claim for tokens that represent a user. The principal name is now JWT {sub} ({iss}), so claim contents (which may include personal information) no longer appear in logs or audit records. A scope or scp claim supplied as a JSON array rather than a space-separated string no longer causes an HTTP 500, and a configured role that does not exist in Mango is now logged at debug level instead of being dropped silently.

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