Configure the portal to use external IDPs

Apigee Developer Services portal (or simply, the portal) acts as a client of Apigee Edge. That means the portal does not function as a stand-alone system. Instead, much of the information used by the portal is actually stored on Edge. When necessary, the portal makes a request to retrieve information from Edge or to send information to Edge.

The portal is always associated with a single Edge organization. When you configure the portal, you can specify the basic authentication credentials (username and password) for an account in the organization that the portal uses to communicate with Edge.

If you choose to enable an external IDP such as SAML or LDAP for Edge authentication, you can then configure the portal to use that authentication when making requests to Edge. Configuring the portal to use an external IDP automatically creates a new machine user account in the Edge organization that the portal then uses to make requests to Edge. For more on machine users, see Automate tasks for external IDPs.

External IDP support for the portal requires that you have already installed and configures the Apigee SSO module on the Edge Management Server node. The general process for enabling an external IDP for the portal is as follows:

Install the Apigee SSO module, as described in Install Apigee SSO for high availability.
NOTE: Basic authentication must still be enabled on Edge to install the portal. Do not disable Basic authentication on Edge until after you have configured and tested the portal with an external IDP.
Install the portal and ensure that your installation is working properly. See Install the portal.
Configure SAML or LDAP on the portal, as described in this section.
(Optional) Disable Basic authentication on Edge, as described in Disable Basic authentication on Edge.

Create a machine user for the portal

When an external IDP is enabled, Edge supports automated OAuth2 token generation through the use of machine users. A machine user can obtain OAuth2 tokens without having to specify a passcode. That means you can completely automate the process of obtaining and refreshing OAuth2 tokens.

The IDP configuration process for the portal automatically creates a machine user in the organization associated with the portal. The portal then uses this machine user account to connect to Edge. For more on machine users, see Automate tasks for external IDPs.

About authentication for portal developer accounts

When you configure the portal to use an external IDP, you enable the portal to use either SAML or LDAP to authenticate with Edge so that the portal can make requests to Edge. However, the portal also supports a type of user called developers.

Developers make up the community of users that build apps by using your APIs. App developers use the portal to learn about your APIs, to register apps that use your APIs, to interact with the developer community, and to view statistical information about their app usage on a dashboard.

When a developer logs in to the portal, it is the portal that is responsible for authenticating the developer and for enforcing role-based permissions. The portal continues to use Basic authentication with developers even after you enable IDP authentication between the portal and Edge. For more information, see Communicating between the portal and Edge.

It is possible to also configure the portal to use SAML or LDAP to authenticate developers. For an example on enabling SAML using third-party Drupal modules, see SSO Integration via SAML with Developer Portal.

IDP configuration file for the portal

To configure an external IDP for the portal, you must create a configuration file that defines the portal's settings.

The following example shows a portal configuration file with IDP support:

# IP address of Edge Management Server and the node on which the Apigee SSO module is installed.
IP1=22.222.22.222

# URL of Edge management API.
MGMT_URL=http://$IP1:8080/v1

# Organization associated with the portal.
EDGE_ORG=myorg

# Information about the Apigee SSO module (apigee-sso).
# Externally accessible IP or DNS of apigee-sso.
SSO_PUBLIC_URL_HOSTNAME=$IP1
SSO_PUBLIC_URL_PORT=9099
# Default is http. Set to https if you enabled TLS on apigee-sso.
SSO_PUBLIC_URL_SCHEME=http

# SSO admin credentials as set when you installed apigee-sso.
SSO_ADMIN_NAME=ssoadmin
SSO_ADMIN_SECRET=Secret123

# Enables or disables external IDP support.
# Default is "n", which disables external IDP support.
# Change it to "y" to enable external IDs support.
DEVPORTAL_SSO_ENABLED=y

# The name of the OAuth2 client used to connect to apigee-sso.
# The default client name is portalcli.
PORTALCLI_SSO_CLIENT_NAME=portalcli
# OAuth client password using uppercase, lowercase, number, and special characters.
PORTALCLI_SSO_CLIENT_SECRET=Abcdefg@1

# Email address and user info for the machine user created in the Edge org specified
# above by EDGE_ORG.
# This account is used by the portal to make requests to Edge.
# Add this email as an org admin before configuring the portal to use an external IDP.
DEVPORTAL_ADMIN_EMAIL=DevPortal_SAML@google.com
DEVPORTAL_ADMIN_FIRSTNAME=DevPortal
DEVPORTAL_ADMIN_LASTNAME=SAMLAdmin
DEVPORTAL_ADMIN_PWD=Abcdefg@1

# If set, the existing portal OAuth client is deleted and a new one is created.
# The default value is "n".
# Set to "y" when you configure the external IDP and change the value of
# any of the PORTALCLI_* properties.
PORTALCLI_SSO_CLIENT_OVERWRITE=y

To enable external IDP support on the portal:

In the Edge UI, add the machine user specified by DEVPORTAL_ADMIN_EMAIL to the organization associated with the portal as an Organization Administrator.
NOTE: The machine user does not exist yet but is created automatically in the next step.
Execute the following command to configure the external IDP on the portal:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-drupal-devportal configure-sso -f configFile
```
Where configFile is the configuration file described above.
Log in to the portal as a portal admin.
In the main Drupal menu, select Configuration > Dev Portal. The portal configuration screen appears, including the external IDP settings:

NOTE: The title and other aspects of this dialog specifies SAML, but the settings apply to any other supported IDPs (such as LDAP).

Note the following:
- The box for This org is SAML-enabled is checked
- The endpoint for the Apigee SSO module is filled in
- The API key and Consumer secret fields for the portal Oauth client are filled in
- The message Connection Successful appears under the Test Connection button.
Click the Test Connection button to retest the connection at any time.

To later change these values, update the configuration file and execute this procedure again.

Disable an external IDP on the portal

If you choose to disable your external IDP for communications between the portal and Edge, the portal will no longer be able to make requests to Edge. Developers are able to log in to the portal but will not be able to view product or create apps.

To disable external IDP authentication on the portal:

Open the configuration file that you used previously to enable the external IDP.
Set the value of the DEVPORTAL_SSO_ENABLED property to n, as the following example shows:
```
DEVPORTAL_SSO_ENABLED=n
```

Configure the portal by executing the following command:

/opt/apigee/apigee-service/bin/apigee-service apigee-drupal-devportal configure-sso -f configFile