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:
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
- Create OKTA
Application
. Then navigate to Applications
.
Okta get started
- Click
Create App Integration
.
Okta integration process
- Choose
SAML 2.0
as shown in the image.
Okta SAML 2.0
- Edit the configuration for your integration and configure a name to the integration, logo, and options about visibility. Click
next
as shown in the image.
Okta application name
- 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
- 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
- Only for the verification step, check the preview of SAML Assertion.
OKTA metadata info
After that, you can click next
.
- 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.
- 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
- The result is as shown in this image:
OKTA assigned groups
ESA Configuration
- Configure SAML Settings. Then navigate to
System Administration > SAML
.
ESA SAML configuration
- 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
.
Note: Remember, by best practices, you must not put more than 5 years for the certificates.
After that, you have the certificate and keys to upload on the ESA in the option upload certificate and key
.
Note: If you want to upload the certificate in PKCS #12 format, it is possible to create it after Step 3.
(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.
- 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.
- Navigate to
System Administration > Users
. C
hange 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