Contents
Introduction
Prerequisites
Configure Certificate Values
Configure Microsoft Azure AD
Create custom Web application
Configure custom Web application
Create the Manifest
Finding the Tenant ID
Final review of values to be saved
Configure Mailbox Settings on ESA
Introduction
This document describes how to setup and configure Microsoft Azure AD and Office 365 to work
with Cisco Email Security Appliance (ESA).
Prerequisites
The information in this document is based on these software and hardware versions:
AsyncOS for Email Security 9.9.5-039 (Bellagio), or newer.
This document also requires the following:
●
●
●
●
●
●
Office 365 account subscription (Please make sure that your Office 365 account subscription
includes access to email, such as an Enterprise E3 or Enterprise E5 account.)
Microsoft Azure account
Both the Office 365 and Microsoft Azure AD accounts are tied properly to an active
[email protected] email address, and you are able to send and receive emails via that
domain and account.
Access to Windows PowerShell, usually administered from a Windows Server.
Domain active Public/Private certificate and the private key used to sign the certificate, or the
ability to create a Public/Private certificate and ability to save the private key used to sign the
certificate.
Configure Certificate Values
Log-in to Windows, and using PowerShell complete the following commands to map and obtain
$keyid, $base64Thumbprint, and $base64Value:
1. $cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
2. $cer.Import('C:\path_to_cert\PEM_certificate.crt')
3. $bin = $cer.GetRawCertData()
4. $base64Value = [System.Convert]::ToBase64String($bin)
5. $bin = $cer.GetCertHash()
6. $base64Thumbprint = [System.Convert]::ToBase64String($bin)
7. $keyid = [System.Guid]::NewGuid().ToString()
8. echo
9. echo
10. echo $keyid
For the purpose of this document, the example configuration will be based on
"esatest.onmicrosoft.com." The commands as run via PowerShell should be similar to the
following example:
Windows PowerShell
Copyright (C) 2014 Microsoft Corporation. All rights reserved.
PS C:\Users\Administrator> cd .\Desktop
PS C:\Users\Administrator\Desktop>
PS C:\Users\Administrator\Desktop> $cer = New-Object
System.Security.Cryptography.X509Certificates.X509Certificate2
PS C:\Users\Administrator\Desktop>
$cer.Import('C:\Users\Administrator\Desktop\esatest.onmicrosoft.com_PEM.crt')
PS C:\Users\Administrator\Desktop> $bin = $cer.GetRawCertData()
PS C:\Users\Administrator\Desktop> $base64Value = [System.Convert]::ToBase64String($bin)
PS C:\Users\Administrator\Desktop> $bin = $cer.GetCertHash()
PS C:\Users\Administrator\Desktop> $base64Thumbprint = [System.Convert]::ToBase64String($bin)
PS C:\Users\Administrator\Desktop> $keyid = [System.Guid]::NewGuid().ToString()
PS C:\Users\Administrator\Desktop>
PS C:\Users\Administrator\Desktop> echo $base64Value
MIIEhjCCA26gAwIBAgIFIBYDKAEwDQYJKoZIhvcNAQEFBQAwgZcxCzAJBgNVBAYTAlVTMRcwFQYDVQQIEw5Ob3J0aCBDYXJv
bGluYTEMMAoGA1UEBxMDUlRQMQ4wDAYDVQQKEwVDaXNjbzEMMAoGA1UECxMDVEF
DMSAwHgYDVQQDExdlc2F0ZXN0Lm9ubWljcm9zb2Z0LmNvbTEhMB8GCSqGSIb3DQEJARYScm9ic2hlcndAY2lzY28uY29tMB4
XDTE2MDMyODE0NTYwMFoXDTE3MDMyODE0NTYwMFowgZcxCzAJBgNVBAYTAlVTMR
cwFQYDVQQIEw5Ob3J0aCBDYXJvbGluYTEMMAoGA1UEBxMDUlRQMQ4wDAYDVQQKEwVDaXNjbzEMMAoGA1UECxMDVEFDMSAwHg
YDVQQDExdlc2F0ZXN0Lm9ubWljcm9zb2Z0LmNvbTEhMB8GCSqGSIb3DQEJARYSc
m9ic2hlcndAY2lzY28uY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzB6r/MtfKwG+86eHzdhYklCdyyT+j
/j/+5yM6W9K8rqhW0FFT8et0vjp402sI8wg34m0LckFkvbakP6w3mam1hfsocj5
axu1raQeZgY/dkyHkTE26vt6rpy5g611TLloTZGlF0nkzT5Gs+zLOuhPHaT1DMU70LCXh8CHs2cLsczpDWfb2OsHxTVlISVJ
qjdhYHYM7vC6VNffMYIYxAE90ZEl9QHOdU5n7spPyxUP0fp8z8gHsQ7HhRTsCNg
WbFyYb0Ib1RTOznmzMXaSOnRKYaIpkLkOSwZurT0wyGJd+TZSw+RgsX1vKJNmKih/ii1YLvMKyq+T7PJbPDwhU8uAGQIDAQA
Bo4HWMIHTMAwGA1UdEwQFMAMBAf8wCwYDVR0PBAQDAgWgMHAGA1UdJQRpMGcGCC
sGAQUFBwMBBggrBgEFBQcDAgYIKwYBBQUHAwQGCisGAQQBgjcCARUGCisGAQQBgjcCARYGCisGAQQBgjcKAwEGCisGAQQBgj
cKAwMGCisGAQQBgjcKAwQGCysGAQQBgjcKAwQBMEQGA1UdEQQ9MDuCF2VzYXRlc
3Qub25taWNyb3NvZnQuY29tgSByb2JzaGVyd0Blc2F0ZXN0Lm9ubWljcm9zb2Z0LmNvbTANBgkqhkiG9w0BAQUFAAOCAQEAR
/F2tqxBriYK8fEt0swLZQYYq+JWma6MxNjODXoSj4SWKxFv8Vb5LwE7goxi9625
f31o1kADPcK3ml0UarT35hH6f9abZSXm3mj3zMnuK5nW2ypDCVUiuA2C5l+woEubSmvn980GHuSXOqfLMPtniUMTubp+SICD
rtCse2l2GkE1OCRmxF1wtwgrCatwyoRxnDA5U4VyWQnyd7dL8eBOIhZMg1sFU6Z
xg8NKtiyEzV99OJ6+DOkMn1fQOXDBPkgHI1mzFmVQogUGDcVbvpsd1roT4JcsUebmAdGvCek49HtHtlo6+aBLHQH+pX6pUqj
1+guS0X0FMmhkDJOTyZWnAQ==
PS C:\Users\Administrator\Desktop>
PS C:\Users\Administrator\Desktop> echo $base64Thumbprint
3DLH9EqnuMPdkMrUj/Fa1jxa+XU=
PS C:\Users\Administrator\Desktop>
PS C:\Users\Administrator\Desktop> echo $keyid
89ed56fc-7fae-4d10-ad63-7ddaeaf8e737
Save the output you receive for $keyid, $base64Thumbprint, and $base64Value, as these values
will be used later in the Create the Manifest section of this document. The $base64Thumbprint
will be used during the ESA configuration.
Note: The $base64Value is required to be edited to be a single line.
Save the Public Key Certificate (.crt) and Private Key used to sign the certificate (.pem) locally.
The Private key will be needed during the ESA configuration.
Configure Microsoft Azure AD
Create custom Web application
1. Log-in to Microsoft Azure.
2. Navigate to ALL ITEMS.
3. Click on the resource name for your domain.
4. From the tool tabs for the resource name,
select APPLICATIONS.
5. From the bottom toolbar, select ADD:
6. When presented "What do you want to do?", select Add an application my organization is
developing.
7. Create with an appropriate name, and leave the Type as Web Application and/or Web API,
and click the arrow to continue:
8. To finish adding the custom Web application, enter the following values for your domain, and
click the check to finish: SIGN-ON URL:
https://<your.domain.com>/ManualRegistrationAPP ID URI:
https://<your.domain.com>
9. From Microsoft, regarding App ID URI: "Because the App ID URI is a logical identifier, it does
not need to resolve to an Internet address. It is presented by your app when sending a single
sign-on request to Azure AD. Azure AD identifies your app and sends the sign-on response
(a SAML token) to the Reply URL that was provided during app registration. Use the App ID
URI value to set the wtrealm property (for WS-Federation) or the Issuer property (for SAMLP) when making a sign-in request. The App ID URI must be a unique value in your
organization's Azure AD."
Note: "When enabling an app for external users, the value of the App ID URI of the app must
be an address in one of your directory's verified domains. As a result, it cannot be a URN.
This safeguard prevents other organizations from specifying (and taking) unique property
that belongs to your organization. During development, you can change your App ID URI to a
location in your organization's initial domain (if you haven't verified a custom/vanity domain),
and update your app to use this new value. The initial domain is the 3-level domain that you
create during sign up, such as contoso.onmicrosoft.com."
Configure custom Web application
1. Once the custom Web application has been created, you are automatically navigated into the
custom Web application itself. From here, in the tool tabs,
select CONFIGURE:
2. From this screen, you can view the Sign-on URL and other configuration details as created.
Note: The Client ID is listed on this screen. This value
3. From this same screen for the custom Web application configuration, scroll to the bottom and
click Add
application:
4. Select Office 365 Exchange Online and click the check to continue.
5. For the Office 365 Exchange Online, select Read and write mail in all mailboxes, Send
mail as any user, and Use Exchange Web Services with full
access...:
6. For the Office 365 Exchange Online, select Send mail as a user, Read and write user
mail, Read user mail, and Access mailboxes as the signed-in user via
Exchange:
7. Click Save from the bottom toolbar to save all work and configuration for the custom Web
application:
Create the Manifest
1. Once the custom Web application has completed saving and updating, click MANAGE
MANIFEST > Download Manifest from the bottom
toolbar:
2. Navigate through the responses, and save the Web application manifest in .json format to
your local computer.
3. Find this .json file and open this .json file with a text editor. (Preferable Notepad++, Atom,
etc.)
4. Search and find the "keyCredentials" line.
5. You will be replacing this single line with the following multiple lines, and customize using the
earlier identified credentials from the Configure Certificate Values section
($base64Thumbprint, $keyid, and $base64Value):
6. "keyCredentials": [
{
"customKeyIdentifier": "$base64Thumbprint",
"keyId": "$keyid",
"type": "AsymmetricX509Cert",
"usage": "Verify",
"value": "$base64Value"
}
],
7. As noted earlier, when entering the $base64Value, this is required to be edited to be a single
line value.
8. Continuing with the example as created from the start of this document, the modified
keyCredentials will be as follows:
9. "keyCredentials": [
{
"customKeyIdentifier": "3DLH9EqnuMPdkMrUj/Fa1jxa+XU=",
"keyId": "89ed56fc-7fae-4d10-ad63-7ddaeaf8e737",
"type": "AsymmetricX509Cert",
"usage": "Verify",
"value":
"MIIEhjCCA26gAwIBAgIFIBYDKAEwDQYJKoZIhvcNAQEFBQAwgZcxCzAJBgNVBAYTAlVTMRcwFQYDVQQIEw5Ob3J0aC
BDYXJvbGluYTEMMAoGA1UEBxMDUlRQMQ4wDAYDVQQKEwVDaXNjbzEMMAoGA1UECxMDVEFDMSAwHgYDVQQDExdlc2F0Z
XN0Lm9ubWljcm9zb2Z0LmNvbTEhMB8GCSqGSIb3DQEJARYScm9ic2hlcndAY2lzY28uY29tMB4XDTE2MDMyODE0NTYw
MFoXDTE3MDMyODE0NTYwMFowgZcxCzAJBgNVBAYTAlVTMRcwFQYDVQQIEw5Ob3J0aCBDYXJvbGluYTEMMAoGA1UEBxM
DUlRQMQ4wDAYDVQQKEwVDaXNjbzEMMAoGA1UECxMDVEFDMSAwHgYDVQQDExdlc2F0ZXN0Lm9ubWljcm9zb2Z0LmNvbT
EhMB8GCSqGSIb3DQEJARYScm9ic2hlcndAY2lzY28uY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAz
B6r/MtfKwG+86eHzdhYklCdyyT+j/j/+5yM6W9K8rqhW0FFT8et0vjp402sI8wg34m0LckFkvbakP6w3mam1hfsocj5
axu1raQeZgY/dkyHkTE26vt6rpy5g611TLloTZGlF0nkzT5Gs+zLOuhPHaT1DMU70LCXh8CHs2cLsczpDWfb2OsHxTV
lISVJqjdhYHYM7vC6VNffMYIYxAE90ZEl9QHOdU5n7spPyxUP0fp8z8gHsQ7HhRTsCNgWbFyYb0Ib1RTOznmzMXaSOn
RKYaIpkLkOSwZurT0wyGJd+TZSw+RgsX1vKJNmKih/ii1YLvMKyq+T7PJbPDwhU8uAGQIDAQABo4HWMIHTMAwGA1UdE
wQFMAMBAf8wCwYDVR0PBAQDAgWgMHAGA1UdJQRpMGcGCCsGAQUFBwMBBggrBgEFBQcDAgYIKwYBBQUHAwQGCisGAQQB
gjcCARUGCisGAQQBgjcCARYGCisGAQQBgjcKAwEGCisGAQQBgjcKAwMGCisGAQQBgjcKAwQGCysGAQQBgjcKAwQBMEQ
GA1UdEQQ9MDuCF2VzYXRlc3Qub25taWNyb3NvZnQuY29tgSByb2JzaGVyd0Blc2F0ZXN0Lm9ubWljcm9zb2Z0LmNvbT
ANBgkqhkiG9w0BAQUFAAOCAQEAR/F2tqxBriYK8fEt0swLZQYYq+JWma6MxNjODXoSj4SWKxFv8Vb5LwE7goxi9625f
31o1kADPcK3ml0UarT35hH6f9abZSXm3mj3zMnuK5nW2ypDCVUiuA2C5l+woEubSmvn980GHuSXOqfLMPtniUMTubp+
SICDrtCse2l2GkE1OCRmxF1wtwgrCatwyoRxnDA5U4VyWQnyd7dL8eBOIhZMg1sFU6Zxg8NKtiyEzV99OJ6+DOkMn1f
QOXDBPkgHI1mzFmVQogUGDcVbvpsd1roT4JcsUebmAdGvCek49HtHtlo6+aBLHQH+pX6pUqj1+guS0X0FMmhkDJOTyZ
WnAQ=="
}
],
10. Save the .json file locally.
11. Return to your browser and the Microsoft Azure portal.
12. Click MANAGE MANIFEST > Upload
Manifest:
13. Browse and find the edited .json file, and select the check mark to complete the upload.
Finding the Tenant ID
1. Click on VIEW ENDPOINTS to view the Endpoints integrated in Microsoft Azure AD.
2. With in the URLs, notice the similar value for each line, "ed437e13-ba50-479e-b40d8affa4f7e1d7," this is the Tenant ID.
This will be unique to your application and configuration. Record this value for later configuration
on the ESA.
Final review of values to be saved
The following values should have been recorded during the Microsoft Azure AD configuration for
use when configuring the mailbox settings on the ESA:
From Configure Certificate Values:
Private Key Certificate (.pem)
$base64Thumbprint
From Configure custom Web application:
●
●
Client ID
From Finding the Tenant ID:
●
●
Tenant ID
Configure Mailbox Settings on ESA
With Microsoft Azure AD configuration complete, you are ready to have the ESA communicate and
validate.
1. Login to ESA appliance via GUI.
2. Enable Office 365 Mailbox Settings under System Administration > Mailbox Settings.
3. Select ‘Enable Office 365 Mailbox Settings check box & provide your Microsoft Azure AD
details (Client ID & Tenant ID) obtained while registering ESA application with Microsoft
Azure AD along with Thumbprint & Private key of the certificate.
4. Click Submit to save the changes to the Mailbox Settings.
5. You will need to test the connection to Microsoft Azure AD at this time for your Office 365
domain as
configured:
6. Use an active and valid email address on the account, click Test
Connection:
7. Once connection status is successful, click Done to complete the connection check.
8. Finally, click Commit to save all configuration changes on the ESA.