Configure a certificate and private key to enable service-to-service calls for the Splunk Add-on for Microsoft Cloud Services¶

This step is only used when you need to configure Microsoft Office 365 Management APIs inputs. If you don’t have to configure Microsoft Office 365 Management APIs inputs, you can skip this step.

This add-on uses OAuth to authenticate from the Splunk platform to your Microsoft Office 365 account using an authorization token refreshed automatically with a refresh token. This authorization token has a mandatory expiration set by Microsoft, so the refresh token only keeps your integration current for a limited period. To avoid having to periodically re-enter a secret key manually, you can upload a Base64-encoded X.509 Certificate and private key to enable service-to-service calls and use the key credentials to update the manifest of your integration application in Azure AD.

If you are using the configuration files to configure your connection to your Microsoft cloud services, this procedure is mandatory. If you are using Splunk Web, this procedure is highly recommended.

If you skip this step, then when your authorization token expires, you will need to edit your account configuration that handles your connection to Microsoft Office 365 by entering a new secret key from the Azure AD admin console.

Configure a certificate and private key¶

You can configure the certificate and private key in Splunk Web on your data collection node (recommended), or in the configuration files.

Configure a certificate in Splunk Web¶

In Splunk Web on the instance responsible for data collection with this add-on, go to the Splunk Add-on for Microsoft Cloud Services > Configuration.
Click Certificate.

Choose one of the two options.

Option 1: Upload your own certificate and private key

Using your preferred tool, generate a X.509 certificate file and a private key with a length of at least 2048 characters and upload them on this screen. For more information about using self-signed certificates, see How to self-sign certificates. Click Choose a Certificate and browse to the certificate file (.cer) in your file system.

You need to decrypt the private key before you upload it on Splunk add-on for Microsoft Cloud Service.

Option 2: Use an auto-generated certificate

Choose this option if you want to use a certificate that the Splunk Add-on for Microsoft Cloud Services auto-generates for you.

The add-on displays the keyCredentials JSON object for your certificate.
Copy the entire JSON object to your clipboard.

Next, see Upload the certificate credentials to your integration application in Azure AD.

Configure a certificate using the configuration files¶

Generate a Base64-encoded X.509 certificate and put it in $SPLUNK_HOME/Splunk_TA_microsoft-cloudservices/local/certificate.cer.

Make sure the certificate is a X.509 certificate and the key length is at least 2048 . Shorter key lengths are not accepted by Microsoft Office 365 as valid keys.

Create $SPLUNK_HOME/Splunk_TA_microsoft-cloudservices/local/splunk_ta_ms_o365_server_certificate.conf and add the following stanza.
```
[certificate]
private_key = <Your private key, using '\' as link breaker>
```

Next, you need to obtain the keyCredentials JSON object. Run

bin/splunk cmd python $SPLUNK_HOME/etc/apps/Splunk_TA_microsoft-cloudservices/bin/splunktamscs/key_credentials_generator.py $SPLUNK_HOME/etc/apps/Splunk_TA_microsoft-cloudservices/local/certificate.cer

Copy the results to the manifest_json field in $SPLUNK_HOME/Splunk_TA_microsoft-cloudservices/local/splunk_ta_ms_o365_server_certificate.conf.

Once your certificate is created using Splunk Web or using the configuration files, it will look like the following example.

"keyCredentials": [{"keyId": "92fe4c65-9ce3-4d6d-9c76-31b511a8a977",
"customKeyIdentifier": "<custom-key-identifier>", "value": "<value>", "type": "AsymmetricX509Cert", "usage": "Verify"}]

For more information about using self-signed certificates, see How to self-sign certificates.

Next, continue with the procedure in the next section.

Upload the certificate credentials to your integration application in Azure AD¶

Sign in to the Azure management portal and navigate to the integration application that you created in Connect to your Microsoft Office 365 account with the Splunk Add-on for Microsoft Cloud Services.

Click Manage Manifest > Download Manifest. It will look similar to the below example.

