ManageEngine ADSelfService Password Reset via RingCentral SMS
ManageEngine ADSelfService has a password reset feature that can utilize SMS for Two-Factor Authentication. This document describes how to integrate this service with RingCentral APIs.
References:
- ManageEngine ADSelfService SMS Password Reset
- ManageEngine Administration Guide
- ManageEngine ADSelfService forums
- ManageEngine ADSelfService phone number format
- RingCentral Developer Guide
- RingCentral Developer Community Thread with ASP.NET example code
Integration Overview
ManageEngine interfaces with third-party SMS providers using a query-string based outbound webhook API call. This is not compatible with the RingCentral API which uses a different JSON body-based API. The basic differences are that ManageEngine can send an outbound webhook via a HTTP
GET
or POST
call with query string parameters and RingCentral listens for an authorized JSON body request.
To get these two services to integrate, 2 approaches are available:
- Custom Middleware: Write a small service that will listen for ManageEngine GET or POST calls and format to the appropriate RingCentral SMS API call.
- Zapier with Inbound Webhook: RingCentral has a Zapier integration that can be integrated with ManageEngine using the Webhooks by Zapier trigger.
The two services that need to be connected are described below:
SMS Phone Number Formatting
Of note, the mobile number sent by ManageEngine's outbound webhook will be the mobile number in ActiveDirectory with all special chracters removed. This should work with RingCentral as long as the number includes the area code. For exampple, "1 (650) 111-2222" will become "16501112222" in ManageEngine. If you are using a custom integration, your code make any necessary modifications. When using Zapier, ensure your ActiveDirectory numbers begin with the country code and it should work seamlessly.
Integration via Custom Middleware
To write a custom middleware service, you will need to operate a HTTP service which can be ASP.NET, PHP, or any other HTTP service.
Essentially two steps are necessary:
1) ManageEngine SMS Compatible Endpoint
ManageEngine uses a query string format of the following type in the ManageEngine Administration Guide:
userName=xxx&password=yyy&mobileNumber=%mobNo%&message=%message%
For RingCentral, the most important parts are the mobile number and the message which are used in the RingCentral API call. An example endpoint for your server can be:
http://localhost/rcsendsms?mobileNumber=%mobNo%&message=%message
2) Making the RingCentral API Call
The rcsendsms
code needs format the incoming query string data to use the RingCentral SMS API. When the rcsendsms
script receives the request, it should reformat it and send it to the RingCentral API using the mobile number as the to.phoneNumber
JSON body value and the message as the text
JSON body value as specified in the RingCentral API Developer Guide.
For authorization, the RingCentral extension credentials can be a stored using the OAuth 2.0 password grant available for private apps. If this service is behind your firewall and you are confident in your security, this may be all that you need. If you wish to lock down this service you can add your own password or key and send that as a header so that it's not captured in server logs.
While all RingCentral SDKs will automatically handle refresh tokens for you, if you do not wish to manage OAuth 2.0 refresh tokens, you can set the refresh_token_ttl
value to -1
so no refresh token is created for the request and then you can request a new access token for each request. Requesting a new refresh token for each SMS API call may get your app blocked by RingCentral so be sensitive to this.
Integration via Zapier
To set up ManageEngine ADSelfService using HTTP-based Custom SMS Provider with RingCentral via Zapier, perform the following steps.
Note: for the Zapier integration to work the phone number produced by the ManageEngine %mobNo%
macro must match a format recognized by RingCentral, e.g. E.164 format with or without the leading +
, for example, +1 (650) 111-2222
would be represented as 16501112222
or +16501112222
. ManageEngine uses the phone number from ActiveDirectory and will strip out all special characters so ensure that your Active Directory numbers include the country code and this should work seamlessly.
1) Make a Zap!
Login to Zapier and click the MAKE A ZAP!
button.
2) Set up the ManageEngine Webhook Trigger
- Select the
Webhooks by Zapier
app. - Select
Catch Hook: Wait for a new POST, PUT, or GET to a Zapier URL.
for the action. - Click
Continue
on the Set up page, and do not enter anything in thePick off a Child Key
option. - Use the webhook provided and send a
GET
request matching the one ManageEngine will provide, e.g.https://zapier.com/hooks/catch/111111/222222/
. It is important to use aGET
request because Zapier does not make query string parameters available toPOST
webhooks. - Upon a successful test, optionally click the
view your hook
link to see the parameters you posted. If your ManageEngine URL used a template like?mobileNumber=%mobNo%&message=%message
in Zapier you should see thequerystring__mobileNumber
andquerystring__message
parameters. Then clickContinue
.
3) Set up the RingCentral SMS Action
- Select
RingCentral
for the Zapier app. - Select
Send SMS
for the action. - Select a connected RingCentral account, either an existing one or a new one via
Connect a New Account
. - On the
Set up RingCentral SMS
form: for thePhone Number From
, select your login phone number or a different one that is allowed to send SMS. For thePhone Number To
value, selectUse a Custom Value
and then in theCustom Value for Phone Numbrer to ID
input, click the text+
icon to the right and selectQuerystring Mobile Number
. In theText
field, click the text+
icon and selec theQuerystring Message
property. Then clickContinue
. - Optionally run the test to receive a SMS message and then click the
Finish
if you do not wish to add any additional actions.
Select Screenshots
Selecting the Webhook Action:
Formatting the RingCentral API Call: