Last time, on the Ring my bell adventures, we explored using powershell to have a bit of fun with our doorbells. Unfortunately since then, about a million people went and used “password” as their password and were then surprised when their cameras were “hacked” which caused Ring to make sweeping changes to their security which broke my fun little script. I recently read my own eerily accurate horoscope profile that read, “You try too hard at dumb things”, so let set about fixing what was broken.

First, lets go over some of the changes that caused our previous script to stop working.

• As far as I’m aware, every ring account must use a method of 2 factor authentication (2FA) for any login event, including generating access tokens for the Ring API. This can be delivered through either Email or SMS text messaging.
• Only one Email address can be associated to a “location” containing Ring products as the Owner.
• Users who are not the Owner of a location will only be able to see doorbell objects or “Doorbots” and not chimes. I’m pretty sure this means the script will only work for location owners. Sorry, no ringing your neighbor’s doorbell.
• While the chimes enpoint still exists, it has different behaviour. Information about chimes is now gathered through the “ring_devices”/{chime id} endpoint even though ringing a chime still takes place through /chimes/{chime id}/play_sound

With that out of the way lets jump into into it. I knew right off the bat I’d want to have a function to handle the authentication. This would let me use the same function for both getting a 2FA code and for getting an access token once the 2FA code was obtained. I started with a simple simple function containing a single parameter name code. This will allow us to pass in our 2FA code later on. (Complete function at the end of the post)

Function Generate-RingOauthToken{

param(    
        [Parameter(Mandatory=$false)]
        [string]
        $Code
)

#define the Endpoint for granting acess tokens
#this is also the endpoint for generating a 2FA code
$uri = "https://oauth.ring.com/oauth/token"

The next event for the function is to handle the username and password that will be used to authenticate. I wrote this portion two different ways. At first I used a read-host prompt to have the user type in their username and password with a secure prompt used for the password. Because you have to run the function twice, once for the 2FA code and once for the token, and I had to run this a number of times to get it working I ended up changing it to a simple plain text entry in the script. I’ll post both options below.

Prompt user for username and secure password:

#prompt the user for their username, if empty or only spaces throw an error and exit the function
$username = Read-Host -Prompt "Username"
if([string]::IsNullOrWhiteSpace($username)){
    Write-Error -Message "The Username was either blank or it could not be validated" -Category InvalidData
    exit
}

#prompt the user for their password, if empty or only spaces throw an error and exit the function
$Secpassword = Read-Host -Prompt "password" -AsSecureString
if([string]::IsNullOrWhiteSpace($Secpassword)){
    Write-Error -Message "The Username was either blank or it could not be validated" -Category InvalidData
    exit
}

#create a PSCredential object to hold the username and password
$credential = New-Object System.Management.Automation.PSCredential ($userName, $SecPassword)

#extract the plaintext password from the securestring password of the PSCredential object
$password = $credential.GetNetworkCredential().Password

Or the less secure but worlds more convenient option. Side note, I actually use a function to store machine specific secure string passwords to my Onedrive and another function to retrieve the correct encrypted secure string from Onedrive for the machine I’m on and the password I need but that’s a function for another time.

$username = "YourUsernameHERE"
$password = "YourPasswordHERE"

Next we need a hash table that should look familiar if you read my last post. This will be the body object that gets sent with our POST request. I played around with this and found that a client id of “RingWindows” will work here as well.

#define the parameters used to authenticate
 $Authbody = @{
    client_id = "ring_official_android"
    grant_type = "password"
    scope = "client"
    username = $username
    password = $password
}

The next section validates whether or not the user passed in a 2FA code. If a 2FA code was used, one set of header fields is generated containing the 2FA code . If not, a different set of header fields are used that signify the user needs a new 2FA code to be generated.

#if a 2FA code was supplied generate a hashtable for the header fields
#containing the code
If(!([string]::IsNullOrWhiteSpace($Code))){

    $authheaders = @{
    'Content-Type' = 'application/x-www-form-urlencoded';
    'charset' = 'UTF-8';
    'User-Agent' = 'Dalvik/2.1.0 (Linux; U; Android 9.0; SM-G850F Build/LRX22G)';
    'Accept-Encoding' = 'gzip, deflate'
    '2fa-support' = 'true'
    '2fa-code' = $Code
 
    } 

}else{

#otherwise use the standard headers indicating the user needs a new 2FA code
#to be generated
$authheaders= @{
    
    'Content-Type' = 'application/x-www-form-urlencoded';
    'charset' = 'UTF-8';
    'User-Agent' = 'Dalvik/2.1.0 (Linux; U; Android 9.0; SM-G850F Build/LRX22G)';
    'Accept-Encoding' = 'gzip, deflate'
    
    }

}

Finally we get to the part where we actually ask for an authorization token or a 2FA code. I was a bit surprised to see that when a successful auth call is made to get a 2FA code, an error is returned rather than a success. Furthermore, the useful information about where the 2FA code was sent is contained in the error message returned. That means that if this function is run without the “-code” switch it will always return an error.

• Error 400 – The 2FA code supplied is invalid
• Error 401 – Bad username and password
• Error 412 – Authorization successful, 2FA was generated and sent
• Error 429 – Your request was throttled. Too many requests have been made

It seems a bit weird to me to handle a successful event by throwing an error, but hey, I’m just some good looking guy. What do I know ¯\_(ツ)_/¯ ? I decided to handle this by parsing the error from the Invoke-RestMethod request in a try/catch block so the relevant information was easily visible. The default error object doesn’t show all of the useful information.

try{

$Authrequest = Invoke-RestMethod -Uri $uri -Method Post -Body $Authbody -Headers $authheaders -ErrorAction Stop

}
catch{
    
    $message = $error[0].ErrorDetails.Message | ConvertFrom-Json
    $exception = $error[0].Exception.Message    

    return $message
    EXIT
}

Finally, the only think left is to return the Token object if the request was successful and close out of the function.

return $Authrequest

} 

