Configure SAML single sign-on (SSO)

Last updated: October 26, 2026NIM service baseline: v4.0.1546

Settings guide

Set up SAML single sign-on (SSO) so users authenticate to NIM through your existing identity provider instead of managing a separate NIM password.

SAML single sign-on (SSO) in NIM

SAML is the protocol NIM uses for single sign-on (SSO). With SAML SSO, users sign in to NIM through an identity provider (IdP) such as Microsoft Entra ID, Google Workspace, or Okta. This centralizes authentication and can apply the same sign-in policies, including multifactor authentication, that your organization already uses.

In the SAML exchange, NIM is the service provider (SP) and your sign-in platform is the IdP. The IdP issues an assertion that NIM uses to identify the user; metadata supplies the endpoints and certificates that let the two sides communicate. The OASIS SAML 2.0 Technical Overview explains these roles and the browser SSO flow. When troubleshooting, check the IdP metadata, assertion signing certificate, and user identifier against the values configured on both sides.

Before you begin

SAML can authenticate users through providers such as Microsoft Entra ID, Google Workspace, or Okta. Each user must exist in NIM’s Internal users table with a matching email address or username. To restrict a user to a specific SAML configuration, set AuthMethod to saml<configuration name>, such as samlEntra for a configuration named Entra. If AuthMethod is undefined, the user can use any authentication method configured in NIM. See Internal user AuthMethod rules.

Prepare HTTPS and the external hostname

Before creating a SAML configuration for any provider:

1. Enable HTTPS/SSL on NIM and confirm that you can open NIM using its intended HTTPS hostname.
2. Go to Configuration > Settings > Preferences and set External host URL to the correct hostname, such as nim.domain.com. See Preferences.
3. Choose the SAML configuration name you will use in NIM, such as Entra, Google, or CorporateSSO. Use that name consistently in the ACS URL and Internal users' AuthMethod values.
4. Provision matching Internal users. To restrict a user to this SAML configuration, set AuthMethod to saml followed by the configuration name, with no space or separator.

Example names only: Choose one name for the SAML configuration you are creating, or use your own. You do not need to create all three configurations shown below. Each row illustrates how that chosen name determines the ACS URL and AuthMethod value.

Example configuration name	Resulting example ACS URL	Resulting example AuthMethod
Entra	https://nim.domain.com/api/v1/saml/sp/acs/Entra	samlEntra
Google	https://nim.domain.com/api/v1/saml/sp/acs/Google	samlGoogle
CorporateSSO	https://nim.domain.com/api/v1/saml/sp/acs/CorporateSSO	samlCorporateSSO

Replace nim.domain.com with your NIM external hostname. After creating a configuration, use its displayed ACS Callback URL and SP metadata to confirm the provider's values. The provider's app name is separate from the NIM configuration name.

Keep a recovery path

Keep a local administrator recovery path until SAML authentication has been tested successfully.

Choose your identity provider

After completing the shared preparation above, follow the instructions for your identity provider:

Microsoft Entra ID

Create a non-gallery enterprise application, exchange metadata, and assign users.

Configure Entra ID →

Google Workspace

Create a custom SAML app, enter NIM's endpoints, and enable user access.

Configure Google Workspace →

Other

Connect another SAML identity provider using NIM's SP metadata and ACS URL.

Configure another provider →

Configure Microsoft Entra ID SAML

The enterprise application name in Entra and the SAML configuration name in NIM are separate settings:

Setting	Example
NIM external hostname	nim.domain.com
Enterprise application name in Entra	NIM
SAML configuration name in NIM	Entra
Internal user AuthMethod	samlEntra

Create a non-gallery application and select SAML

1. Open the Microsoft Entra admin center and go to Entra ID > Enterprise applications > All applications. Microsoft's Add an enterprise application guide describes how to access this area.
2. Select New application, then Create your own application.
3. Enter an application name, such as NIM.
4. Select Integrate any other application you don't find in the gallery (Non-gallery), then select Create.
5. Once the application is created, go to Manage > Single sign-on.
6. Select SAML.

Set the NIM endpoints and download metadata

1. Under Basic SAML Configuration, select Edit.

