Supporting SAML on Edge for Private Cloud

Edge for Private Cloud v4.19.01

The Edge UI and Edge management API operate by making requests to the Edge Management Server, where the Management Server supports the following types of authentication:

  • Basic Auth Log in to the Edge UI or make requests to the Edge management API by passing your username and password.
  • OAuth2 Exchange your Edge Basic Auth credentials for an OAuth2 access token and refresh token. Make calls to the Edge management API by passing the OAuth2 access token in the Bearer header of an API call.

Edge also supports Security Assertion Markup Language (SAML) 2.0 as the authentication mechanism. With SAML enabled, access to the Edge UI and Edge management API still uses OAuth2 access tokens. However, now you can generate these tokens from SAML assertions returned by a SAML identity provider.

SAML supports a single sign-on (SSO) environment. By using SAML with Edge, you can support SSO for the Edge UI and API in addition to any other services that you provide and that also support SAML.

Support added for OAuth2 to Edge for Private Cloud

As mentioned above, the Edge implementation of SAML relies on OAuth2 access tokens.Therefore, OAuth2 support has been added to Edge for Private Cloud. For more information, see Introduction to OAuth 2.0.

SAML advantages

SAML authentication offers several advantages. By using SAML you can:

  • Take full control of user management. When users leave your organization and are deprovisioned centrally, they are automatically denied access to Edge..
  • Control how users authenticate to access Edge. You can choose different authentication types for different Edge organizations.
  • Control authentication policies. Your SAML provider may support authentication policies that are more in line with your enterprise standards.
  • You can monitor logins, logouts, unsuccessful login attempts and high risk activities on your Edge deployment.

Using SAML with Edge

To support SAML on Edge, you install apigee-sso, the Edge SSO module. The following image shows Edge SSO in an Edge for Private Cloud installation:

You can install the Edge SSO module on the same node as the Edge UI and Management Server, or on its own node. Ensure that Edge SSO has access to the Management Server over port 8080.

Port 9099 has to be open on the Edge SSO node to support access to Edge SSO from a browser, from the external SAML IDP, and from the Management Server and Edge UI. As part of configuring Edge SSO, you can specify that the external connection uses HTTP or the encrypted HTTPS protocol.

Edge SSO uses a Postgres database accessible on port 5432 on the Postgres node. Typically you can use the same Postgres server that you installed with Edge, either a standalone Postgres server or two Postgres servers configured in master/standby mode. If the load on your Postgres server is high, you can also choose to create a separate Postgres node just for Edge SSO.

With SAML enabled, access to the Edge UI and Edge management API uses OAuth2 access tokens. These tokens are generated by the Edge SSO module which accepts SAML assertions returned by the your IDP.

Once generated from a SAML assertion, the OAuth token is valid for 30 minutes and the refresh token is valid for 24 hours. Your development environment might support automation for common development tasks, such as test automation or Continuous Integration/Continuous Deployment (CI/CD), that require tokens with a longer duration. See Using SAML with automated tasks for information on creating special tokens for automated tasks.

Edge UI and API URLs

The URL that you use to access the Edge UI and Edge management API is the same as used before you enabled SAML. For the Edge UI:

http://edge_ui_IP_DNS:9000
https://edge_ui_IP_DNS:9000

where edge_ui_IP_DNS is the IP address or DNS name of the machine hosting the Edge UI. As part of configuring the Edge UI, you can specify that the connection use HTTP or the encrypted HTTPS protocol.

For the Edge management API:

http://ms_IP_DNS:8080/v1
https://ms_IP_DNS:8080/v1

where ms_IP_DNS is the IP address or DNS name of the Management Server. As part of configuring the API, you can specify that the connection use HTTP or the encrypted HTTPS protocol.

Configure TLS on Edge SSO

By default, the connection to Edge SSO uses HTTP over port 9099 on the node hosting apigee-sso, the Edge SSO module. Built into apigee-sso is a Tomcat instance that handles the HTTP and HTTPS requests.

Edge SSO and Tomcat support three connection modes:

  • DEFAULT - The default configuration supports HTTP requests on port 9099.
  • SSL_TERMINATION - Enabled TLS access to Edge SSO on the port of your choice. You must specify a TLS key and cert for this mode.
  • SSL_PROXY - Configures Edge SSO in proxy mode, meaning you installed a load balancer in front of apigee-sso and terminated TLS on the load balancer. You can specify the port used on apigee-sso for requests from the load balancer.

Enable SAML support for the portal

After enabling SAML support for Edge, you can optionally enable SAML for Apigee Developer Services portal (or simply, the portal). The portal supports SAML authentication when making requests to Edge. Note that this is different from SAML authentication for developer login to the portal. You configure SAML authentication for developer login separately. See Configuring the portal to use SAML to communicate with Edge for more.

As part of configuring the portal, you must specify the URL of the Edge SSO module that you installed with Edge: