Integrate Okta with ZTP using SAML

Prerequisites

This integration requires the following:

Okta Identity Cloud account with admin credentials
An active ZTP account, accessible using the Bootstrap Identity provided by AppGate
A test user account on your Okta cloud directory with at least the following attributes configured:
- email, for example: joe.smith@mycompany.com
- firstName, for example: Joe
- lastName, for example: Smith

Step 1: Add a new application in Okta

Log in to your Okta admin account. Confirm that you are on the Admin UI, not the end-user dashboard.
In the left menu, go to Applications and click Create App Integration.

On the sign-in method list, select SAML 2.0 and click Next.

On the Create SAML Integration page, enter an app name, for example: AppGate ZTP. Click Next.

Step 2: Configure the application

On the Configure SAML tab, enter the following values in the General section:

In the Single Sign-On URL field, enter a placeholder URL, for example: https://example.com. You will replace this value after completing the configuration.
In the Audience URI field, enter the Audience value to use in ZTP. For this example, use okta-idp.
Leave all other fields at their default values.

Step 3: Map attributes

Create application attributes and specify which SAML attributes map to the ID token. Use the attributes configured for your test user account.

The following table shows the attribute mapping for this example:

Name	Value
`firstName`	`user.firstName`
`lastName`	`user.lastName`
`email`	`user.email`
`username`	`user.email`

Note the attribute names you create. You will need them to complete the configuration form.

Click Next.

NOTE
Okta displays a Feedback tab before completing the configuration. Select the option that describes your situation and click Finish.

Step 4: Retrieve IdP metadata

On the Sign On tab of your new application, scroll down to SAML Signing Certificates.
Click View SAML Setup Instructions to display the metadata required to configure your IdP in ZTP.

Record the following values:
- Identity Provider Single Sign-On URL
- Identity Provider Issuer
- X.509 Certificate (click Download Certificate to save the file)

You can also save the IdP metadata as an XML file and upload it when completing the configuration form.

Step 5: Configure the IdP in ZTP

In ZTP, go to Settings > Identity Providers in the left menu.
Click Add New and select SAML provider.
Complete the form using the following values (required fields are marked with an asterisk):

Field	Description
Name*	`OKTA – SAML`
Audience*	`okta-idp`
XML Metadata File	IdP metadata provided by Okta, saved as an XML file
SSO URL*	If you uploaded the XML file, this field populates automatically. Otherwise, enter the Identity Provider Single Sign-On URL recorded in Step 4.
Issuer*	If you uploaded the XML file, this field populates automatically. Otherwise, enter the Identity Provider Issuer recorded in Step 4.
Public Certificate	If you uploaded the XML file, this field populates automatically. Otherwise, enter the X.509 Certificate recorded in Step 4.
Email Attribute*	`email`
First Name Attribute*	`firstName`
Last Name Attribute*	`lastName`
Username Attribute*	`email`

Copy the ACS URL from the ZTP form by clicking the copy to clipboard button.

In Okta, return to General SAML Settings and replace the placeholder URL (https://example.com) in the Single Sign-On URL field with the ACS URL you copied.
Click Save and test the integration.

NOTE
Common integration errors include missing fields and mismatched attribute names between the Okta SAML app and the AppGate ZTNA configuration. Verify attribute mappings carefully before saving.

Documentation Index