Now that the Function is complete how do we use it? Simple. Either paste the function into your powershell console or save it to your powershell profile and then launch powershell. Now type Generate-RingOauthToken. Here you can see the result when a 2FA code is sent to you via Email. When you receive codes via SMS text messages you will only see the next_time_in_secs and phone parameters and the phone value will be an obfuscated representation of the phone number on your account.

Once you receive the 6 digit 2FA code, run the function again with the “-code” switch to generate a token for later use like this.

$token = (Generate-RingOauthToken -code xxxxxx).access_token

With our token in hand we can query the devices in our account. This is handled through a different endpoint than before. Record the ID of the chime you’d like to make ring.

#get all chime devices
$chimes = (Invoke-RestMethod -Method get -Uri 'https://api.ring.com/clients_api/ring_devices' -Headers @{Authorization = "Bearer $token"}).chimes

#get all doorbell devices
$doorbells = (Invoke-RestMethod -Method get -Uri 'https://api.ring.com/clients_api/ring_devices' -Headers @{Authorization = "Bearer $token"}).doorbots

#quick access reference for the object IDs of all chimes in the account
$chimes.ID
#quick access reference for the object IDs of all doorbells in the account
$doorbells.ID

After you find the particular device ID for the chime you want to make ring, run the following command to make it so. Replace “{ChimeID}” with the ID you found from the preceding commands.

Invoke-WebRequest -Method post -Uri 'https://api.ring.com/clients_api/chimes/{ChimeID}/play_sound' -Headers @{Authorization = "Bearer $token"}

There you have it. One broken script restored to its former glory.

I’ll place the entire token generation function below so it’s all together in one place. I left both authentication methods (manual typing and stored in plain text) in the script so comment out one and use the other if you’d like.

Function Generate-RingOauthToken{

param(    
        [Parameter(Mandatory=$false)]
        [string]
        $Code
)

#define the Endpoint for granting access tokens
#this is also the endpoint for generating a 2FA code
$uri = "https://oauth.ring.com/oauth/token"


<#

This area was commented out in favor of putting the credentials in the script so you don't
have to type username and pw twice per token grant

#prompt the user for their username, if empty or only spaces throw an error and exit the function
$username = Read-Host -Prompt "Username"
if([string]::IsNullOrWhiteSpace($username)){
    Write-Error -Message "The Username was either blank or it could not be validated" -Category InvalidData
    exit
}

#prompt the user for their username, if empty or only spaces throw an error and exit the function
$Secpassword = Read-Host -Prompt "password" -AsSecureString
if([string]::IsNullOrWhiteSpace($Secpassword)){
    Write-Error -Message "The Username was either blank or it could not be validated" -Category InvalidData
    exit
}

#create a PSCredential object to hold the username and password
$credential = New-Object System.Management.Automation.PSCredential ($userName, $SecPassword)

#extract the plaintext password from the securestring password of the PSCredential object
$password = $credential.GetNetworkCredential().Password

#>

#plaintext username and password. Comment out these two lines and uncomment the block 
#above to use manual username and password typing
$username = "YourUsernameHere"
$password = "YourPasswordHere"

#define the parameters used to authenticate
 $Authbody = @{
    client_id = "ring_official_android"
    grant_type = "password"
    scope = "client"
    username = $username
    password = $password
}

#if a 2FA code was supplied generate a hashtable for the header fields
#containing the code
If(!([string]::IsNullOrWhiteSpace($Code))){

    $authheaders = @{
    'Content-Type' = 'application/x-www-form-urlencoded';
    'charset' = 'UTF-8';
    'User-Agent' = 'Dalvik/2.1.0 (Linux; U; Android 9.0; SM-G850F Build/LRX22G)';
    'Accept-Encoding' = 'gzip, deflate'
    '2fa-support' = 'true'
    '2fa-code' = $Code
 
    } 

}else{

#otherwise use the standard headers indicating the user needs a new 2FA code
#to be generated
$authheaders= @{
    
    'Content-Type' = 'application/x-www-form-urlencoded';
    'charset' = 'UTF-8';
    'User-Agent' = 'Dalvik/2.1.0 (Linux; U; Android 9.0; SM-G850F Build/LRX22G)';
    'Accept-Encoding' = 'gzip, deflate'
    
    }

}


try{

#make an authentication request for a token or 2FA Code
$Authrequest = Invoke-RestMethod -Uri $uri -Method Post -Body $Authbody -Headers $authheaders -ErrorAction Stop

}
catch{
    
    #return the parsed error message to the user
    $message = $error[0].ErrorDetails.Message | ConvertFrom-Json
    $exception = $error[0].Exception.Message    

    return $message
    EXIT


}

#if successful, return the access token
return $Authrequest


} 

I recently started playing with some of the advanced calling features available in Microsoft Teams, specifically the voicemail features. For years our organization has had an on-premises Cisco based phone system. Through the use of Unified Messaging, we receive email notifications in our Outlook inbox when we miss a call and someone left us a voicemail. We can listen to the attached .wav file without having to “dial in” and check them manually. I was pleasantly surprised when I realized that Teams has its own cloud voicemail capabilities built into its calling feature. When a message is left on a missed Teams call, I get a message in both my outlook and my Teams app and I can listen to the message in either place. The service will even give you a speech to text transcription of the message.

I love the idea of having all of my important content in a single work space, so the wheels in my head started turning. I wondered if it would be possible for our Cisco unified messaging system to send me voicemails that were visible in both my outlook and my teams console. I checked a few settings on the Cisco and Teams side of things and I didn’t see an obvious solutions so I went to Microsoft support. Because we do not have a session border controller and we have not extended our calling system to the cloud, I was told, “these two systems are completely separate and as such it will not be possible to receive your Cisco voicemails in your teams console”.

My response:

I dug into the documentation for Microsoft’s cloud voicemail and how it interacts with Teams. It turns out, the Teams app is just looking at a user’s Email inbox and scanning for Emails with certain “SingleValueExtendedProperties” tags on them. Emails that match these criteria are considered cloud voicemails and will show up in your list of voicemails in Teams. With the help of a blog post: https://gsexdev.blogspot.com/2019/05/ I was able to use the Microsoft graph API to spoof a cloud voicemail email and have that message show up in both my inbox and my Teams console. Armed with a small bit of success, I knew what needed to be done. If I could make a regular old Email appear to be a cloud voicemail in the eyes of Teams, I was going to find a way to automate this process and convert all of my Cisco voicemails to Teams cloud voicemails.

Automation, APIs, and Microsoft, this sounded like a perfect excuse to use Microsoft Flow. I had a plan. If I could make a Graph API POST call create a cloud voicemail Email, I should be able to use a PATCH request to convert an existing one, so I set about designing my flow.

The first step was obvious. I wanted to make a automated flow that was triggered whenever I received an email.

If the email matches the subject line filter of “Message from” and it has an attachment, the flow gets triggered. From there, I create four variables. First, I create “upn” and set it the value of the “To” field of the Email. This should capture my email address which is also my Userprincipalname. Second, I create “messageid” and set it the the global unique identifier propertiy of the Email that was received. We will need this value later on to convert this specific email. Next I create “Uri” using values from the last two variables that were created. This string is the URI endpoint to which we will be sending our PATCH request. Finally I create “attachmentcontent” and I do not assign it an initial value. We will set the value in the next step.

After initializing these variables that are necessary for making the PATCH request. I had one more variable to set. I wanted to know how long (in seconds) the voicemail was. Teams displays this value for each voicemail that is received and I wanted it to be accurate.

The .wav files that are generated by the Cisco voicemail system contain a length attribute, but unfortunately this value is not parsed by Microsoft Flow. The only values I could see were the unique identifier for the attachment, name, size in bytes, and file format. This meant I had to do a little calculation. Additionally, any time I tried to set a variable based on the attachment properties, it put that process inside of a ‘apply to each’ loop. I guessing that’s to account for Emails with multiple attachments. In the end, My next step looked like this:

This step took each attachment, in my case there should only be one, and it extracts the size of the attachment in bytes using the expression shown above “items(‘Apply_to_each’)?[‘size’]”. That value then gets set to the blank variable we created earlier.

Based on the recording quality of our phone system, 64kbps, I found that the following formula gave a fairly accurate estimation of the file length: (Size in bytes)/8100 = (file length). I initialized a new variable using this formula to save the file length property using a custom expression.

At this point, I’ve stored all of the values I need to make my idea come to life. I can start actually doing things. This first action I need to take is to mark the message as read and then wait 10 seconds. This is an important process because it makes the Cisco phone system believe the message has been listened to and it clears the little red “you have voicemails” light from my phone. I found I had to wait 10 seconds before continuing to account for latency and other factors to make sure the phone system sees the message as read. It’s important to take this step first because once the Email gets converted into a cloud voicemail Email, it breaks the relationship to the phone system and the only way to get the phone system to realize the message has been listened to is to actually dial in and listen manually.

Now comes the actual conversion process. We will use the HTTP connector in Flow to make a PATCH request using Azure OAUTH authentication. This requires an Azure application set up with the appropriate permission. You can find the setup instructions for such apps here: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app or on a number of other blogs. For the HTTP process, we set the method to PATCH in order to modify an existing object. For the URI we use the variable we set earlier to reference the URI for the message we want to modify. I set the headers to with the value “content-type”=”application/json”.

For the body of the request, I constructed a JSON statement with an array of values for the “singleValueExtendedProperties” property of the email. These are the actual changes that will be written to the Email object. I use  IPM.Note.Microsoft.Voicemail.UM.CA to set the ItemClass of the message to a voicemail. X-VoiceMessageConfidenceLevel is an undocumented property, but it is generally set to high. Next I use the wavelength variable to set the length of the voicemail message. Finally, I use the X-VoiceMessageTranscription property to set the speech to text transcription property. We currently don’t use this feature on our Cisco phone system so I set this value to a static string to let me know this is a converted Email.

Now I need to set the authentication for the HTTP process. I’ve redacted my values but you can find them all in Azure AD by selecting your app under application registrations. The secret key can be found or generated on the certificates & secrets page for your application.

Now the message has been converted and the connection between that Email and the Cisco phone system has been severed. There are only two things left to do. First, I add a 5 second delay to let the change propagate back to the phone system, then I mark the Email as unread so I see the alert in my Teams console and Outlook.

Lets take a look at the end result. I see a notification in my teams console where I can listen to the message attachment. Listening to the message in Teams marks the message as read in Outlook and visa-versa. The message duration is displayed correctly and should be accurate. If the person who left the voicemail is a member of our organization I see their user details in teams because the Cisco UM message is associated to their account and if not, I see the email came from the Cisco message system.

Let this be a lesson to you all. Don’t tell me something is impossible unless you want to end up holding my beer.

Next time we’ll go over a few improvements as well as setting up voicemail conversions for multiple users with a single Flow.