Initial setup

Single Sign-on (SSO) supports integrating authentication for your Nextmv accounts with a SSO provider using SAML. Nextmv supports Auth0, Microsoft Entra ID and OKTA Identity Providers (IDP). The Nextmv SSO SAML integration supports the service provider initiated login flow.

Attribute Mappings

Nextmv requires two attributes, email and name, to be present in the SAML token. Setup instructions specify how to configure these for each supported IDP.

Behavior with Single Sign-on Enabled

SSO is enabled on a single account, but the configuration applies to any user in any account whose email belongs to the domain defined by the SSO integration. SSO uses the domain of the owner's email of the account in which the SSO is configured as the SSO domain. Consider treating the account specially since it defines behavior across multiple accounts belonging to the domain, and Nextmv will have additional features in the future that are for organization wide rather than account specific. We also recommend that the email account of the owner not be tied to an individual, but rather be generalized for the account (ex: nextmv-admin@example.com)

To illustrate the SSO behavior, if fred@example.com and betty@example.com both created Nextmv accounts, and then fred@example.com configures his account to use SSO, then the domain example.com becomes an SSO domain. After enabled betty@example.com will be authenticated via SSO to her account.

The permission model remains unchanged from the description in teams where users are invited to an account by an administrator who determines their role in the account, and the user accepts the invitation.

Behavior when a SSO User first accesses Nextmv

When a SSO user first accesses Nextmv they will not have an account created. This behavior differs from the case of a non-SSO user, where Nextmv always creates an account for the user upon first access. If the user has already been invited to other accounts within the organization, then the user will see those invitations. Once the user accepts an invitation the account becomes the users default organization (instead of having their own "root account"). Subsequently the user will be shown the default account at login and can switch to other accounts using the teams mechanism.

Configuring Nextmv for SSO

Configuration settings are same for all SSO integrations for Nextmv, but how you setup your IDP will vary by provider, and you should reference the provider's integration page for detailed instructions. Instructions are available for Auth0, Microsoft Entra and Okta IDP configurations.

You configure SSO using the Nextmv CLI. Since the CLI works using an API key, you will not run the risk of being locked out if a misconfiguration impacts Nextmv console login. You will need either the metadata URL or download the metadata document from your IDP provider.

The following example configures an SSO integration for the Nextmv platform with all of the features enabled:

nextmv account sso configure \
    --metadata-url "$METADATA_URL"  \
    --enabled \
    --allow-non-domain-users

allow-non-domain-users setting

This setting determines if non-domain users are allowed to be invited to an account. The setting applies to all accounts where the owner of the account is in the SSO domain. If allow_non_domain_users is not set then administrators will not be allowed to invite users that are not in your domain. Accounts that existed prior to SSO being configured that had owners in the SSO domain are impacted by this setting.

If an account had non-domain users prior to enabling SSO, then those users will be able to continue to access the account and will need to be removed manually if desired.

enabled setting

This setting enables SSO for an account that has been configured. If set to false when configuring an account, then the configuration is created but not yet enforced. You can subsequently toggle enabled to enable/disable the integration. This gives a quick way to turn off the integraiton if it isn't functioning correctly.