Skip to main content

Single Sign-on authentication

All users who log in to an account with the account's password assume Root user privileges by default, and can access and update the account's settings. But, if the account has enabled SAML Single Sign-On authentication, two user roles are available:

Root and Admin

These user roles are assigned to users in an identity provider (like Okta). For accounts with SSO enabled, only users with the Root role will be able to access and update settings as described below.

Manage your organization's access to Mapbox accounts while adding another level of security with SAML Single sign-on (SSO). SSO enables members of your organization to authenticate into a Mapbox account through any trusted, third-party identity provider that supports the SAML2.0 protocol.

SAML SSO capabilities​

SupportedNot Supported
  • SAML2.0 protocol
  • Identity provider (IdP) initiated login
  • Shared accounts that multiple users can access
  • User roles of Root and Admin
  • JIT (Just in Time) provisioning
  • SCIM provisioning / de-provisioning
  • Domain control or domain lockout
  • Service provider (SP) initiated login
  • Identity provider (IdP) initiated single logout
  • OAuth, OpenID Connect, Kerberos, other protocols
  • Multiple identity providers for a single account
  • SAML authentication for Atlas on-premises
  • Individual user accounts, a nested sub-account hierarchy, or separate, connected accounts

Setting up SAML SSO for your Mapbox account​

SAML Single sign-on for Mapbox can be configured with any identity provider that supports the SAML 2.0 protocol. Integrate the Mapbox SAML applications offered by Okta, Azure AD, and OneLogin for a streamlined setup and IdP specific documentation, or learn more about the general steps for setting up SSO with any identity provider below.

Okta​

Azure Active Directory​

OneLogin​

  • OneLogin App Store: A Mapbox SAML app is available. Log in to your OneLogin portal, navigate to the Administration panel, click "Browse app catalog", and search for "Mapbox".

Identity providers that support SAML2.0​

You can create a custom SAML app for Mapbox if there is not a Mapbox SAML application available in your IdP. The setup workflow and terminology used by each identity provider can be unique, but there are general themes:

  1. Log in to the Mapbox account you want to set up with SSO authentication
  2. Navigate to the account's SSO setup page
  3. In your identity provider (IdP), create a new SAML application
  4. Copy and paste the required details in the Configure your identity provider section of the Mapbox SSO setup page into your IdP’s configuration workflow
  5. Create a custom attribute within your app that will pass the required user roles from your IdP to Mapbox in the SAML assertion.
  6. Copy and paste the required details from your SAML app within your IdP into the Setup SAML single sign-on for Mapbox section of the SSO setup page
  7. Click Enable single sign-on to save the integration
  8. Validate the integration is working as expected by assigning yourself one of the required user roles for the Mapbox SAML app. If required, assign yourself the application within your IdP.
  9. Assign users to the Mapbox application in your IdP, and assign a required Mapbox user role to each user (or user group)
  10. Follow the recommendations for enforcing SAML authentication, then flip the Activate Mapbox SSO toggle from Off to On to immediately terminate all sessions.

Configuring your identity provider​

Log into your identity provider with the required administrative privileges, then create a custom SAML2.0 application for Mapbox. See the following external links for IdP specific instructions:

In this new application, enter the following values from the Mapbox SSO setup page:

  • Single sign-on URL, also could be referred to as the SSO URL, Assertion Consumer Service (ACS) URL, Application ACS URL, Reply URL, Callback URL, or Post-back URL in your IdP.
  • Audience Restriction, also could be referred to as Audience URI, SP Entity ID, Identifier, or Application SAML Audience in your IdP.

Configuration notes

  • The application username must be in email format
  • The SHA256 encryption algorithm is required
  • One of the supported user roles must be present in the SAML assertion for a successful SAML login.

Configuring user roles in your identity provider​

Through SAML SSO you can assign users roles that provide certain permissions in the Mapbox Account and Studio apps that are also enforced by all Mapbox APIs. User roles are assigned in the identity provider and transferred to Mapbox in the SAML assertion. The available user roles are:

RolePermissionsTypical users
RootUsers with the Root role can access invoices, read and write to account settings, and read and write to all resources and APIs.IT Admins, Product Owners, CTOs
AdminUsers with the Admin role can read and write to all resources and APIs. They cannot access invoices, nor can they read or write to account settings.Developers, Designers, Project contributors

Many identity providers use custom attributes and attribute statements for roles. The attribute key name and role values are case-insensitive. Typically, roles can be assigned to individuals or groups. Consult the documentation for your specific IdP, such as the Okta documentation for Mapbox SAML apps for details.

Enabling SAML SSO for the Mapbox account​

To complete the initial connection between your identity provider and mapbox.com, enter the required information in the Mapbox account's SSO setup page:

  • Identity Provider sign-on URL, also could be referred to as SSO URL, SAML endpoint, or SSO sign-in URL in your IdP
  • Issuer ID, also could be referred to as Entity ID, Issuer, or Issuer URL in your IdP
  • X.509 Certificate, pasted as text into the field.

Be sure to include — BEGIN CERTIFICATE — and — END CERTIFICATE — when pasting your X.509 certificate into the Mapbox form. You may need to open the X.509 certificate in a text editor to accurately copy the full body.

Click Enable single sign-on to submit the form. You will be prompted to re-authenticate.

Validating the SAML SSO integration​

Once you have saved the integration, return to your identity provider to assign the application to yourself and/or another member of the organization for testing. When assigned, try clicking the tile, "chiclet", or link for your Mapbox app to log in from your identity provider's portal. If you receive an error when attempting to log in with SAML, you can adjust the settings by clicking edit single sign on.

Enforcing SAML SSO authentication​

Enabling SSO for an account does not invalidate password authentication. The account's password is still a valid authentication method to make sure your organization's transition period to SAML authentication is seamless, and that direct password access to the account is available in case your identity provider has a service outage. Note that any users logging in with the account's password (and optional 2FA) will assume the Root user role.

To encourage your users to transition from password-based authentication to SAML login through your IdP, we recommend the following once the integration has been tested successfully:

  • Assign yourself the Root user role in your IdP so you will have access to settings
  • Assign most other users the Admin user role so they will not have access to settings
  • Change the email for the account to an email address that the Root user(s) can access
  • Save the new password in a safe location with least-privilege access (identity provider, shared password manager, IT vault)
  • If 2FA is enabled for the account, either turn it off or save the recovery codes with the new password
  • Announce to your organization that SAML SSO will be the primary mechanism for Mapbox access as of a future date. Encourage all users to test that they can access Mapbox with SAML before that date.
  • On the date of enforcement, toggle the Activate single sign on button on the account's Security Settings page to immediately terminate all the account's active sessions.
  • Change the password for the account, making the previous password invalid. As with activating Mapbox SSO, when the account's password is changed, all active sessions will be terminated. We recommend taking these two steps at the same time to prevent confusion for your users.

Once SSO is activated and the password has been changed, these updates should effectively push all application users to authenticate with Single Sign-On, as they'll no longer have the password.

Questions about setting up SAML SSO? Visit the troubleshooting section for recommendations and next steps to contact support.

Deleting SAML SSO integration​

You have the option to delete your SAML SSO integration. This is something you would need to do only in a rare situation -- generally, only if your organization has set up single sign-on with a test account. Some identity providers can only be associated with a single Mapbox account. If you or your IT team has associated an IdP with a test account, we recommend deleting that integration before beginning setup for the organization's main account.

Was this page helpful?