Information for: DEVELOPERS   PARTNERS   SUPPORT

Looking for something?

Federated Authentication

Federated Authentication is an Acquia Cloud Platform feature that enables you to register and integrate with an external Identity Provider (IdP). This ensures that your users need to authenticate using the IdP to access resources within a Cloud Platform organization. You can purchase Federated Authentication as an add-on to your Cloud Platform subscription, if it is not included in your plan.

Note

  • Federated Authentication is a feature in Acquia Cloud Platform and is different from Site Factory’s Single Sign-On (SSO) offering. For more information on the SSO feature in Site Factory, see Managing Site Factory accounts.
  • Federated Authentication is separate from Acquia’s Single Sign-On (SSO) –Drupal SAML/LDAP configuration Professional Services engagement. For more information on configuring SAML/LDAP with your Drupal sites, see Single Sign-On – Drupal SAML/LDAP Configuration.

How does Federated Authentication work?

Federated Authentication enforces additional authentication, provided by the customer’s IdP, to access protected resources within your Cloud Platform organization. Resources within a Cloud Platform organization include applications and associated environments, logging, crons, and organization management like teams and permissions. Federated Authentication uses a Service Provider (SP)-initiated authentication flow. In an SP-initiated flow, your user attempts to access a protected resource, such as environment, and is redirected to the external IdP to verify the identity. After the IdP verifies the user’s identity, the requested protected resource is provided.

All Cloud Platform users must have an Acquia account, including the users who will authenticate with an IdP through Federated Authentication. In addition, such users must have an account with their IdP. Acquia accounts belong to users and not the subscription holder because certain users, such as consultants, may work across different subscriptions and have access to multiple Cloud Platform organizations. Users are only required to authenticate with an IdP through Federated Authentication when they are attempting to access resources within a protected Cloud Platform organization.

saml_flow

IdP compatibility with Federated Authentication

To integrate with Cloud Platform, your IdP must support SP-initiated SAML using the Redirect-POST method. Cloud Platform redirects sign-in requests to your IdP through a GET request and your IdP responds with a POST request. Cloud Platform doesn’t support the IdPs authenticating with a POST-POST method or the IdPs that only support IdP-initiated SAML authentication flows.

Managing Cloud Platform users

Federated Authentication doesn’t support SCIM, user provisioning, or user management. Federated Authentication doesn’t map roles nor use the SAML attributes for user role permissions mapping. Each user must have an Acquia account, even when they have access to a Cloud Platform organization that is integrated with an IdP. Acquia user roles and permissions are managed through the Cloud Platform and not through the IdP. For more information on provisioning users, deprovisioning users, and managing Cloud Platform user permissions, see Managing users, teams, roles, and permissions.

Security information about Federated Authentication

Before integrating a Cloud Platform organization with an IdP, note the following security implications:

  • Integrating with an IdP affects all users accessing the Cloud Platform organization, including partners or consultants who belong to a different company.
  • Acquia employees can access your subscription even after you enable the Federated Authentication feature.
  • Acquia Support can debug SSO configuration issues using information from the Cloud Platform and HAR files. However, Acquia Support can’t help with issues pertaining to a customer’s IdP.
  • Deactivating a user in your IdP prevents the user from accessing protected resources within the Cloud Platform organization. However, this won’t deactivate Git or SSH access. To completely remove the user’s access, you must remove the user from any associated teams either manually or by using the Cloud Platform API v2. For more information, see Best practices for team member departures.

Setting up Federated Authentication

To add an IdP to your Cloud Platform organization:

  1. Confirm that Federated Authentication is available to your Cloud Platform organization.
  2. Submit informatiom from your IdP.
  3. Register your Cloud Platform organization with your IdP.
  4. Enable Federated Authentication.

Note

  • The setup process requires you to register the Cloud Platform organization with your IdP.
  • The Cloud Platform’s SAML integration may be different from others that you have managed because it is an SP-initiated flow. For more information on the SP-initiated flow, see How does Federated Authentication work?.
  • The labels that Acquia uses for SAML concepts, as outlined in the following instructions, may be different from the labels that your IdP uses for the same concepts. Every IdP labels items differently.

Part 1: Confirm that Federated Authentication is available to your Cloud Platform organization

  1. Confirm with your Account Manager that Acquia has enabled Federated Authentication for the Cloud Platform organization that you’d like to protect.

  2. Sign in to the Cloud Platform user interface with the user account that owns the organization or as a user with the Admin role for that organization.

  3. Select Manage.

  4. Select the organization you want to change.

  5. In the left navigation pane, select Security.

  6. Verify if you can see the Register an Identity Provider option. The system displays this option if Federated Authentication is enabled for your account.

    idp_page

  7. If you don’t see the Register an Identity Provider option, contact your Account Manager.

Note

For IDP-specific instructions, see:

Part 2: Submit information from your IdP

  1. After you complete the earlier steps, click Register an Identity Provider and specify the following information:

    enter_idp_information

  2. In Label, specify a human-readable name for the IdP configuration.

  3. In Entity ID, specify the entity ID that you obtain from your IdP.

    Note

    If you integrate multiple Cloud Platform organizations with your IdP, you must have a unique entity ID for each organization. Therefore, you might need to set up a new application within your IdP where each application has a unique entity ID.

  4. In SSO URL, specify the URL that you obtain from your IdP. Every IdP structures its SSO URL differently. Ensure that this URL uses the SP-initiated SSO method.

  5. In Public Certificate, paste the public certificate of your IdP in the PEM format.

  6. Select Submit.

Note

Some IdPs require an ACS link before they provide the entity ID or SSO URL. Cloud Platform generates the ACS link once all the listed values are specified. To avoid this issue, enter dummy values for the information that your IdP won’t provide. Cloud Platform generates the ACS link despite the dummy values. Before enabling Federated Authentication, ensure that you specify the correct values once they are available.

Part 3: Register your Cloud Platform organization with your IdP

After you complete these steps, the Cloud Platform user interface displays a summary of the information that you must provide to your IdP. Don’t forget to update any dummy values you provided while specifying IdP details in Cloud Platform. To update these values, select Edit.

  1. Provide the entity ID of Cloud Platform and your IdP’s ACS link to register with your IdP.

    Cloud Platform uses the information provided in Part 2 to generate an ACS link specific to your IdP.

    register_idp

  2. If you specified dummy values in Entity ID or SSO URL in the previous section, update these fields with the values provided by the IdP.

  3. Ensure that your IdP is configured with the following:

    • The response from your IdP and the assertion within the response must be signed. If not, validation fails. Your IdP must have ds:Signature... as a child of <saml:Assertion….
    • Ensure that your IdP sends the RelayState to Cloud Platform.

Important

Don’t enable the external IdP in Cloud Platform until you register your Cloud Platform organization with your IdP and update any dummy values used in this section. If the configuration is incorrect, you and all members of your organization may be locked out of the Cloud Platform user interface. If you are locked out, contact Acquia support.

Part 4: Enable Federated Authentication

  1. After completing these steps, select Enable.

    Cloud Platform displays a confirmation dialog box.

  2. Select the confirmation check box and select Enable.

    The Cloud Platform user interface displays a confirmation window indicating that your IdP is enabled.

    idp_enabled

    After Federated Authentication is enabled, you and your users must authenticate with your external IdP when you access the Cloud Platform organization.

User experience

When Federated Authentication is enabled, users sign in using their Cloud Platform account credentials on the Acquia Cloud Platform login page. Users are redirected to authenticate with the IdP when attempting to access protected resources. This means that users must log in twice:

  • Through the Acquia Cloud Platform login page
  • When attempting to access protected resources

  1. Sign in to the Cloud Platform user interface.

    log_in_cp

  2. Navigate to the Cloud Platform organization to access applications and their environments.

    navigate_cp

  3. Authenticate with IdP. For example, Google.

    authenticate_google

  4. Proceed with access to the Cloud Platform Organization and its applications.

    proceed_cp

Additional information

  • When Federated Authentication is enabled, the IdP manages access to restricted resources in the Cloud Platform user interface.
  • All access token sessions are cached for up to five minutes. After the token session expires, Acquia Cloud Platform re-authenticates with the IdP again.
    • A user who is authenticated with the IdP is not required to take any action. The redirect occurs silently from Acquia Cloud Platform to the IdP and back.
    • A user who isn’t authenticated with the IdP must authenticate. Upon successful authentication, such a user is redirected to Acquia Cloud Platform and can access protected resources.
    • A user who isn’t authenticated with the IdP and can’t authenticate (account is inactivated or credentials are lost) can’t access the protected resources on Acquia Cloud Platform and will get a 401 Unauthorized Access error response.

User provisioning for Acquia Cloud Platform

User account provisioning (accounts.acquia.com)

  • When a user signs up for an account, the user must validate the ownership for the email address.
  • When a user is invited to a Cloud Platform organization, the invitation is sent through email.
  • When a user belongs to a Cloud Platform organization that requires IdP authentication, the user can view the organization but cannot access the organization or any resources that belong to the organization, without authenticating with the IdP.
  • For more information, see Controlling access to Cloud Platform.

User account deprovisioning

  • SSH access is not managed through the IdP. To restrict access after an employee’s departure, change the passwords for the private keys or generate new keys entirely. For more information, see Controlling access to Cloud Platform.
  • When an employee departs, delete such users from the Cloud Platform organization and delete all outstanding invitations.
  • Cloud Platform provides an API endpoint to automate the removal of a user’s membership from a Cloud Platform organization. For more information, see here.
  • For more information, see Best practices for team member departures.

53 State Street, 10th Floor
Boston, MA 02109
United States
Phone: 888-922-7842