Changes To Personal Access Tokens (PAT)

Announcements Platform Updates
1

As part of SmartThings’ ongoing work to improve our platform and deliver a high-performing and secure smart home experience for our users, we’re making some changes to how personal access tokens (PATs) work.

PATs were originally intended as a way to test and evaluate new integrations and SmartApps on the SmartThings platform. Since SmartThings provided an easy way to generate PATs over 10 years ago, they’ve been used extensively by our developer community to create and share new devices and unique integrations.

Unfortunately, their very nature (easy to generate, very wide scopes/permissions, and basically anonymous) have also become a problem over the years. The use of PATs for long-lived integrations was never their intent and presents a problem for how we manage the platform going forward. They’re a security risk due to the lack of scope restrictions. They’re incredibly opaque - we can’t really tell who’s using them or how, making management of our architecture and development of new features a challenge. There are also better ways to integrate with SmartThings, such as the widely used OAuth2 standard, which provides a much better authentication structure and flow with appropriate scope restrictions.

Starting at the end of December, we’re going to make some proactive changes to how PATs are issued to get back to their original intended uses - for testing, development, and evaluation of the SmartThings platform. As of 30 Dec, we will start restricting the TTL (time to live) of newly issued PATs to 24hrs. We will also lower the rate limits on the /devices endpoint for newly issued PATs. Both of these changes are intended to improve the security of the platform and give us better control over ingress routes to prevent disruption to the whole platform from potential accidental or intentional bad actors.

Two important things to note:

  1. These changes only impact newly issued PATs. As of now we’re not making any changes to existing PATs. We know that of the 40k or so PATs in active use, a number of those are being used for critical integrations for users’ locations such as the 20k or so being used for HomeAssistant. We don’t want to break that functionality and before we would consider making any changes to existing PATs, we’d want to have a paved path to keep our users’ locations functioning reliably.

  2. If you have an integration that requires generating new PATs for ongoing access, we’d encourage you to refactor that to use an OAuth flow so that it doesn’t rely on issuing new PATs to work in the future.

We’ve tried to design these changes in a way that safeguards the platform but also respects the existing use cases we know about (primarily ones like HomeAssistant, InfluxDB, and development via the CLI). Since the use of PATs is highly opaque to us though, we’d really appreciate discussion from our users on other uses of existing PATs so that we’re aware of those going forward.

5 Likes
2

Very interesting…

2 Likes
3

Odd. I only ever use this forum with New, Latest and Unread, and yet I only discovered this post when another user told me about it.

There’s not a lot to challenge really. OK I don’t understand why the PATs ever had such a long TTL to start with, apart from the sheer inconvenience of having to access a web page to generate them. A choice of one day/week/month would have been plenty had it been possible to generate them more easily using, for example, the CLI or a single API call.

I also feel the time to address the unintended usage was when it was first detected.

3 Likes
4

To address the question of PAT usage:

  1. I use a PAT with curl on the command line to access the API at the user level. If I could get a PAT easily from the command line I would happily do that daily as I already extract the CLI token for things that can do that a PAT can’t.
  2. I use a PAT to override the default user in the CLI. Again I would happily generate that PAT daily if it weren’t such a pain.
  3. I use a PAT for a private app I have been using for years to cross-reference the API at a user level. I could easily change to a WebHook SmartApp but the app tokens would be Location based and although they can do things a PAT can’t there is a lot they can’t do. Indeed I probably need both. I would have to jump though a number of unwanted hoops to create an OAuth app and you could hardly call the process well documented. This is where I will have issues as although my PATs are older than I’d like they have been changed many times, and it only takes a useful extra scope to be added (like read-only access to some of the more interesting hub stuff) to force my hand.

It seems to me that I am using PATs pretty much as intended, or at least in the spirit they are intended for. Far from having too wide a scope I am constantly frustrated by their limited scopes in a number of areas. I would happily reject use of PATs with too many privileges if I knew how (even though I am the only user of my app).

I am not a Home Assistant user so I wasn’t aware of widespread inappropriate use of PATs. I was aware of one being required temporarily to bootstrap a service by installing a SmartApp, or something like that. That seemed perfectly reasonable, though having to use one with a TTL of about fifty years was less so.

5

This topic only popped up as new today even though it was posted on 12/13.

Unfortunately, PATs are used for many 3rd party tools like ConstantGraph and the API Browser+ and while the existing PATs will continue to work for those tools, the 24 hour TTL will limit the ease of use for these (and other) tools for new users.

Exacerbating the issue, some developers who’ve created tools are no longer part of the ST community. API Browser+ was developed by a community developer who is no longer around so there is no opportunity for that tool to be updated to using OAuth (unless someone else picks up development) which means new users of that tool are limited to 24 hours before having to regenerate new credentials. That will serverly impact the ease of use for that useful tool.

4 Likes
6

I use one PAT with the only permission being to run scenes, the narrowest scope / permission I found, hardly a security risk even if someone knew the PAT.

It’s used by a Macrodroid routine in Android TV that will make a HTTPS request to run some lights automations in SmartThings when the TV is on / off / playing.

If I didn’t have that PAT, with the new TTL being 24 hours, I don’t know if I’d have a workaround. Generating a new one each day and editing the macros each day clearly would not cut it.

7

