You're viewing **Apigee Edge** documentation.
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/publish/portal/portal-identity-provider). info
> [!NOTE]
> This is the **beta release of self-service SAML** . To learn more about the Apigee release phases, see [Apigee Release Stages](https://docs.apigee.com/release/release-stages). Self-service SAML is available in the Edge UI; it is not available in the Classic Edge UI.
This section describes how to enable SAML for Apigee Edge so that authentication for members of your organization(s) can be delegated to your own identity service. For an overview of SAML and identity zone management in Edge, see [SAML overview](https://docs.apigee.com/api-platform/system-administration/saml-overview).
**Video:** Watch a short video to learn about how to access Apigee Edge APIs before and after enabling single sign-on (SSO) using SAML.
> [!NOTE]
>
> **Related information:**
>
> - To enable SSO using SAML for integrated portals, see [Configure the SAML identity provider](https://docs.apigee.com/api-platform/publish/portal/portal-identity-provider#configure_the_saml_identity_provider).
> - To learn about automating the token generation process by using machine users, see [Automate the token generation process](https://docs.apigee.com/api-platform/system-administration/automating-tasks).
## About the zoneadmin role
You must be a **zoneadmin** to manage identity zones in Edge. The zoneadmin role provides full CRUD procedures for managing identity zones only.
To have the zoneadmin role assigned to your Apigee Edge account, contact [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support).
## Before you begin
Before you begin, obtain the following information **from your third-party SAML identity provider**:
- Certificate for signature verification (PEM or PKCSS format). If necessary, [convert an x509 certificate to PEM format](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#x509)
- Configuration information (defined in the following table)
| Configuration | Description |
|---|---|
| Sign-in URL | URL to which users are redirected to sign-in to the SAML identity provider. |
| Sign-out URL | URL to which users are redirected to sign-out of the SAML identity provider. |
| IDP entity ID | Unique URL for this identity provider. For example: `https://idp.example.com/saml` |
In addition, **configure your third-party SAML identity provider** with the following settings:
- Ensure that the `NameID` attribute is mapped to the user's email address. The user's email address serves as the unique identifier of the Edge developer account. The following shows an example using Okta, where the **Name ID format** field defines the `NameID` attribute.
- (Optional) Set the authenticated session duration to 15 days to match the duration of the Edge UI authenticated session duration.
## Explore the Edge SSO Zone Administration page
Manage identity zones for Edge using the Edge SSO Zone Administration page. The Edge SSO Zone Administration page exists **outside of your organization** enabling you to assign multiple organizations to the same identity zone.
To access the Edge SSO Zone Administration page:
1. Sign in to using an **Apigee Edge user account** with [zoneadmin privileges](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#zoneadmin).
> [!NOTE]
> **Note:** You cannot access the Edge SSO Zone Administration page if you sign in using your company single sign-on (SSO) credentials that are processed through your company's third-party SAML identity provider. You must use your Edge user account.
>
> If you do not have an Edge user account or
> are not sure, [create an Apigee Edge account](https://docs.apigee.com/api-platform/get-started/creating-apigee-edge-account). If your Edge user account already exists, you will be notified.
> If you have an Apigee Edge user account but have forgotten your password, see [Reset your password](https://docs.apigee.com/api-platform/get-started/sign-in-manage-account#password).
2. Select **Admin \> SSO** in the left navigation bar.
> [!NOTE]
> **Note:** If you signed in to Edge using an Edge user account with zoneadmin privileges but do not see Admin \> SSO in the left navigation bar, you may have encountered a [known issue](https://docs.apigee.com/release/known-issues#sso) that incorrectly causes the link to be removed after you [connect an organization to an identity zone](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#connect-org-zone). As a workaround, navigate to the Edge SSO Zone Administration page directly using the following URL:
The Edge SSO Zone Administration page displays (outside of your organization).
As highlighted in the figure, the Edge SSO Zone Administration page enables you to:
- View all identity zones
- View login URL for each zone
- [Add](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#add) and [delete](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#delete) an identity zone
- [Configure the SAML identity provider](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#configure)
- [Connect an Edge organization to an identity zone](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#connect-org-edge)
- [Delete a portal identity zone](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#delete)
## Add an identity zone
You can add a maximum of **10** identity zones.
To add an identity zone:
1. [Access the Edge SSO Zone Administration page](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#explore-ui).
2. In the Identity zones section, click **+**.
3. Enter a name and description for the identity zone.
The zone name must be unique across all Edge organizations.
> **Note**: Apigee reserves the right to remove any zone name that is deemed unjustifiable.
4. Enter a string to append to the subdomain, if required.
For example, if `acme` is the zone name, you may want to define a production zone, `acme-prod` and a test zone, `acme-test`.
To create the production zone enter **prod** as the subdomain suffix. In this case, the URL used to access the Edge UI would be: `acme-prod.apigee.com`, as described in [Access your organization using the identity zone](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#identity).
> **Note**: The appended subdomain suffix must be unique across all your zones.
5. Click **OK**.
6. [Configure the SAML identity provider](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#configure).
## Configure the SAML identity provider
Configure the SAML identity provider by performing the following steps:
1. [Configure SAML settings](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#saml-settings).
2. [Upload a new certificate](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#cert).
If necessary, [convert an x509 certificate to PEM format](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#x509).
### Configure SAML settings
To configure the SAML settings:
1. [Access the Edge SSO Zone Administration page](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#explore-ui).
2. Click the row of the identity zone for which you want to configure the SAML identity provider.
3. In the **SAML Settings** section, click .
4. Click **Copy** adjacent to the **SP metadata URL** .
5. Configure your SAML identity provider using the information in the service provider (SP) metadata file.
For some SAML identity providers, you will be prompted only for the metadata URL. For others, you will need to extract specific information from the metadata file and enter it into a form.
In the latter case, paste the URL into a browser to download the SP metadata file and extract the required information. For example, the entity ID or sign-in URL can be extracted from the following elements in the SP metadata file:
> **Note** : In the SP metadata file, the sign-in URL is referred to as the `AssertionConsumerService` (ACS) URL.
- ``
- ``
> **Note** : If required by your SAML identity provider, set the audience restriction to zoneID.apigee-saml-login, which you can copy from the `entityID` element in the SP metadata file (shown above).
6. Configure the SAML settings for the **SAML identity provider**.
In the **SAML Settings** section, edit the following values *obtained from your SAML identity provider metadata file*:
| SAML setting | Description |
|---|---|
| Sign-in URL | URL to which users are redirected to sign-in to the SAML portal identity provider. For example: `https://dev-431871.oktapreview.com/app/googledev431871_devportalsaml_1/exkhgdyponHIp97po0h7/sso/saml` |
| Sign-out URL | URL to which users are redirected to sign-out of the SAML portal identity provider. **Note**: If your SAML identity provider does not provide a sign-out URL, leave this field blank. In this case, it will be set to the same value used for the sign-in URL. |
| IDP entity ID | Unique URL for the SAML identity provider. For example: `http://www.okta.com/exkhgdyponHIp97po0h7` **Note:** Depending on the SAML identity provider, this field may be named differently, such as `Entity ID`, `SP Entity ID`, `Audience URI`, and so on. |
> **Note**: Apigee SSO does not support the following 2 features:
> - Automatic IDP certificate refresh by using an IDP metadata URL and downloading the metadata periodically to update changes on the Apigee SSO Service Provider side.
> - Uploading an entire IDP Metadata xml file or using an IDP Metadata URL for automatic IDP configuration.
>
>
>
7. Click **Save**.
Next, [upload a certificate](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#cert) in PEM or PKCSS format, as described in the next section.
### Upload a new certificate
To upload a new certificate:
1. Download the certificate for signature verification from your SAML identity provider.
> **Note** : The certificate must be in PEM or PKCSS format. If necessary, [convert an x509 certificate to PEM format](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#x509).
2. [Access the Edge SSO Zone Administration page](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#explore-ui).
3. Click the row of the identity zone for which you want to upload a new certificate.
4. In the **Certificate** section, click .
5. Click **Browse** and navigate to the certificate in your local directory.
6. Click **Open** to upload the new certificate.
The Certificate information fields are updated to reflect the selected certificate.
7. Verify that the certificate is valid and has not expired.
8. Click **Save**.
### Convert an x509 certificate to PEM format
If you download an x509 certificate, you need to convert it to PEM format.
> [!NOTE]
> **Note:** If you have a PEM-formatted file with an extension other than `.pem`, open the file and save it using the `.pem` extension. You may encounter problems if you simply rename the file.
To convert an x509 certificate to PEM format:
1. Copy the contents of the `ds:X509Certificate element` from the SAML identity provider metadata file and paste it into your favorite text editor.
2. Add the following line at the top of the file:
`---BEGIN CERTIFICATE---`
3. Add the following line at the bottom of the file:
`---END CERTIFICATE---`
4. Save the file using a `.pem` extension.
The following provides an example of the PEM file contents:
---BEGIN CERTIFICATE---
MIICMzCCAZygAwIBAgIJALiPnVsvq8dsMA0GCSqGSIb3DQEBBQUAMFMxCzAJBgNV
BAYTAlVTMQwwCgYDVQQIEwNmb28xDDAKBgNVBAcTA2ZvbzEMMAoGA1UEChMDZm9v
MQwwCgYDVQQLEwNmb28xDDAKBgNVBAMTA2ZvbzAeFw0xMzAzMTkxNTQwMTlaFw0x
ODAzMTgxNTQwMTlaMFMxCzAJBgNVBAYTAlVTMQwwCgYDVQQIEwNmb28xDDAKBgNV
BAcTA2ZvbzEMMAoGA1UEChMDZm9vMQwwCgYDVQQLEwNmb28xDDAKBgNVBAMTA2Zv
bzCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAzdGfxi9CNbMf1UUcvDQh7MYB
OveIHyc0E0KIbhjK5FkCBU4CiZrbfHagaW7ZEcN0tt3EvpbOMxxc/ZQU2WN/s/wP
xph0pSfsfFsTKM4RhTWD2v4fgk+xZiKd1p0+L4hTtpwnEw0uXRVd0ki6muwV5y/P
+5FHUeldq+pgTcgzuK8CAwEAAaMPMA0wCwYDVR0PBAQDAgLkMA0GCSqGSIb3DQEB
BQUAA4GBAJiDAAtY0mQQeuxWdzLRzXmjvdSuL9GoyT3BF/jSnpxz5/58dba8pWen
v3pj4P3w5DoOso0rzkZy2jEsEitlVM2mLSbQpMM+MUVQCQoiG6W9xuCFuxSrwPIS
pAqEAuV4DNoxQKKWmhVv+J0ptMWD25Pnpxeq5sXzghfJnslJlQND
---END CERTIFICATE---
## Connect an Edge organization to an identity zone
**Before you connect an Edge organization to a SAML-enabled identity zone**, you should have already added all existing organization users to your SAML identity provider. All users require an email address that is returned to the Edge UI as part of the SAML authentication process. After you enable SAML, existing Edge users will not be able to sign in to the Edge UI until they are added to the SAML identity provider.
To connect an Edge organization to an identity zone:
1. [Access the Edge SSO Zone Administration page](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#explore-ui).
2. In the **Organization mapping** section, select an identity zone in the **Identity zone** drop-down menu associated with the organization you want to assign to a zone.
Select **None (Apigee default)** to enable basic authentication for the organization.
3. Click **Confirm** to confirm the change.
## Access your organization using the identity zone
The URL that you use to access the Edge UI is defined by the name of your identity zone:
```
https://zonename.apigee.com
```
Similarly, the URL that you use to access the Classic Edge UI is as follows:
```
https://zonename.enterprise.apigee.com
```
For example, Acme Inc. wants to use SAML and chooses "acme" as its zone name. Acme
Inc. customers then access the Edge UI with the following URL:
```
https://acme.apigee.com
```
The zone identifies the Edge organizations that support SAML. For example, Acme Inc. has three
orgs: OrgA, OrgB and OrgC. Acme can decide to add all organizations to the SAML zone, or only a
subset. The remaining organizations continue to use Basic Auth or OAuth2 tokens generated from
Basic Auth credentials.
You can define multiple identity zones. All zones can then be configured to use the same
identity provider.
For example, Acme might want to define a production zone, "acme-prod", containing OrgAProd and
OrgBProd, and a test zone, "acme-test", containing OrgATest, OrgBTest, OrgADev, and OrgBDev.
You then use the following URLs to access the different zones:
```
https://acme-prod.apigee.com
https://acme-test.apigee.com
```
## Register Edge users with SAML authentication
> [!NOTE]
> You must be an organization administrator to perform this step.
After you enable SAML for an organization, you need to register the SAML users that are
not already registered with your organization. For more information, see [Manage organization users](https://docs.apigee.com/api-platform/system-administration/managing-organization-users).
## Update scripts to pass OAuth2 access tokens
After you enable SAML, Basic Auth is disabled for the Edge API. All
scripts (Maven scripts, shell scripts, `apigeetool`, and so on) that rely on Edge
API calls supporting Basic Auth will no longer work. You must update API calls and
scripts that use Basic Auth to pass OAuth2 access tokens in the Bearer header. See [Using SAML with the Edge API](https://docs.apigee.com/api-platform/system-administration/using-saml).
> [!NOTE]
> The URL for the Edge API is not affected by enabling SAML authentication. You still access the Edge API at:
>
> ```
> https://api.enterprise.apigee.com/v1
> ```
## Delete an identity zone
> [!WARNING]
> Deleting an identity zone permanently removes all custom zone configuration. This action cannot be undone. You cannot delete a zone that has connected organizations.
To delete a identity zone:
1. [Access the Edge SSO Zone Administration page](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge#explore-ui).
2. Position your cursor over the row associated with the identity zone you want to delete to display the actions menu.
3. Click .
4. Click **Delete** to confirm the delete operation.
## Sign out of the Edge SSO Zone Administration page
Because you manage Edge identity zones outside of your organization, you will need to sign out of the Edge SSO Zone Administration page and then sign-in to your organization to be able to access other features of Apigee Edge.
