Device Configuration Options
This integration utilizes the Spotify Web API services to control the Spotify Connect player, as well as access information on behalf of your Spotify user account(s). Spotify secures access to its Web API services using the OAuth 2.0 authorization standard, so there are some pre-requisites to complete before installing the integration to Home Assistant.
This page is fairly lengthy, so use the following index to get to where you want to be:
- OAuth2 Authorization Protocol
- Pre-Installation Requirements
- Home Assistant Applicatoin Credentials
- Integration Install
- Integration Remove
- Integration Options
Or continue reading for detailed information on how things work pertaining to the installation process.
For those already familiar with OAuth 2.0 and how it works, you can probably skip this section. If you're not familiar with OAuth2, then read on.
OAuth 2.0 (or OAuth2), which stands for “Open Authorization”, is a standard designed to allow an application to access resources hosted by other applications on behalf of a user. OAuth2 provides consented access and restricts actions of what the client application can perform on resources on behalf of the user, without ever sharing the user's logon credentials.
The OAuth2 protocol provides a way for resource owners to provide a client application with secure delegated access to server resources. It specifies a process for resource owners to authorize third-party access to their server resources without providing credentials. OAuth2 essentially allows access tokens to be issued to third-party clients by an authorization server, with the approval of the resource owner (you). The third party client then uses the access token to access the protected resources hosted by the resource server.
In the case of Home Assistant and our integration, the following can be used when interpreting the OAuth2 authorization flow explained below:
- Client: the Home Assistant OAuth2 Authorization Provider.
- Resource: the Spotify data accessed - a users playlist, media player commands, etc.
- Consumer: the SpotifyPlus integration accessing the Resource.
The Spotify Web API supports the OAuth2 Authorization Code authorization flow type. More information on Spotify Authorization Flows can be found on the Spotify Developer Documentation, Authorization page.
The following lists the basic authorization flow that is performed when accessing Spotify resources.
In the case of our integration, all but the last of the following steps will happen when the integration is installed to Home Assistant and a new Application Credential is defined by using the "Add Service" link.
-
The user shows intent. Basically, it means any access to a restricted resource that requires them to sign in. It signifies the user's intent to initiate the OAuth2 process to grant access to their data.
-
The user gets permission. Here, the client prepares an OAuth2 request and directs the user to the OAuth2 authorization server. The server will show a consent screen, listing the kinds of data the client wants to access and what actions it wants to perform.
-
The user is redirected to the service provider. The user is redirected to the authorization server's UI (a web page) where they must log in with their credentials and approve the permissions requested by the client.
-
The user gives permission. Once the user has authenticated, they give consent for the permissions requested. This is done by clicking on the “Agree” button on the authorization server's UI.
-
The consumer obtains an access token. After successful authentication and approval, the user is redirected back to the client with an authorization code. The client then exchanges this code for an access token by making a server-to-server request.
-
The consumer accesses the protected resource. Finally, the client uses the acquired access token to access the protected resources hosted by the resource server. Depending on the OAuth2 flow, this token can be short-lived and optionally refreshed.
Again, all of the above happens without Home Assistant having to store your Spotify username and password. Theat's the beauty of OAuth2.
The following steps need to be completed prior to installing the integration.
An active Spotify account is required. If you don't have a Spotify user account, then hop out to the Spotify web-site and create an account.
A premium-level account is recommended, as Spotify limits playback operations (e.g. play, pause, adjust volume, skip to the next track, etc) to premium-level accounts. You will need a premium-level membership if you want to control the Spotify Connect player from Home Assistant. Note that the premium-level membership does require a monthly service fee.
A free-level membership will also work, but you will only be able to browse media and retrieve player playback status with it (no player control, no playing of media content from Home Assistant).
In order for our integration to access Spotify user resources, we must define a Spotify Developer Application in the Spotify Developer Portal. An Application provides the Client ID and Client Secret needed by the Home Assistant OAuth2 Authorization Provider to request an access token. The access token will be created when we define the Application Credentials in Home Assistant.
NOTE - This will need to be done for each Spotify user-account that you wish to access from the Home Assistant SpotifyPlus integration, regardless of membership level (premium or free).
You may proceed to Step 3 - Home Assistant Application Credential(s) if you have already created a Spotify Developer Application(s), and have your Client ID / Client Secret values.
Otherwise, use the following steps to create a Spotify Developer Application(s).
Go to the Spotify for Developers portal and log in using your Spotify credentials. The login button is located toward the upper-right of the screen. Once you are logged in, go to the Spotify Developer Dashboard. The dashboard (see Figure 2a) is where you can create apps, control the API credentials bound to the app, or just get some nice app usage statistics.
Figure 2a - Spotify Developer Dashboard
Click on the Create App button to start the application create process (see Figure 2b).
Use the following details for the input fields on the form.
NOTE - it is VERY IMPORTANT that you get the Redirect URI correct, as it is case-sensitive and must match exactly what is specified below!
- App name:
Home Assistant Spotify Plus Integration - App description:
Home Assistant integration that allows Spotify content to be played for a Premium user account. - Website:
https://www.home-assistant.io/ - Redirect URI:
https://my.home-assistant.io/redirect/oauth - API/SDKs used:
Web API - Accept the terms and conditions by checking the box.
- Click the
Savebutton to save the application.
Figure 2b - Spotify Developer Create App
Now that the application has been created, we can look at the settings to retrieve the client id and client secret values.
Click on the Settings button to view the application details form (see Figure 2c).
Figure 2c - Spotify Developer App Details Form
You will need to click on the View Client Secret link in order to view the secret.
Copy down the Client ID and the Client Secret values, and store them in a safe place. We will be entering these values into Home Assistant in a later step. In our example, the client id is 95576e7c24e94c2d839068aa1b2e7f5e, and the client secret is 28e0224edc8c4419b9adb6feddf33ca6. Note that you cannot use OUR example values, as they have been deleted by the time this document is published.
Your new application contains your Client ID and Client Secret needed to authorize the SpotifyPlus integration to use Spotify resources via Home Assistant.
NOTE - The above steps will need to be done for each Spotify user-account that you wish to access from the Home Assistant SpotifyPlus integration, regardless of membership level (premium or free).
We are now ready to configure the Home Assistant Application Credential for the integration.
We are now ready to add Home Assistant Application Credentials for each of the Spotify Developer Applications that were created in Step 2.
Go to the Application Credentials page to list any existing OAuth2 application credentials, as well as define new ones. This is located under Settings \ Devices & Services \ Application Credentials (have to click the 3 dots menu in the upper right corner).
Click the Add Application Credentials button to add a new credential.
Fill in the Credential Form fields (see Figure 3a):
- Integration:
SpotifyPlus(select from dropdown list). - Name: Enter a name for the credential. I would suggest using "Spotify FIRST LAST" for this value, with FIRST being the Spotify user first name and LAST being the Spotify user last name (e.g. "Spotify John Smith").
- OAuth client ID: The Client ID value for the Spotify User.
- OAuth client secret: The Client Secret value for the Spotify User.
- click
Addto add the credential.
Figure 3a - Home Assistant Application Credentials Form
For multiple Spotify User support, repeat the above step for each of the Spotify Developer Applications that you created.
We are now ready to add the SpotifyPlus integration.
Use the following steps to install and configure the integration.
Go to the Integrations Dashboard page to add the integration. This is located under Settings \ Devices & Services. Click on the Add Integration button to start the process.
Or, if you have already added the integration and want to add another Spotify user, go to the SpotifyPlus Integration Details page and use the ADD SERVICE button.
The OAuth Application Credential selection form (see Figure 4b) should be displayed at this point. This will allow you to select the Application Credential that was defined earlier for the Spotify user you wish to add access for.
Check the button next to the Application Credential item that was previously defined, and click Submit to start the Spotify authorization process.
Figure 4b - Select SpotifyPlus OAuth Credential Form
Home Assistant OAuth2 security will now open a secure browser window to the Spotify authorization web-site (see Figure 4c), prompting you for your Spotify login credentials (see Figure 4c).
Enter your Spotify username and password credentials.
Figure 4c - Spotify Login Form
Note that the Spotify login prompt may be bypassed if you have logged into Spotify before and are using cached credentials. If that is the case, you will see the Authorization Form instead. If this happens, MAKE SURE that the Spotify user display name is the same Spotify account that you entered Application Credentials for!
Click on Agree on the Spotify Authorization Access Form (see Figure 4d) to allow Home Assistant to access Spotify resources on your behalf.
Figure 4d - Spotify Authorization Access Form
Click on Link Account (see Figure 4e) to allow Home Assistant to link the OAuth2 Application Credential to Spotify.
Figure 4e - Home Assistant Link Account Form
Verify the result (see Figure 4f) and click on FINISH to complete the setup for this user if the addition was successful.
Figure 4f - Integration Added Form
Repeat the SpotifyPlus Integration Install steps for each Spotify user account that needs to be added.
Use the following steps to remove the integration.
Go to the SpotifyPlus Integration Dashboard page to remove the integration. This is located under Settings \ Devices & Services \ Spotify Plus.
From the Integration Summary Form (see Figure 5a), click the 3 dots menu next to the service that you want to remove and select the Delete menu item. A confirmation dialog box will be displayed - just click DELETE to confirm the action.
Figure 5a - Integration Remove Confirm Form
Figure 5a2 - Integration Remove Confirm Form
Home Assistant will also prompt you (see Figure 5b) to remove the Application Credentials associated with the integration. You can either keep the Application Credentials or delete them.
I would suggest keeping them if you are going to re-install the integration later, which will save you the process of re-entering them again later. If you choose to keep them, but decide later that you don't need them, they can still be removed via the Application Credentials page.
Figure 5b - Application Credential Remove Confirm Form
The SpotifyPlus Service Options Form (Figure 6) allows you to customize various aspects of the integration. Adjust the settings to your taste. Click the Save button once you are finished to save your changes, or the X button at the top right to cancel without saving.
Figure 6 - SpotifyPlus Service Options Form
The following fields are available for this form:
This option controls what Spotify Connect Player device is used to play content when there is no active device, or when the default device is selected. It contains a list of Spotify Connect Player devices that are active when the options form is opened. Select an item from the dropdown list to set the default player for the specified integration.
If no selection is made, then the previously active player will be used. If no player is active, then the player command will probably fail as there will be no active device.
It should be noted that sometimes device id's change in the Spotify device list. This is especially true for web and mobile based players - the id's will change every time you open a new web page to the Spotify player. This is why you should avoid setting a web or mobile player device as the default. This is controlled by Spotify, and cannot be avoided.
Sometimes device id's are static - in the case of Bose SoundTouch for example, the Spotify player device id remains the same, even between power cycling.
Figure 6a - Default Device ID Selection