This is a big change for many of the community written and supported tools. It is unreasonable to have them be unable to take on new users until they are rewritten, which could take several months given that these are volunteer efforts. You should:

  1. Defer these changes by 6 months, providing time for rewrites to occur
  2. Pin this post in the announcement and developer categories here, and
  3. Post this info on the developer portal and the PAT generation pages. I just looked and this info does not seem to be there.

Deprecation of PATs as a persistent permission mechanism is a big deal. Perhaps not as big as the shift to Edge drivers, but still non-trivial. Samsung needs to respect the developer community and provide an adequate timeframe for this transition, with a lot of communication and information along the way.

8 Likes
8

It was created on 12/13 but we waited until today to make it public. We are listening to your feedback.

1 Like
9

I don’t know anything about the architecture of ConstantGraph but I am still surprised that it uses a PAT.

On the other hand API Browser+ is a completely client side app. It seems perfectly reasonable to use a PAT for that. Again a TTL of a month would have been plenty.

10

Me neither :slight_smile:

Well, there is a server component to it as well because I host it :slight_smile: Yes, the actual API calls are submitted by the client browser, but the syntax of the API calls is built on the server side.

1 Like
11

Agreed, many developer friendly apps and diagnostics apps including the CLi are going to be hurt the most.

Maybe the solution would be to have users sign up for a developer account and then issue permanent PAT’s to these accounts. It’s going to have to suck to create a new PAT every time we decide to push driver updates or use diagnostics apps (and possibly reduce the incentive to continue developing). There needs to be a balance between analytics and ease of development.

5 Likes
12

When discussing PAT usage, I forgot to mention a couple of other points related to how I use one in an app.

  1. I suck just about everything I know out of the API. I try to minimise API calls as they can be expensive. A single call to the device API takes broadly the same time whether it pulls down hundreds of devices with full status and health data, or just some information on a single device. Sometimes you need individual calls though. The last thing I want is any rate limiting, it is slow enough already.

  2. My app will maintain a copy of all the data I’ve read on my server. This will get updated on my request or automatically every couple of weeks. I can choose to use this instead of the API if I don’t need the latest data. This also means if something bad happens to my installation I have a relatively recent dump of just about anything I may need to know to reinstate it. This is encrypted using the PAT as a key, though it doesn’t have to still be valid. I am rather depending on the persistence of the PAT though. Having to change the PAT every month, say, would be doing me a favour in some ways as it would give me a history of backups. However anything less than that would probably be too often.

So:

  • Make the PAT easier to generate, replace and destroy via the command line (and so in scripts) then most of my PATs could be 24 hours and things would be all the better for it.
  • If 24 hours is the only option then I am somewhat screwed as persistent PATs have their place for private development tools. A 28 day TTL is realistically the minimum I would be comfortable with, but also a reasonable maximum.
  • I don’t like the sound of rate limiting, though it is all in the detail.
13

In my case I use the API call on Tasker.

When tasker reads from my calendar that it’s a Holiday or I have a Vacation day, it calls the API to activate a virtual switch and that will affect routines.

Before the use of Edge Drivers there was a Device Handler that could access Gmail calendar and search something based on a filter, and in that case I could switch on the virtual device. But now with the Edge Driver there is nothing that could read Google Calendar…

So, I don’t know how could I achieve this behaviour with the new PAT policy of 24h only…

1 Like
14

That’s going to inconvenience a number of users and although it is more on the day to day use side of the production/development fence it doesn’t seem that unreasonable a use of a PAT to me as it is still a very personal thing. It is again a case where a 28 day TTL seems a reasonable compromise.

Again the hassle of replacing PATs comes into play. It should be easier to replace an existing PAT with a similarly scoped one. Having to go through selecting scopes every time is tedious. Perhaps being able to define ‘profiles’ for the PAT scopes would be a good thing.

Just as I would like a command line or CLI based way of creating, replacing and deleting PATs, perhaps there needs to be a way of doing it via the mobile app. It could even be placed under Developer options to make that less of an anti-climax. Visiting a web page just seems very ‘out of band’ since the demise of the IDE.

15

Edit: There is a critical part of the original post that I managed to overlook before I posted my comment here.

To avoid misleading anyone reading these threads, I’ve deleted the portion of my post that expressed concern about the effect this change might have on existing PATs.

As someone else mentioned in another forum, it’s odd that you think that this is a security issue when you have community edge drivers that can be updated and uploaded to our hubs without our permission and any kind of code check.

2 Likes
16

???

17

Yes, webCoRE in Hubitat. Probably a half-dozen pistons.

18

so technically the PAT is for the integration to Hubitat :slight_smile:

19

No, HubiThings Replica already uses an OAuth flow, but it might need some refactoring to accommodate this change. That’s already being discussed elsewhere.

I make some direct calls via WebCoRE to the SmartThings API that are unrelated to what HubiThings Replica does. Those pistons will absolutely break, including and especially one of the critical profiles I have there.

20

This is offtopic but an evil entity knowing a fully-scoped PAT can do pretty much everything like if it was you, complete control, even mess with your automations.

An evil Edge driver on the other side cannot do much harm. For starters it cannot even communicate outside the LAN, so sending information outside is not an option. And the driver lives in a sandbox, does not know about other devices, does not have access to rules or anything, can’t control anything in your account at all.

Going back to the topic on hand, there are PATs that don’t require full control, can’t have the same limits a fully-scoped PAT and a PAT meant to run a scene from time to time from automation tools like Tasker or Macrodroid which are not web servers and the SmartApp alternative is not an option.