{
  "appId": "0399fdb3-c651-4360-ae33-97ed0598b5af",
  "appRoles": [],
  "availableToOtherTenants": false,
  "displayName": "zliang-test-app",
  "errorUrl": null,
  "groupMembershipClaims": null,
  "optionalClaims": null,
  "acceptMappedClaims": null,
  "homepage": "http://localhost:8000",
  "identifierUris": [
    "https://a830edad9050849NDA3079.onmicrosoft.com/6136b06e-df48-4776-82c0-424641b1b33f"
  ],
  "keyCredentials": [],
  "knownClientApplications": [],
  "logoutUrl": null,
  "oauth2AllowImplicitFlow": false,
  "oauth2AllowUrlPathMatching": false,
  "oauth2Permissions": [
    {
      "adminConsentDescription": "Allow the application to access zliang-test-app on behalf of the signed-in user.",
      "adminConsentDisplayName": "Access zliang-test-app",
      "id": "8448c8ef-a250-481e-ba5c-d877badd3e07",
      "isEnabled": true,
      "type": "User",
      "userConsentDescription": "Allow the application to access zliang-test-app on your behalf.",
      "userConsentDisplayName": "Access zliang-test-app",
      "value": "user_impersonation"
    }
  ],
  "oauth2RequirePostResponse": false,
  "objectId": "aa082da8-0f43-4a09-a364-630f4df75a62",
  "passwordCredentials": [],
  "publicClient": false,
  "replyUrls": [
    "http://localhost:8000"
  ],
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "resourceAccess": [
        {
          "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "type": "Scope"
        }
      ]
    }
  ],
  "samlMetadataUrl": null
}

Open the manifest in a text editor.

Place your cursor inside the empty brackets after "keyCredentials": and replace the keyCredentials key-value pair with the one generated in your configured certificate. See the below example.

{
  "appId": "0399fdb3-c651-4360-ae33-97ed0598b5af",
  "appRoles": [],
  "availableToOtherTenants": false,
  "displayName": "zliang-test-app",
  "errorUrl": null,
  "groupMembershipClaims": null,
  "optionalClaims": null,
  "acceptMappedClaims": null,
  "homepage": "http://localhost:8000",
  "identifierUris": [
    "https://a830edad9050849NDA3079.onmicrosoft.com/6136b06e-df48-4776-82c0-424641b1b33f"
  ],
  "keyCredentials": [{"keyId": "92fe4c65-9ce3-4d6d-9c76-31b511a8a977", "customKeyIdentifier": "<custom-key-identifier>", "value": "<value>", "type": "AsymmetricX509Cert", "usage": "Verify"}],
  "knownClientApplications": [],
  "logoutUrl": null,
  "oauth2AllowImplicitFlow": false,
  "oauth2AllowUrlPathMatching": false,
  "oauth2Permissions": [
    {
      "adminConsentDescription": "Allow the application to access zliang-test-app on behalf of the signed-in user.",
      "adminConsentDisplayName": "Access zliang-test-app",
      "id": "8448c8ef-a250-481e-ba5c-d877badd3e07",
      "isEnabled": true,
      "type": "User",
      "userConsentDescription": "Allow the application to access zliang-test-app on your behalf.",
      "userConsentDisplayName": "Access zliang-test-app",
      "value": "user_impersonation"
    }
  ],
  "oauth2RequirePostResponse": false,
  "objectId": "aa082da8-0f43-4a09-a364-630f4df75a62",
  "passwordCredentials": [],
  "publicClient": false,
  "replyUrls": [
    "http://localhost:8000"
  ],
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "resourceAccess": [
        {
          "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "type": "Scope"
        }
      ]
    }
  ],
  "samlMetadataUrl": null
}

Check to make sure the edited JSON is valid.
(Optional) If the keyCredentials array in your application’s manifest is not empty, copy the value, from your generated keyCredentials array, and paste it inside your existing keyCredentials array in your manifest, along with a “,” in between the copied value and the existing values in order to construct a valid JSON array. See the below example.
```
{"keyId": "92fe4c65-9ce3-4d6d-9c76-31b511a8a977",
"customKeyIdentifier": "<custom-key-identifier>",
"value": "<value>", "type": "AsymmetricX509Cert", "usage": "Verify"}
```
Save the file. Do not change the file name.
In the Azure management portal, click Manifest > Upload Manifest.
Upload the edited JSON file that you just saved.
On the Splunk platform instance responsible for data collection for this add-on, click on Troubleshooting.

If the Certificate Status panel says anything other than “Uploaded and verified as valid”, wait a moment and refresh the page. If the certificate is still not reported as valid, try again with a new certificate and key file.