Implementing Authentication

Upgrading Authentication

To upgrade your service's authentication to OAuth from DeviceLink, Session ID, or anonymous access, you create a new service version. Implement authentication as described in the rest of this tutorial and respond to getDeviceAuthToken requests for authentication updates. The upgrade will occur automatically for the listener when you follow these key implementation differences described here.

Create a new service version

Create a new version of your service by following all the implementation steps beginning with Starting an implementation using browser authentication. To submit your new service, select DEVELOP & SUBMIT and use the version manager. Be sure to choose App Link for the Authentication on the Technical Configuration & Test Setup page. This changes the authType value in the service XML file and provides Sonos the trigger to upgrade authentication. Sonos checks the authType after a system upgrade when the player restarts.

Note: Enable App Link authentication even if you only implement browser authentication so that the automatic update can occur.

Respond to Sonos Player requests for updates

We've already describe how to implement getDeviceAuthToken responses, but an authentication upgrade requires that your service respond to a different form of the request. During authentication upgrade, the player upgrades each account record one at a time with repeated getDeviceAuthToken requests to your service. To indicate that this is an authentication upgrade, these requests do not contain a <linkCode> parameter, but they do include the current username and password credentials in the SOAP header. See the following sample getDeviceAuthToken request.

<soapenv:Envelope 
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:ns="http://www.sonos.com/Services/1.1">
  <soapenv:Header>
    <ns:credentials>
      <ns:deviceId>00-0E-58-5B-06-D6:8</ns:deviceId>
      <ns:deviceProvider>Sonos</ns:deviceProvider>
      <ns:login>
        <ns:username>testuser</ns:username>
        <ns:password>12345</ns:password>
     </ns:login>
   </ns:credentials>
 </soapenv:Header>
 <soapenv:Body>
   <ns:getDeviceAuthToken>
     <ns:householdId>Sonos_WhYJA54ephjrAICI4FH9geDW7F</ns:householdId>
   </ns:getDeviceAuthToken>
 </soapenv:Body>
</soapenv:Envelope>

To make the authentication upgrade automatic, your server should return your valid <authToken> and <privateKey> in the getDeviceAuthToken responses. Note also, do not update the <nickname> value if a nickname is already there. The listener may have set a different nickname, which you should not overwrite.

If you want the listener to reauthorize the account from their Sonos app with their username and password instead of providing automatic updating, then leave the <authToken> and <privateKey> blank in your response to getDeviceAuthToken.