2. Enter the values below. Replace the example hostname and configuration name with your own.

   Entra setting	Value	Example
   Identifier (Entity ID)	The NIM hostname, matching External host URL.	nim.domain.com
   Reply URL (Assertion Consumer Service URL)	https://<External host URL>/api/v1/saml/sp/acs/<NIM SAML configuration name>	https://nim.domain.com/api/v1/saml/sp/acs/Entra

3. Select Save.

4. Set Verification Certificates – Required to No.

5. Under SAML Certificates, download the Federation Metadata XML file for this application.

The Reply URL must use the same configuration name you will create in NIM. After creating that configuration, compare this value with NIM's displayed ACS Callback URL.

Download Federation Metadata XML

Do not copy the App Federation Metadata URL. Its certificate can differ from the certificate assigned to the application. Download and upload the Federation Metadata XML file instead.

Upload the identity-provider metadata

In NIM, go to Configuration > Settings > SAML, select Add, name the configuration (for example, Entra), upload the Entra metadata file in IdP Metadata, and select Create.

The example below shows a configuration named Entra. If you use a different name, use that name in the Reply URL and AuthMethod values as well.

Open the new configuration, select the Sp tab, and confirm that the following options are selected, as shown in the screenshot:

• Want Assertions Signed
• Want Message Signed
• Want Logout Request Signed
• Login Hint As Query Parameter

Leave Signed Authn Requests and Want Logout Response Signed cleared.

Upload NIM metadata and assign access

1. Select the new NIM SAML configuration and copy the metadata url and open it in a new browser tab. Save the metadata to the disk. Upload it to the Entra enterprise application to populate the required application values. Confirm the Reply URL matches the configuration's ACS Callback URL.

2. In the Entra application's Users and groups, assign the users and groups that may sign in to NIM.

3. In NIM's Internal users table, set each intended user's AuthMethod to saml immediately followed by the Name of the SAML configuration in NIM, with no space or separator.

   NIM SAML configuration name	Internal user AuthMethod
   Entra	samlEntra
   CorporateSSO	samlCorporateSSO

   Use your actual configuration name. The Entra enterprise application name does not determine this value. For example, an Entra application named NIM and a NIM SAML configuration named Entra require samlEntra.

4. Save the changes and test the complete login process with a controlled Internal user before enabling access for a broader group. The email address or username in the SAML assertion must match that Internal user.

Step 1 of 4

Configure Google Workspace SAML

Use Google's custom SAML app guide alongside the NIM-specific values below.

Create a custom app and download Google metadata

1. Sign in to the Google Admin console as a super administrator.
2. Open Apps > Web and mobile apps.
3. Select Add app > Add custom SAML app.
4. Name the app, such as NIM, and select Continue.
5. On Google Identity Provider details, download the IdP metadata. Keep this setup open while configuring NIM in another tab.

Upload Google metadata to NIM

1. In NIM, go to Configuration > Settings > SAML and select Add.
2. Name the configuration, such as Google, upload the downloaded file in IdP Metadata, and select Create.
3. Select the new configuration and copy its ACS Callback and Metadata URLs. Open or download the NIM SP metadata to confirm its entityID value. This is NIM's service-provider identity, not the Google IdP Entity ID shown in Google's metadata.

Use your actual configuration name in the URLs and in Internal users' AuthMethod values.

Map the NIM endpoints and user identity

Return to the Google setup, select Continue, and enter Service Provider Details:

Google setting	Value	Example
ACS URL	NIM's ACS Callback URL: https://<External host URL>/api/v1/saml/sp/acs/<NIM SAML configuration name>.	https://nim.domain.com/api/v1/saml/sp/acs/Google
Entity ID	The entityID from NIM's SP metadata. The existing Google configuration uses the NIM Metadata URL. Confirm the exact value in your metadata.	https://nim.domain.com/api/v1/saml/sp/metadata/Google
Signed response	Enabled to match NIM's signed-response requirement.	Checked
Name ID format	EMAIL	EMAIL
Name ID	Basic Information > Primary Email	The user's Google primary email address

The Metadata URL locates NIM's SP metadata; the value in its entityID attribute is the identifier to match. If your NIM metadata specifies a different Entity ID, use that exact value in Google. Do not substitute Google's IdP Entity ID or the app's display name.

Select Continue, add any attribute mappings required by your NIM user-identification settings, and select Finish.

Enable the app for users and test sign-in

