Documentation for building OAuth clients

[KrishnaIyer]

Summary

Document registering Oauth clients. Replaces https://github.com/TheThingsNetwork/lorawan-stack/issues/1784

Why do we need this ?

To register Oauth clients

What is already there? What do you see now?

No docs

What is missing? What do you want to see?

Document how users can approach building OAuth clients

How do you propose to document this?

From the original issue

OAuth clients can be managed by going to /oauth/oauth-clients on the IS cluster (TTS CE: https://eu1.cloud.thethings.network/oauth/oauth-clients)

When you register an OAuth client, you should keep in mind that it will have to be approved by an admin. The scope and duration of the review process depends on the network where you register your OAuth client. If you register it in your own tenant on The Things Stack Cloud, then the administrator (probably you) can approve it right away. If you register an OAuth client on The Things Stack Community Edition, the administrators will take some more time to review if and how the OAuth client benefits the community. Now that the first requests are coming in, we have started working on defining the review guidelines. Some things that the admins look at are:

The ID and name of the user / organization that owns the OAuth client should clearly identify who is providing the service. For public clients, this should typically be an organization with the brand name as ID. For private/testing clients this can also be a user ID. For personal testing clients, approval should not be needed (we need to work on that; see https://github.com/TheThingsNetwork/lorawan-stack/issues/49). IDs or names that could be confused with official TTN IDs/names will be rejected.
The ID of the OAuth client should ideally consist of the brand name of the application, and the purpose of the OAuth client (example: "mycompany-gateway-onboarding"). Keep in mind that you can't change the Client ID after registration, and you can't re-use the Client ID after deletion.
The name and description should be clear. The name is typically the capitalized form of the ID. The description should explain to users what the application does (example name: "MyBrand Gateway Manager" and description: "Manage your MyBrand gateway from the mobile app")
The redirect URI(s) should work.
The logout redirect URI(s) are optional.
The password grant should never be used. No exceptions.
The refresh_token grant should only be used when non-interactive access is clearly required.
The rights should be appropriate given the name and description of the OAuth client.
Once the OAuth client registration is approved (or once https://github.com/TheThingsNetwork/lorawan-stack/issues/49 is implemented) you can start using the OAuth client with the following settings:

Authorize URL: /oauth/authorize on the IS cluster (TTS CE: https://eu1.cloud.thethings.network/oauth/authorize)
Token URL: /oauth/token on the IS cluster (TTS CE: https://eu1.cloud.thethings.network/oauth/token)
Client ID: The Client ID you picked
Client Secret: The Client Secret that was generated when you registered the client

Can you do this yourself and submit a Pull Request?

Can help document.

[nejraselimovic]

Hey @KrishnaIyer, I've been looking at OAuth docs to see if all is covered. I've noticed that we have this now:

which is a bit different than what was described here https://www.thethingsindustries.com/docs/api/concepts/auth/oauth-access-tokens/, i.e. there is no password and authorization code options to choose, and there is this Enabled option for which I don't understand what it should be representing. Also, there seems to be double Enabled option if I log in as admin, but if I log in as non-admin I can only see one Enabled option. Could you give me a bit context about changes that were done in the meantime so I can update this

[KrishnaIyer]

@nicholaspcr: Can you take a look? This is also good for you to get up to speed with our OAuth system.