安裝並設定 Apigee 單一登入 (SSO)

如要使用外部 IDP 安裝及設定 Apigee 單一登入 (SSO) 模組，您必須執行下列操作：

  1. 建立金鑰和憑證。
  2. 設定 Apigee 基礎單一登入設定：基礎檔案必須包含所有 SSO 設定的共用屬性。
  3. 新增 IdP 專屬設定屬性：在設定檔中使用下列任一 IdP 專屬設定屬性區塊：
  4. 安裝 Apigee SSO：安裝 Apigee SSO 模組，並將設定檔傳遞至安裝程式。

我們會在後續章節中說明每個步驟。

建立金鑰和憑證

本節說明如何建立自行簽署的憑證，這類憑證可能適用於測試環境，但您應在實際工作環境中使用由憑證授權單位 (CA) 簽署的憑證。

如何建立用於簽署驗證的金鑰組：

  1. 以 sudo 使用者身分建立以下新目錄： 
    sudo mkdir -p /opt/apigee/customer/application/apigee-sso/jwt-keys
  2. 變更至新的目錄： 
    cd /opt/apigee/customer/application/apigee-sso/jwt-keys/
  3. 使用下列指令產生私密金鑰：
    sudo openssl genrsa -out privkey.pem 2048
  4. 使用下列指令，從私密金鑰產生公開金鑰：
    sudo openssl rsa -pubout -in privkey.pem -out pubkey.pem
  5. 將輸出 PEM 檔案的擁有者變更為「apigee」使用者：
    sudo chown apigee:apigee *.pem

如要建立金鑰和自行簽署的憑證 (不含密碼字串)，以便與 IDP 通訊：

  1. 以 sudo 使用者身分建立新目錄：
    sudo mkdir -p /opt/apigee/customer/application/apigee-sso/idp/
  2. 變更至新的目錄： 
    cd /opt/apigee/customer/application/apigee-sso/idp/
  3. 使用通關密語產生私密金鑰： 
    sudo openssl genrsa -out server.key 2048
  4. 從金鑰中移除密碼短語：
    sudo openssl rsa -in server.key -out server.key
  5. 為 CA 產生憑證簽署要求： 
    sudo openssl req -x509 -sha256 -new -key server.key -out server.csr
  6. 產生有效期限為 365 天的自行簽署憑證：
    sudo openssl x509 -sha256 -days 365 -in server.csr -signkey server.key -out selfsigned.crt
  7. 將金鑰和憑證匯出至 KeyStore：
    1. 將金鑰和憑證匯出至 PKCS12 金鑰庫：
      2. sudo openssl pkcs12 -export -clcerts -in <certificate_path> -inkey <key_path> -out <keystore_path> -name <alias>

      參數：

      • certificate_path：在步驟 6 中建立的憑證路徑。
      • key_path：在步驟 3 中產生的私密金鑰路徑。
      • keystore_path：新建 PKCS12 金鑰庫的路徑，其中包含憑證和私密金鑰。
      • alias：用於參照 KeyStore 中金鑰和憑證組合的別名。

      詳情請參閱 OpenSSL 說明文件。

    2. (選用) 將金鑰和憑證從 PKCS12 匯出至 JKS KeyStore：
      3. sudo keytool -importkeystore -srckeystore <PKCS12_keystore_path> -srcstoretype PKCS12 
-destkeystore <destination_keystore_path> -deststoretype JKS -alias <alias>

      參數：

      • PKCS12_keystore_path：步驟 7 中建立的 PKCS12 金鑰庫路徑，其中包含憑證和私密金鑰。
      • destination_keystore_path：新建 JKS 金鑰庫的路徑，其中包含相同的憑證和金鑰。
      • alias：在 JKS 鍵值儲存庫中，用於金鑰和憑證組合的別名。

      詳情請參閱 Keytool 說明文件。

    3. 將輸出 KeyStore 檔案的擁有者變更為「apigee」使用者：
      sudo chown apigee:apigee <keystore_file>
    4. 請在 silent.conf 中更新下列屬性：
      5. # Path to your keystore  
SSO_SAML_SERVICE_PROVIDER_KEYSTORE_PATH=/opt/apigee/customer/application/apigee-sso/saml/keystore.p12  

# Keystore password
SSO_SAML_SERVICE_PROVIDER_KEYSTORE_PASSWORD=Secret123

# Alias within keystore that stores the key and certificate  
SSO_SAML_SERVICE_PROVIDER_KEYSTORE_ALIAS=service-provider-cert  

