Example Web Setup App (Simple Authentication)

Cloud
2

Hey @G65434_2! So excited that you are building a product on Particle! That is a very good question. Providing a redirect_uri allows us to stick to the OAuth spec of the "Implicit Grant Flow." Here's a quick summary of Implicit:

The Implicit Grant flow is used when the user-agent will access the protected resource directly, such as in a rich web application or a mobile app. The client secret is not used.

The user-agent connects to a URL on the authorization server. This could either be a direct connection, or through a redirect made from the client. The request contains the client id, the request scope, and the redirect URL. If the authorization server passes the request, it performs a redirect to the redirect URL with the access token and expiration time in the fragment (after the hash #).

While the redirect URL points to the client, code inside the client (that is, the server-side app) does not see it. Instead, the URL may be used to load JavaScript that takes the access token from the URL and uses it. Or, a mobile app can capture the redirect, extract the access token and use it in its code, in which case the URL may just point to static content.

That is to say, because you are building a web app, OAuth credentials are exposed in the browser and cannot be fully hidden/secured. As a result, using the implicit grant type only requires your OAuth Client ID, but not the Client Secret. The access token is appended to the URL of the redirect_uri after successful authentication with the Particle API. This redirect_uri should be the first step of your device setup after creating a Particle customer.

This all comes into play when you are creating a Particle customer for your web app so that the person can claim a device and generate access tokens to control that device. You will be hitting POST /v1/orgs/:orgSlug/customers to both create the customer and receive an access token back for that customer.

Because you are using the Implicit Grant Flow, you will use the "Implicit" version of the customer creation endpoint, Documented here. From the docs, you'll see that you pass your OAuth client ID as an HTTP header, but not your secret.

After a POST to this endpoint, the Particle API will redirect the customer to the redirect_uri that you provided when creating the OAuth client, and append the access token as a hash to the end of the url (i.e. http://setup.cool.com#123456789). The token is now available for you to grab via JavaScript to use to generate claim codes, complete setup, and allow the user to start controlling their device.

So, to recap:

  • For a web app, you will use the Implicit Grant Flow to protect your OAuth client credentials from being compromised
  • You should set your redirect_uri to be the start of the setup process after a customer has been created
  • This all comes into play when creating customers during device setup, and the API must be hit in a specific way to follow the Implicit Grant Flow
  • If done correctly, the customer will be created in Particle's system correctly, then redirected to start device setup with a scoped access token appended to the redirect_uri

Does this all make sense?

2 Likes