Connect Microsoft Entra ID to Netos

Connect your company's Microsoft Entra ID (formerly Azure Active Directory) to Netos so your people sign in with their Microsoft work account, and Entra groups decide what they can do in NetBox. This guide is for the Entra administrator and the Netos contact working together on the setup.

What you need

On your side (Entra administrator)

  • An Entra account that can create an app registration and grant consent for it in your tenant.
  • Your tenant ID.
  • The email domains your people sign in with, for example example.com.
  • Every user's sign-in name (user principal name) is their work email in one of those domains.
  • One Entra security group per level of access, for example netos-engineers (edit) and netos-viewers (read only).
  • MFA for your users, through your Conditional Access policies or security defaults.

From Netos (we send you)

  • Your zone name, for example uks001, and its two redirect URIs.
  • The credential Netos will use to authenticate to your tenant (see Step 3).

Back to Netos (you send us, Step 5)

  • Tenant ID, application (client) ID, email domains, and which Entra group gets which access on which environment.

How sign-in works

sequenceDiagram
  actor U as User
  participant G as Netos zone
  participant E as Your Entra tenant
  participant N as NetBox
  U->>G: Open Netos link, enter work email
  G->>U: Continue with your company sign-in
  U->>E: Microsoft sign-in and MFA
  E->>G: ID token with groups
  G->>G: Map Entra groups to NetBox groups
  G->>N: Open NetBox as the user

Netos identifies each user by their tenant and object ID, not by their email, so a renamed user keeps their Netos user. It reads the email from the preferred_username claim, so that claim must be the user's work email.

Step 1: Register the application

In the Microsoft Entra admin center, create a new app registration.

  1. Name it, for example Netos <zone>.
  2. Supported account types: accounts in this organizational directory only (single tenant). Netos accepts a single-tenant issuer only.
  3. Add a Web redirect URI, then add the second one, so both are present:
    • https://<zone>.app.netos.io/_auth/callback
    • https://<zone>-auth.app.netos.io/_auth/callback
  4. Register, then note the Application (client) ID and the Directory (tenant) ID.

Step 2: Add the groups claim

Netos reads group membership from the groups claim in the ID token.

  1. In the app registration's token configuration, add a groups claim for security groups, included in the ID token.
  2. Entra sends group object IDs, not names. Send Netos the object ID of each group you name in Step 5.
  3. Keep the token to the groups Netos uses, for example by sending only groups assigned to the application. A user whose token carries more than 64 groups can be refused.

Step 3: Set the credential

Netos supports two ways to authenticate to your tenant. Agree which with your Netos contact.

  • Signed token (preferred): Netos signs a token with its own private key (private_key_jwt). You add the public key Netos sends you to the app registration. There is no secret to store or rotate on your side.
  • Client secret: you create a client secret on the app registration and send it to Netos through the secure route your Netos contact gives you. Never send a secret by email or chat.

Step 4: Require MFA and assign users

  1. Netos treats a sign-in as multi-factor when the token reports it (amr contains mfa). Production environments require it. Make sure your Conditional Access policy for the Netos application requires MFA.
  2. In the enterprise application for Netos <zone>, assign the groups whose members may sign in to Netos. Setting assignment required stops anyone else from signing in.

Step 5: Send these details to Netos

Item Example
Tenant ID 11111111-1111-4111-8111-111111111111
Application (client) ID 22222222-2222-4222-8222-222222222222
Email domains example.com
Entra groups (object ID and name) and the access each should get netos-viewers: read on all environments; netos-engineers: edit on lab, read on production

Netos adds your tenant to your zone, links the groups to NetBox groups per environment, and confirms when you can test. Your issuer is https://login.microsoftonline.com/<tenant-id>/v2.0.

Test checklist

  1. A user in a linked group opens your Netos link, enters their email, and sees the button to continue with your company sign-in.
  2. They complete Microsoft sign-in and MFA, then land on the Netos home page with their environments.
  3. In NetBox, their user is in the expected group for that environment.
  4. Move them to a different Entra group and sign in again; their NetBox group changes.
  5. A user in no linked group gets "Access denied".

Removing access

Remove the user from the Netos groups in Entra, or disable the account. They cannot start a new session, and open sessions end at the next check against Entra.

Troubleshooting

What the user sees Likely cause Fix
Email goes to Netos ID instead of Microsoft The email domain is not linked to your tenant on this zone Send Netos the domain
Microsoft reports a redirect URI mismatch One of the two redirect URIs is missing or mistyped Check both URIs in Step 1
"Sign in failed" after Microsoft Netos could not complete the token exchange, often a wrong credential (Step 3) Check the credential, then send Netos the reference ID and time
"Access denied" after Microsoft The user is in no linked group, the groups claim is missing, or preferred_username is not an email in a linked domain Check Step 2 and the user's sign-in name
Refused on production only The sign-in did not report MFA Require MFA for the Netos application (Step 4)

Netos support can trace a failed sign-in from the reference ID shown on the error page.