1. Open the app's User access settings. Enable it for the intended organizational units or access groups, or choose On for everyone when appropriate. Save.
2. Confirm that each test user's Google primary email matches the intended NIM Internal user. For a NIM configuration named Google, set AuthMethod to samlGoogle. For another name, use saml followed by that name.
3. Use Test SAML login in Google, then test sign-in from NIM with a controlled user.
4. Confirm the user reaches NIM successfully before broadening access. Google notes that access changes can take up to 24 hours to propagate.

Step 1 of 4

Configure another SAML identity provider

Use this procedure for an IdP other than Entra ID or Google Workspace. Complete the HTTPS and hostname preparation first. The example NIM configuration name is CorporateSSO.

Create the provider app and the NIM configuration

1. In your IdP, create a SAML 2.0 application for NIM and obtain its IdP metadata XML file. Use your provider's instructions for creating the app and signing certificate.
2. In NIM, go to Configuration > Settings > SAML, select Add, and enter a configuration name such as CorporateSSO.
3. Upload the provider's file in IdP Metadata and select Create.
4. Select the new NIM configuration. Download its SP metadata and copy its displayed ACS Callback URL.

Configure the Entity ID and ACS in your provider

If the provider supports importing SP metadata, upload NIM's metadata file. Otherwise, enter these values in its service-provider settings:

Provider setting	What to enter	Example
SP Entity ID, Audience, or Identifier	The exact entityID in NIM's SP metadata. Do not use the IdP's own issuer or Entity ID.	nim.domain.com if NIM's metadata contains entityID="nim.domain.com".
ACS URL, Reply URL, or SSO callback URL	NIM's ACS Callback URL: https://<External host URL>/api/v1/saml/sp/acs/<NIM SAML configuration name>.	https://nim.domain.com/api/v1/saml/sp/acs/CorporateSSO
SP metadata URL or SP metadata file	NIM's displayed Metadata URL or the downloaded XML file. This supplies the SP identity, endpoints, and certificates.	https://nim.domain.com/api/v1/saml/sp/metadata/CorporateSSO

The metadata URL is the location of the XML file; it is not automatically interchangeable with the Entity ID. Copy the entityID value exactly, including its scheme and path when present. Match the ACS URL's scheme, hostname, path, and configuration name as well.

Configure the provider's assertion and response signing to match the requirements on NIM's Sp tab. Map the SAML user identifier to the email address or username NIM uses to find the Internal user, then save both configurations.

Match Internal users and verify access

1. Assign the intended users or groups to the application in your IdP.
2. In NIM, confirm that the SAML identifier matches the intended Internal user. To restrict the user to this configuration, set AuthMethod to saml plus the NIM configuration name: samlCorporateSSO for CorporateSSO.
3. Test sign-in with a controlled non-administrator user. Verify the returned identity and successful access before expanding the assignment.

Step 1 of 3

Troubleshoot SAML sign-in

Login fails with a signed authentication request flag conflict

!

Problem

Login fails with a signed authentication request flag conflict

Error message

ERR_METADATA_CONFLICT_REQUEST_SIGNED_FLAG

Resolution

1. In NIM, go to Configuration > Settings > SAML and open the affected configuration.
2. Open the Sp tab. Make sure Signed Authn Requests is unchecked, then save the configuration if you changed it.
3. If it is already unchecked, select Signed Authn Requests and save. Then uncheck it and save again.
4. Retry the login process.

Renew identity-provider metadata after certificate expiration

!

Problem

Renew identity-provider metadata after certificate expiration

Likely cause

The identity provider's SAML signing certificate has expired or been renewed, and NIM still has the previous metadata.

Resolution

1. Obtain a current metadata XML file from your identity provider.
2. In NIM, go to Configuration > Settings > SAML.
3. Edit the existing configuration for that identity provider.
4. Select the IdP tab.
5. Upload the current file in IdP Metadata.
6. Select Update to save the configuration.
7. Test sign-in with a controlled non-administrator user before restoring broader access.

Update the existing configuration; you do not need to create a new one for the same identity provider. Keep a local administrator recovery path and retain the prior metadata file according to your organization's change and retention process until testing succeeds.

Report a problem with this page

Found an error or a missing step? Open the feedback form and describe what needs changing. The article details and Documentation topic are filled in for you.

Need help with your NIM environment? Contact Support.