SAML SSO Setup
This feature is available with the Professional or Premium tier of NetBox Cloud, or with NetBox Enterprise.
NetBox Cloud supports single sign-on (SSO) with any SAML 2.0 identity provider (IdP), including Okta, Microsoft Entra ID, OneLogin, and Auth0, so users can log in with their existing corporate credentials instead of separate NetBox account credentials.
This centralizes access control and simplifies user management, letting administrators grant or revoke NetBox Cloud access directly from your IdP.
NetBox Cloud acts as the SAML service provider (SP). Your IdP authenticates the user and returns a signed assertion, which NetBox Cloud uses to create or update a local user account.
If your IdP is Okta or Microsoft Entra ID, you can use the provider-specific OIDC setup instead. See Okta SSO Setup or Microsoft Entra ID Setup.
Identity provider configuration
The exact steps vary by provider, but every IdP needs the same information from NetBox Cloud.
Register NetBox Cloud as a service provider
Create a new SAML 2.0 application in your IdP and provide the following, substituting your own domain.
| Setting | Value |
|---|---|
| Service Provider (SP) entity ID (also called Audience URI or Identifier) | https://\{your-domain\}.cloud.netboxapp.com |
| Assertion Consumer Service (ACS) URL (also called Single sign-on URL, Reply URL, or Recipient URL) | https://\{your-domain\}.cloud.netboxapp.com/oauth/complete/saml/ |
These values must match the configuration applied to your instance exactly, including the trailing slash on the ACS URL.
Map user attributes
NetBox Cloud reads user details from named attributes in the SAML assertion. Configure your IdP to send the following.
| Attribute | Contents |
|---|---|
email | User's email address. NetBox Cloud uses this as the username. |
first_name | Given name |
last_name | Surname |
These attribute names are the ones NetBox Cloud looks for in the assertion, so they are the same whatever IdP you use. What differs by provider is where you configure them and which user property you map into each one. In Okta they are attribute statements on the app's SAML settings, mapping email to user.email; in Entra ID they are claims under Single sign-on > Attributes & Claims, mapping email to user.mail.
Attribute names are case-sensitive and must match exactly.
To assign NetBox Cloud permissions from IdP group membership, you will also need to send a groups attribute. See Group Mapping For SAML Single Sign-On (SSO).
Collect your IdP details
After creating the application, collect three values from your IdP. All three are published in its SAML metadata.
- entity_id: your IdP's unique identifier.
- url: your IdP's SSO login URL. It must support the HTTP-Redirect binding.
- x509cert: the base64-encoded X.509 certificate NetBox Cloud uses to verify assertion signatures. Download it from your IdP, or copy the
<X509Certificate>value from the metadata XML.
NetBox Cloud configuration
Send the following to NetBox Labs Support:
- Your IdP metadata file, or the
entity_id,url, andx509certvalues you collected above. - The SP entity ID you configured in your IdP, if it differs from the value in the table above.
Preferred submission method: send your IdP metadata file. This standardized format ensures all necessary information is included.
The support team will then:
- Add your IdP details to your NetBox Cloud instance.
- Generate a public/private certificate pair for the service provider.
- Send you the SP public certificate, which you add to your IdP application if it verifies signed authentication requests.
Testing
After the support team has confirmed that your Cloud instance has been configured, you can test it.
Log out of NetBox Cloud and click the "Log In" button at top right. You should see the normal login form as well as an option to authenticate using SAML.
Click the SAML option. You will be redirected to your IdP's authentication portal where you can log in with your test user's credentials.
If successful, you will be redirected back to the NetBox Cloud UI, and will be logged in as the IdP user. You can verify this by clicking your login ID in the upper right and selecting Profile.
This user account is now replicated within NetBox Cloud, and can be assigned groups and permissions within the NetBox Cloud admin UI.
By default, new users have no permissions. To assign permissions automatically from IdP group membership, see Group Mapping For SAML Single Sign-On (SSO).
Troubleshooting
Response received at an unexpected URL
If authentication fails with an error such as "The response was received at ... instead of ...", the URL your IdP posted the assertion to does not match the one NetBox Cloud expects.
Check the ACS URL configured in your IdP against the following pattern, including the subdomain and the trailing slash.
https://<your-domain>.cloud.netboxapp.com/oauth/complete/saml/SAML response validation failed
If authentication fails immediately on return from your IdP with a validation or signature verification error, the certificate NetBox Cloud uses to verify assertions no longer matches the one your IdP signs with.
Confirm the certificate has not expired and that your IdP has not rotated its signing certificate. If it has, download a fresh copy and email it to NetBox Labs Support.
Missing or empty user details
If a user logs in but the username is blank or the name fields are empty, or authentication fails with an error such as "Missing needed parameter first_name", the attribute names your IdP sends do not match what NetBox Cloud expects.
Compare the attribute names configured in your IdP against the table under Map user attributes. Names are case-sensitive. Confirm too that your test user has a value for every attribute you mapped: a mapped attribute that is absent from the assertion causes authentication to fail.
A SAML tracer browser extension is useful here, as it captures the assertion so you can read the attribute names your IdP is actually sending.
Not logged in after authenticating
If you are redirected to the NetBox Cloud UI after authenticating successfully, but are not logged in, confirm that the assertion includes the email attribute. NetBox Cloud uses it as the username, and cannot create the account without it.
If the assertion looks correct, contact NetBox Labs Support so we can check the authentication backend configured on your instance.