# [Optional] Only specify if you are using something other than JKS. Values could be PKCS12 or BCFKS  
SSO_SAML_SERVICE_PROVIDER_KEYSTORE_TYPE=JKS

    如要在 Apigee 單一登入模組上啟用 TLS，請將 SSO_TOMCAT_PROFILE 設為 SSL_TERMINATION 或 SSL_PROXY，這樣就無法使用自行簽署的憑證。您必須透過 CA 產生憑證。詳情請參閱「為 HTTPS 存取權設定 Apigee SSO」一文。

    Apigee 單一登入 (SSO) 設定

    您必須先定義設定檔，才能安裝 Apigee 單一登入 (SSO) 模組。安裝 Apigee 單一登入 (SSO) 模組時，您會將此設定檔傳遞給安裝程式。

    設定檔的格式如下：

    IP1=hostname_or_IP_of_apigee_SSO
IP2=hostname_or_IP_of_apigee_SSO

## Management Server configuration.
# Management Server IP address and port
MSIP=$IP1
MGMT_PORT=8080
# Edge sys admin username and password as set when you installed Edge.
ADMIN_EMAIL=opdk@google.com
APIGEE_ADMINPW=Secret123
# Set the protocol for the Edge management API. Default is http.
# Set to https if you enabled TLS on the management API.
MS_SCHEME=http

## Postgres configuration.
# Postgres IP address and port
PG_HOST=$IP1
PG_PORT=5432
# Postgres username and password as set when you installed Edge.
PG_USER=apigee
PG_PWD=postgres

## Apigee SSO module configuration.
# Choose either "saml" or "ldap".
SSO_PROFILE="[saml|ldap]"
# Externally accessible IP or DNS name of apigee-sso.
SSO_PUBLIC_URL_HOSTNAME=$IP2
SSO_PG_DB_NAME=database_name_for_sso

# Default port is 9099. If changing, set both properties to the same value.
SSO_PUBLIC_URL_PORT=9099
SSO_TOMCAT_PORT=9099
# Set Tomcat TLS mode to DEFAULT to use HTTP access to apigee-sso.
SSO_TOMCAT_PROFILE=DEFAULT
SSO_PUBLIC_URL_SCHEME=http

# SSO admin user name. The default is ssoadmin.
SSO_ADMIN_NAME=ssoadmin
# SSO admin password using uppercase, lowercase, number, and special chars.
SSO_ADMIN_SECRET=Secret123

# Enable the ability to sign an authentication request with SAML SSO.
SSO_SAML_SIGN_REQUEST=y

# Path to signing key and secret from Create the TLS keys and certificates above.
SSO_JWT_SIGNING_KEY_FILEPATH=/opt/apigee/customer/application/apigee-sso/jwt-keys/privkey.pem
SSO_JWT_VERIFICATION_KEY_FILEPATH=/opt/apigee/customer/application/apigee-sso/jwt-keys/pubkey.pem

###########################################################
#                 Define External IDP                     #
# Use one of the following configuration blocks to        #
# define your IDP settings:                               #
#  - SAML configuration properties                     #
#  - LDAP Direct Binding configuration properties        #
#  - LDAP Indirect Binding configuration properties       #
###########################################################

INSERT_IDP_CONFIG_BLOCK_HERE (SAML, LDAP direct, or LDAP indirect, below)

# Configure an SMTP server so that the Apigee SSO module can send emails to users
SKIP_SMTP=n
SMTPHOST=smtp.example.com
SMTPUSER=smtp@example.com
# omit for no username
SMTPPASSWORD=smtppwd
# omit for no password
SMTPSSL=n
SMTPPORT=25
# The address from which emails are sent
SMTPMAILFROM="My Company <myco@company.com>"

    SAML 單一登入 (SSO) 設定屬性

    如果您要為 IdP 使用 SAML，請在設定檔 (如上所定義) 中使用以下設定屬性區塊：

    ## SAML Configuration Properties
# Insert this section into your base configuration file, as described previously.

# Name of SAML IDP. For example, okta or adfs.
SSO_SAML_IDP_NAME=okta
# Text displayed on the SSO sign-in page after being redirected by either the New or Classic Edge UI for SAML logins.
# Note: Installing SSO does not depend on the Edge UI or which version of the UI you are using.
SSO_SAML_IDP_LOGIN_TEXT="Please log in to your IDP"

# The metadata URL from your IDP.
# If you have a metadata file, and not a URL,
# see "Specifying a metadata file instead of a URL" below.
SSO_SAML_IDP_METADATA_URL=https://dev-343434.oktapreview.com/app/exkar20cl/sso/saml/metadata

# Determines whether to skip TLS validation for the URL specified
# by SSO_SAML_IDP_METADATA_URL.
# This is necessary if the URL uses a self-signed certificate.
# The default value is "n".
SSO_SAML_IDPMETAURL_SKIPSSLVALIDATION=n

