{"id":18695339,"url":"https://github.com/smartthingscommunity/st-schema-oauth-example","last_synced_at":"2025-06-19T07:05:21.592Z","repository":{"id":44840732,"uuid":"191703676","full_name":"SmartThingsCommunity/st-schema-oauth-example","owner":"SmartThingsCommunity","description":"Compete ST Schema connector example including OAuth server and virtual device web app","archived":false,"fork":false,"pushed_at":"2023-08-11T11:11:25.000Z","size":233,"stargazers_count":8,"open_issues_count":11,"forks_count":9,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T07:37:15.999Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SmartThingsCommunity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-06-13T06:25:50.000Z","updated_at":"2023-09-11T13:08:22.000Z","dependencies_parsed_at":"2025-04-12T07:29:48.089Z","dependency_job_id":"c702bbb8-0451-4ec4-9689-b9bc92591918","html_url":"https://github.com/SmartThingsCommunity/st-schema-oauth-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SmartThingsCommunity/st-schema-oauth-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fst-schema-oauth-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fst-schema-oauth-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fst-schema-oauth-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fst-schema-oauth-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SmartThingsCommunity","download_url":"https://codeload.github.com/SmartThingsCommunity/st-schema-oauth-example/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fst-schema-oauth-example/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260705809,"owners_count":23049488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T11:14:40.635Z","updated_at":"2025-06-19T07:05:16.565Z","avatar_url":"https://github.com/SmartThingsCommunity.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ST Schema OAuth Example\n\nReference application that includes a cloud-based virtual device application\nwith web UI for controlling devices, and OAuth2 server for authenticating\nwith that cloud using ST Schema and the SmartThings mobile app, and an\nST Schema connector. The app uses the [st-schema SDK](https://www.npmjs.com/package/st-schema),\nthe [express](https://www.npmjs.com/package/express) web server, \n[EJS](https://ejs.co/), \nand the [Knockout](https://knockoutjs.com/documentation/introduction.html) UI library.\n\nThe app allows users to create a number of virtual devices including switches,\ndimmers, tunable white bulbs, color bulbs, motions sensors, open/close \nsensors, and thermostats.\n\n#### Prerequisites\n\n- An [Amazon Web Services account](https://aws.amazon.com/)\n- [Ngrok](https://ngrok.com/) or similar technology for creating an SSL tunnel (or you can host this \nconnector on something like [Glitch](https://glitch.com/)) \n- A [SmartThings Developer Workspace account](https://smartthings.developer.samsung.com/workspace/)\n- The SmartThings mobile app (available from the [iOS App Store](https://apps.apple.com/us/app/smartthings/id1222822904)\nor [Google Play Store](https://play.google.com/store/apps/details?id=com.samsung.android.oneconnect))\n\n\n## File Structure\n\n* lib -- Example third party app classes\n  * Account.js -- Account domain object and password management\n  * connector.js -- The ST Schema connector\n  * db.js -- Reading and writing of devices and access tokens to DynamoDB\n  * device-service.js -- Proactive state callbacks\n  * mapping.js -- Mappings between ST Schema and the external representation of devices\n* public -- Static web server files\n  * images -- images for use in web pages\n  * javascript\n    * devices.js -- View model object for a device\n    * devices.js -- Initializes the devices page and view model\n    * devicesviewmodel.js -- Top level view model for the page\n    * oauth.js -- Initializes the OAuth page\n    * property.js -- View model object for a device property\n  * stylesheets\n* routes -- Web application controllers\n  * devices.js -- Handles web-based device CRUD and control operations\n  * index.js -- Home page and web UI login\n  * oauth -- Handles login and OAuth authorization for ST mobile app\n  * schema -- ST Schema endpoint\n* views\n  * devices\n    * index.ejs -- The devices page\n  * oauth\n    * invalidauth.js -- Invalid authorization error page\n    * login.js -- The OAuth login page rendered in the SmartThings app\n  * error.ejs -- Web app error page\n  * index.ejs -- Web app landing page with a link to the devices web page\n  * login.ejs -- Web app login page\n  * redirect.ejs -- Test page that renders redirect parameters\n* .example_env -- Example enviromnent variables file\n* server.js -- The express web server\n\n## Setup\n\nCreate the `.example_env` file to a `.env` in the root directory of the project containing the following information, changing values and filling in\nmissing data (shown inside `{...}`) with your information. Note that you won't yet have `ST_CLIENT_ID`\nand `ST_CLIENT_SECRET` fields so just leave them as they are for now.\n\n```$\n# Publically accessible URL for accessing this server. You can use ngrok to tunnel to your local server for development\nSERVER_URL=https://{{SOMETHING}}.ngrok.io\n\n# Client ID and secret of this OAuth app. These can be anything you want\nCLIENT_ID=\"{{SOMETHING}}\"\nCLIENT_SECRET=\"{{SOMETHING}}\"\n\n# Permitted redirect URLs. You shouldn't have to change this\nPERMITTED_REDIRECT_URLS=\"https://c2c-us.smartthings.com/oauth/callback,https://c2c-eu.smartthings.com/oauth/callback,https://c2c-ap.smartthings.com/oauth/callback\"\n\n# Client ID and secret of your ST Schema connector, from the SmartThings dev workspace\nST_CLIENT_ID=\"{{CLIENT_ID}}\"\nST_CLIENT_SECRET=\"{{CLIENT_SECRET}}\"\n\n# Credentials, region, and DynamoDB table names for this application. You can delete these if you are setting your\n# AWS credentials in some other way\nAWS_REGION=\"us-east-1\"\nAWS_ACCESS_KEY_ID=\"{{YOUR_ACCESS_KEY}}\"\nAWS_SECRET_ACCESS_KEY=\"{{YOUR_SECRET_KEY}}\"\n\n# DynamoDB tables. You don't have to change these. They will be created if they don't already exist when you start the app\nDYNAMODB_TABLE_NAME=\"sts_oauth_example\"\nDYNAMODB_SESSION_TABLE_NAME=\"sts_oauth_example_sessions\"\n```\n\n## Install NPM modules\n```\nnpm install\n```\n\n## Running Server\nRun the following command in the root directory to start the server. If the DynamoDB tables specified in the `.env` file\ndon't exist they will be created\n```\nnode server.js\n```\n\nWhen the server starts it will print out information you will use later to log in and create devices and\nconfigure your ST-Schema connector. For example:\n```\nHome:              https://yourserver.ngrok.io\nLogin:             https://yourserver.ngrok.io/login\nDevices:           https://yourserver.ngrok.io/devices\nOAuth Test:        https://yourserver.ngrok.io/oauth/login?client_id=my-client-id-xyzabc123\u0026response_type=code\u0026redirect_uri=https://yourserver.ngrok.io/redirect\u0026state=xxxyyyzzz\n\nST Connector Hosting:\nTarget URL:        https://yourserver.ngrok.io/schema\n\nST Connector Device Cloud Credentials:\nClient ID:         your-client-id\nClient Secret:     your-client-secret\nAuthorization URI: https://yourserver.ngrok.io/oauth/login\nRefresh Token URL: https://yourserver.ngrok.io/oauth/token\n```\n\n## Creating an Account and Adding Devices\n\nOnce the server is running you can create an account back access it in a browser at:\n\n`https://${SERVER_URL}/login`\n\nEnter an email address and password and click _Create New Account_. Once you are signed in click the\n_Create your first device_ link to create a device. You can create more devices, delete devices, and log\nout using the [...] menu at the top of the page.\n\n## Creating an ST Schema Connector\n\nGo to [SmartThings Developer Workspace account](https://smartthings.developer.samsung.com/workspace/) and\ncreate a new ST-Schema device integration.\n\nFill in the fields on the _Hosting_ and _Device Cloud Credentials_ tabs using the information printed\nout when you started your server.\n\nAfter you create your connector in the Developer Workspace, copy the client ID and client secret values\nit shows you into the `ST_CLIENT_ID` and `ST_CLIENT_SECRET` entries in the `.env. file and restart the server.\n\n## Installing your ST Schema Connector\n\nInstall the SmartThings mobile app from the [iOS App Store](https://apps.apple.com/us/app/smartthings/id1222822904)\nor [Google Play Store](https://play.google.com/store/apps/details?id=com.samsung.android.oneconnect),\nlog in with the same email address and password used for your developer workspace account, and \ncreate a location (if you have not already done so)\n\nPut the SmartThings mobile app in [developer mode](https://smartthings.developer.samsung.com/docs/guides/testing/developer-mode.html) and tap the \"+\" button at the top to\nadd a device. Scroll down to _My Testing Devices_ tap on it, and select your connector. Complete\nthe OAuth login process and return to the Devices page. You should see all of the devices you created \nin you web application.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartthingscommunity%2Fst-schema-oauth-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartthingscommunity%2Fst-schema-oauth-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartthingscommunity%2Fst-schema-oauth-example/lists"}