Integrate OKTA with ESA for SAML Authentication

Introduction

This document describes the integration of Email Security Appliance (ESA) and OKTA for Security Assertion Markup Language (SAML) authentication.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• OKTA, more information can be found at Understand SAML | Okta Developer
• General Public Key Infrastructure (PKI) Knowledge

Components Used

The information in this document is based on these software and hardware versions:

• Active Directory
• Cisco Email Security Appliance 13.x.x or later versions
• OKTA

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

Background Information

OKTA is a two-factor authentication service provider that adds a layer of security to SAML authentication.

SAML is a federation method for authentications. It was developed to give secure access and separate the identity provider and service provider.

The Identity Provider (IdP) is the Identity that stores all the information of users in order to permit the authentication (which means OKTA has all the user information to confirm and approve an authentication request).

The Service Provider (SP) is the ESA.

ESA OKTA SAML process

Configure

OKTA Configuration

1. Create OKTA  Application. Then navigate to Applications.

Okta get started

2. Click  Create App Integration.

Okta integration process

3. Choose  SAML 2.0  as shown in the image.

Okta SAML 2.0

4. Edit the configuration for your integration and configure a name to the integration, logo, and options about visibility. Click  nextas shown in the image.

Okta application name

5. In this step, you configure the most important part of the IdP in order to permit the users to authenticate and send the correct parameters in SAML.

Okta configuration

• Single sign-on URL: The location where the SAML assertion is sent with HTTP POST. This is often referred to as the SAML Assertion Consumer Service (ACS) URL for your application.

   This is used in the image for Steps 5 and 6 about how OKTA works.

• Use this for Recipient URL and Destination URL: Mark that option.
• Audience URI (SP Entity ID): The application-defined unique identifier that is the intended audience of the SAML assertion. This is most often the SP Entity ID of your application. Configure the same as a Single sign-on URL.
• Application Username: Determines the default value for a user application username. The application username is used for the assertion subject statement. Use Email.

For this, you must set up the same ESA from  System Administration > SAML > Service Provider Settings.

ESA SAML settings

Note: Remember Sign-on URL and Audience URI must be the same as your ESA login URL.

• Name ID format: Identifies the SAML processing rules and constraints for the assertion subject statement. Use the default value of 'Unspecified' unless the application explicitly requires a specific format. The name ID format is unspecified, and the ESA does not require a specified ID format.

ESA name ID format

6. For the next step, configure how the ESA searches the parameters received by the IdP in order to make a match for the users selected in the group.

In the same windows of Step 5., navigate to  Group Attribute Statements and configure the next parameters in order to permit authentication.

OKTA group attribute statements

• Name: Configure the word you use in the ESA for  External Authentication Settigns via SAML (Case Sensitive).
• Filter: Configure  equals and the name of the group which you want to use to make a match in the ESA Device for  External Authentication Settings.

(The next image is just an example of how it looks when you finish the configuration part of ESA).

ESA SAML external authentication configuration

7. Only for the verification step, check the preview of SAML Assertion.

OKTA metadata info

After that, you can click  next.

8. In order to finalize the application in OKTA, you can configure the parameters as shown in the next image.

Okta finalizing app integration

Click the  Finish button as in the image.

9. In order to finalize the configuration in OKTA you must navigate to your application and choose assignments and the users or groups which you permit the authentication in your application.

OKTA assigning user groups

10. The result is as shown in this image:

OKTA assigned groups

ESA Configuration

1. Configure SAML Settings. Then navigate to  System Administration > SAML.

ESA SAML configuration

2. Choose  Add Service Provider as in the earlier image.

ESA SAML settings

• Entity ID: The Service Provider Entity ID is used to uniquely identify a service provider. The format of the Service Provider Entity ID is typically a URI.

Note: Remember this parameter must be equal in ESA and OKTA.

ESA Entity ID

• Assertion Consumer URL: The Assertion Consumer URL is the URL that the Identity Provider must send the SAML assertion after successful authentication. The URL that you use to access the web interface of your appliance must be the same as the Assertion Consumer URL. You need this value while you configure the service provider settings on the identity provider.

Note: Remember this parameter must be equal on ESA and OKTA.

ESA Assertion URL

• SP Certificate: This is the certificate for the hostname for which you have configured the assertion consumer URL.

ESA certificate

It is best if you use  openssl  on Windows or Linux. If you want to configure a self-signed certificate, you can do that with the next steps or you can use your certificate:

1. Create the private key. This helps to enable encryption or decryption.

openssl genrsa -out domain.key 2048

2. Create a Certificate Signing Request (CSR).

openssl req -key domain.key -new -out domain.csr

3. Create the self-signed certificate.

openssl x509 -signkey domain.key -in domain.csr -req -days 365 -out domain.crt

If you want more days, you can change the value after  -days .

After that, you have the certificate and keys to upload on the ESA in the option  upload certificate and key.

(Optional) From PEM format to PKCS#12 format.

openssl pkcs12 -inkey domain.key -in domain.crt -export -out domain.pfx

For organization details, you can fill it as you want and click submit.

3. Navigate to System Administration > SAML  and choose  Add Identity Provider.

ESA SAML IdP configuration

ESA IdP settings configuration

In this step there are two options, you can upload that information manually or via an  XML file.

In order to do that, you must navigate to your OKTA Application and find the  IDP metadata .

OKTA IdP metadata

Scroll down in the OKTA Sign On option and find the option SAML Setup.

OKTA SAML metadata instructions

Choose  View SAML setup instructions. Then scroll down to the  optional  step.

OKTA IdP metadata information

Copy and paste all the information in a notepad, save it as  IDP.xml, and upload it to the option  Import IDP metadata in the ESA for  Identity Provider.

ESA metadata import

After that, click submit and you can see an overview of your configuration like this:

ESA SAML configuration overview

Now that SAML is configured, you must configure the external authentication.

1. Navigate to  System Administration > Users. Change the configuration for external authentication to use SAML.

ESA external authentication configuration

Choose Edit Global Settings and configure the next parameters equal to the parameters configured in OKTA for the group.

ESA external authentication configuration

OKTA external authentication configuration

After that click  Commit.

Verify

In order to verify, click  Use Single On.

ESA authentication via SSO

After you click the  Use Single Sign-On button, you are redirected to the IdP service (OKTA) and you must provide the username and password to authenticate, or, if you have fully integrated with your domain, you are automatically authenticated in the ESA.

ESA OKTA authentication

After you enter your OKTA login credentials, you are redirected to the ESA and authenticated as in the next image.

ESA authentication successful

Troubleshoot

There is currently no specific troubleshooting information available for this configuration.

Related Information

• Understanding SAML
• Technical Support & Documentation - Cisco Systems