Tenant Configuration Guide
When you’re ready to get started building solutions with Yonomi you’ll need to request and configure your Yonomi Platform Tenant. This guide will walk you through the steps to get you up and running.
📘 What is a Tenant?
Yonomi provides customers with one or more tenants to build and run their solutions. A tenant is a dedicated instance of Yonomi Platform software services. A customer will typically use at least two tenants - one for each of their development and production environments - and may request as many as needed to build their solutions. Tenants can be thought of as synonymous with a developement environment/stage, and a customer may run multiple solutions on a single production tenant.
Tenants are logically distinct. For example, users and devices created on a customer’s development tenant do not exist and are not accessible on that customer’s production tenant. Likewise, tenants are unique across customers and data is not shared or accessible across different customer tenants.
Each tenant provided by Yonomi must be configured, and with few exceptions such as webhook url configurations, tenants cannot share configuration settings.
There are 3 steps to tenant configuration:
One additional, optional configuration step is Custom Vendor API Key Management, covered at the end of this guide.
User Authentication Configuration
The first and most important step in configuring your Yonomi tenant is to establish a user authentication source and begin generating JSON Web Tokens (JWTs) that Yonomi can use to identify and authorize your users. Yonomi relies on your existing OAuth2.0-compliant Identity & Access Management (IAM) solution to authorize requests made to Yonomi Platform on behalf of your users. In other words, Yonomi uses the very same user access and authorization systems you already use today. This means you won’t need to create and manage separate users in Yonomi - your existing users simply interact with Yonomi. The Yonomi platform verifies your user requests by validating user tokens against your IAM public key for every request. This identity management flow allows for a seamless user experience between the Yonomi platform, 3rd Party devices and your applications.
For more on user authentication with Yonomi see User Access and Authorization.
This step requires that you have the ability to generate OAuth2.0-compliant JSON Web Tokens, or JWTs. If you already use a popular IAM solution today for user management such as Auth0, Okta, PingIdentity or AWS Cognito then you’re in a great position to be able to generate JWTs that can be used with Yonomi to authentiate and authorize your users. If not, a good first step will be to identify the right IAM for your needs. If you need help here you can reach out to us for guidance.
JWTs generated by your IAM must meet to the following requirements:
- must conform to the OpenID Connect standard
- must be be signed by your private key
- must include
kidclaim in the payload header
- must include
expclaims in the payload body
subclaim must be unique per user
expclaim must specify a time in the future when the token expires
issclaim must be a URI that can be used to resolve your IAM’s OpenID Configuration at the standard-specified path:
- JSON Web Keyset (JWKS) URI with public key must be accessible from the
jwks_uriattribute in the Open ID Configuration
- JWKS must have an
nRSA modulus - Yonomi only accepts RS256 encrypted JWTs
You can use the jwt.io site to decrypt and view your token for validity.
Once you are able to generate JWTs that conform to this standard, contact your Yonomi Customer Support engineer (or Yonomi PreSales) and provide an unexpired sample JWT, which will be used to configure your tenant.
Making Authenticated Calls to your Yonomi Tenant
After your tenant is configured, simply set the
Authorization HTTP header to the value of your user’s JWT to execute authenticated queries. With the
Authorization header set, you’re now ready to begin making GraphQL queries in your own environment.
If you ever find that your calls are reflected as unauthorized when you attempt to run them in the Playground, try replacing the token in the
Authorization header with a newly generated, unexpired token.
Callback URL Configuration
The second step in configuring your tenant is to set your device authorization callback URLs. Yonomi allows you to access and control devices after they have been authorized by the device vendor’s authorization process. This process is called Account Linking, and involves directing a user to a vendor-provided URL in order to enter the username and password credentials for the account that owns the device. As an example, in order to use a Schlage lock you’ll need to load an account linking URL and provide the Schlage credentials used to provision the lock when it was first installed. Once authorized, any devices associated with the newly linked account will be available for use through Yonomi.
📘 What if I don’t set my callback URLs?
If you don’t set your callback URLs your user’s experience will terminate at a very simply “Success” or “Failed” page upon completion of the Account Linking process
Key to the account linking process is a redirect of the user to the vendor’s account linking URL. Once the linking process is complete, Yonomi allows you to redirect the user back to your app with a callback URL. Callback URLs allow you to send the user back to your app experience in a seamless way to continue the flow after an account has been linked and devices are accessible. Yonomi allows you to set two callback URLs - one for successful linking (Success Callback URL) and one for a failed linking process (Failure Callback URL) which can result for instance during attempts to use invalid vendor login credentials.
🚧 Callback URLs are static; they cannot be customized per user or include dynamic query string parameters.
To configure your callbacks, just send the URLs to your Yonomi Customer Support engineer (or Yonomi PreSales). They’ll let you know once they’ve been configured.
To test your callback URLs, simply complete the account linking process with a user account and make sure you see the appropriate URL redirect after the process is complete.
Webhook Setup & Configuration
The last step in tenant configuration is to begin processing webhook events from Yonomi Platform. Webhooks - also known as user-defined HTTP callbacks - are automated, one-way messages sent from a service to a client when an event occurs. Webhooks are a scalable, efficient and convenient way for applications to receive real-time information of the events monitored or managed by that service. Yonomi uses webhooks to asynchronously provide data about device state changes to your applications.
📘 For a full list of all event types supported by the Yonomi platform visit the Yonomi Webhooks reference.
Because webhooks are useful once you have begun working with devices, webhook setup is covered in the separate Getting Started with Webhooks Guide. You can follow that guide to get webhooks configured and complete your Yonomi Platform tenant configuration
Congratulations! You’ve successfully completed configuration of your Yonomi Tenant.
Optional: Custom Vendor API Key Management
Yonomi uses our own API keys to make calls against vendor clouds in order to interact with devices. This approach makes sense for most customers, however if you have your own API keys with a particular vendor and/or need to establish a more direct relationship with that, Yonomi can configure your tenant to use your own API keys when making calls to a given vendor cloud. Please contact Yonomi Customer Care if you’re interested in making this change.