# Keystore configuration details
# [Optional] Only specify KEYSTORE_TYPE if you are using something other than JKS. Values could be PKCS12 or BCFKS.
SSO_SAML_SERVICE_PROVIDER_KEYSTORE_PATH=/opt/apigee/customer/application/apigee-sso/saml/keystore.jks
SSO_SAML_SERVICE_PROVIDER_KEYSTORE_PASSWORD=Secret123
SSO_SAML_SERVICE_PROVIDER_KEYSTORE_ALIAS=service-provider-cert
SSO_SAML_SERVICE_PROVIDER_KEYSTORE_TYPE=JKS

# Requires that SAML responses be signed by your IDP.
# This property is enabled by default since release 4.50.00.05.
SSO_SAML_SIGNED_ASSERTIONS=y

    LDAP 直接繫結設定屬性

    如果您為 IdP 使用 LDAP 直接繫結，請在設定檔中使用以下設定屬性區塊，如上例所示：

    ## LDAP Direct Binding configuration
# Insert this section into your base configuration file, as described previously.

# The type of LDAP profile; in this case, "direct"
SSO_LDAP_PROFILE=direct

# The base URL to which SSO connects; in the form: "ldap://hostname_or_IP:port
SSO_LDAP_BASE_URL=LDAP_base_URL

# Attribute name used by the LDAP server to refer to the user's email address; for example, "mail"
SSO_LDAP_MAIL_ATTRIBUTE=LDAP_email_attribute

# Pattern of the user's DN; for example: =cn={0},ou=people,dc=example,dc=org
# If there is more than one pattern, separate with semicolons (";"); for example:
# =cn={0},ou=people,dc=example,dc=org;=cn={0},ou=people,dc=example,dc=com
SSO_LDAP_USER_DN_PATTERN=LDAP_DN_pattern

    LDAP 間接繫結設定屬性

    如果您要為 IdP 使用 LDAP 間接繫結，請在設定檔中使用下列設定屬性區塊，如上例所示：

    ## LDAP Indirect Binding configuration
# Insert this section into your base configuration file, as described previously.

# Type of LDAP profile; in this case, "indirect"
SSO_LDAP_PROFILE=indirect

# Base URL to which SSO connects; in the form: "ldap://hostname_or_IP:port
SSO_LDAP_BASE_URL=LDAP_base_URL

# DN and password of the LDAP server's admin user
SSO_LDAP_ADMIN_USER_DN=LDAP_admin_DN
SSO_LDAP_ADMIN_PWD=LDAP_admin_password

# LDAP search base; for example, "dc=example,dc=org"
SSO_LDAP_SEARCH_BASE=LDAP_search_base

# LDAP search filter; for example, "cn={0}"
SSO_LDAP_SEARCH_FILTER=LDAP_search_filter
     # LDAP 伺服器用來參照使用者電子郵件地址的屬性名稱，例如「mail」 SSO_LDAP_MAIL_ATTRIBUTE=LDAP_email_attribute

    安裝 Apigee 單一登入 (SSO) 模組

    建立金鑰並設定設定檔後，即可安裝 Apigee SSO 模組。

    安裝 Apigee SSO 模組的方式：

    1. 登入管理伺服器節點。該節點應已安裝 apigee-service，如安裝 Edge apigee-setup 公用程式一文所述。

      或者，您可以在其他節點上安裝 Apigee 單一登入模組。不過，該節點必須能夠透過通訊埠 8080 存取管理伺服器。

    2. 執行下列指令，安裝及設定 apigee-sso：
      /opt/apigee/apigee-setup/bin/setup.sh -p sso -f configFile

      其中 configFile 是您在前面定義的設定檔。

    3. 安裝 apigee-ssoadminapi.sh 公用程式，用於管理 apigee-sso 模組的管理員和機器使用者：
      /opt/apigee/apigee-service/bin/apigee-service apigee-ssoadminapi install
    4. 請登出殼層，然後重新登入，將 apigee-ssoadminapi.sh 公用程式新增至路徑。

    指定中繼資料檔案，而非網址

    如果您的 IdP 不支援 HTTP/HTTPS 中繼資料網址，您可以使用中繼資料 XML 檔案設定 Apigee 單一登入 (SSO)。

    如要使用中繼資料檔案，而非網址來設定 Apigee 單一登入 (SSO)：

    1. 將 IDP 中的中繼資料 XML 內容複製到 Apigee SSO 節點的檔案中。例如，將 XML 複製到：
      /opt/apigee/customer/application/apigee-sso/saml/metadata.xml
    2. 將 XML 檔案的擁有權變更為「apigee」使用者： 
      chown apigee:apigee /opt/apigee/customer/application/apigee-sso/saml/metadata.xml
    3. 將 SSO_SAML_IDP_METADATA_URL 的值設為絕對檔案路徑：
      SSO_SAML_IDP_METADATA_URL=file:///opt/apigee/customer/application/apigee-sso/saml/metadata.xml

      您必須在檔案路徑前方加上「file://」，接著是從根目錄 (/) 開始的絕對路徑。