Single Sign-On (SSO)

Overview

SSO/SAML is only available on Production and Enterprise plans.

Aptible provides Single Sign On (SSO) to an organization’s resources through a separate, single authentication service, empowering customers to manage Aptible users from their primary SSO provider or Identity Provider (IdP).

Aptible supports the industry-standard SAML 2.0 protocol for using an external provider. Most SSO Providers support SAML, including Okta and Google’s GSuite. SAML provides a secure method to transfer identity and authentication information between the SSO provider and Aptible.

Each organization may have only one SSO provider configured. Many SSO providers allow for federation with other SSO providers using SAML. For example, allowing Google GSuite to provide login to Okta. If you need to support multiple SSO providers, you can use federation to enable login from the other providers to the one configured with Aptible.

How to setup Single Sign-On (SSO)

Organization Login ID

When you complete Single Sign On Provider Setup, your organization’s users can use the SSO link on the SSO login page to begin using the configured SSO provider. They must enter an ID unique to your organization to indicate which organization they want to access.

That ID defaults to a randomly assigned unique identifier. Account owners may keep that identifier or set an easier-to-remember one on the SSO settings page. Your organization’s primary email domain or company name makes a good choice. That identifier is to make login easier for users.

Do not change your SSO provider configuration after changing the Login ID. The URLs entered in your SSO provider configuration should continue to use the long, unique identifier initially assigned to your organization. Changing the SSO provider configuration to use the short, human-memorable identifier will break the SSO integration until you restore the original URLs.

You will have to distribute the ID to your users so they can enter it when needed. To simplify this, you can embed the ID directly in the URL. For example, https://dashboard.aptible.com/sso/example_id. Users can then bookmark or link to that URL to bypass the need to enter the ID manually. You can start the login process without knowing your organization’s unique ID if your SSO provider has an application “dashboard” or listing.

Require SSO for Access

When Require SSO for Access is enabled, Users can only access their organization’s resources by using your configured SAML provider to authenticate with Aptible. This setting aids in enforcing restrictions within the SSO provider, such as password rotation or using specific second factors.

Require SSO for Access will prevent users from doing the following:

• Users cannot log in using the Aptible credentials and still access the organization’s resources.
• Users cannot use their SSH key to access the git remote.

Manage the Require SSO for Access setting in the Aptible Dashboard by selecting Settings > Single Sign-On.

Before enforcing SSO, we recommend notifying all the users in your organization. SSO will be the only way to access your organization at that point.

CLI Token for SSO

To use the Aptible CLI with Require SSO for Access enabled, users must:

1. Generate an SSO token.
   1. In the Aptible Dashboard, select the user’s profile on the top right and then “CLI Token for SSO,” which will bring you to the CLI Token SSO settings page.
2. Provide the token to the CLI via the aptible login --sso $SSO_TOKEN command.

Invalidating CLI Token for SSO

1. Tokens will be automatically invalidated once the selected duration elapses.
2. Generating a new token will not invalidate older tokens.
3. To invalidate the token generated during your current session, use the “Logout” button on the bottom left of any page.
4. To invalidate tokens generated during other sessions, except your current session, navigate to Settings > Security > “Log out all sessions”

Controlling CLI Token Lifetime

To limit how long CLI tokens remain valid when using SSO:

1. Require SSO for all users — Enable Require SSO for Access (described above).
2. Configure session duration in your Identity Provider — Set a shorter max session duration in your IdP (e.g., Google Workspace). This is where the limit is enforced.

The token generated for Aptible will be limited to the max session duration configured in your Identity Provider, even if a user selects a longer duration in the Aptible dashboard

Exempt Users from SSO Requirement

Users exempted from the Require SSO for Access setting can log in using Aptible credentials and access the organization’s resources. Users can be exempt from this setting in two ways:

• users with an Account Owner role are always exempt from this setting
• users added to the SSO Allow List

The SSO Allow List will only appear in the SSO settings once Require SSO for Access is enabled.

Account Owners and users on the SSO Allow List can generate CLI tokens directly through Aptible (via username/password login) even when Require SSO is enabled. These users may create tokens with a lifetime of up to 7 days. There is no mechanism to reduce this 7-day limit at the organization level. To enforce shorter token lifetimes, we recommend limiting the number of users granted Account Owner access.

We recommend restricting the number of Users exempt from the Require SSO for Access settings, but there are some use cases where it is necessary; some examples include:

• to allow users to use their SSH key to access the git remote
• to give contributors (e.g., consultants or contractors) access to your Aptible account without giving them an account in your SSO provider
• to grant “robot” accounts access to your Aptible account to be used in Continuous Integration/Continuous Deployment systems

Users in Multiple Organizations

Users can be members of multiple organizations. If a user logs in with Aptible username and password (rather than SSO), they can create tokens with a lifetime of up to 7 days. However, without Account Owner access in a given organization, those tokens will not grant access to that organization’s resources. So even if a user can create longer-lived tokens via password login, those tokens will not provide access to resources in an organization where Require SSO is enabled.