Documentation for building OAuth clients

[htdvisser]

Summary

It would be good to write some documentation for registering (and working with) OAuth clients.

Why do we need this ?

To help users integrate The Things Stack with their applications.

What is already there? What do you see now?

ttn-lw-cli commands to manage OAuth clients

What is missing? What do you want to see?

Documentation for how to register, what scopes to ask for, maybe an example OAuth flow.

Can you do this yourself and submit a Pull Request?

Yes

[GMouaad]

This would be very helpful! Thank you in advance :)

[LasaleFamine]

I was just searching something like this, I didn't know even that some CLI command exist yet for OAuth clients registration. I will try with the CLI but would be really helpful to know what's the best approach 👍

[htdvisser]

Since this is now implemented in the Console, here are some starting points for the documentation:

1. 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)

2. 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 issue 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 issue 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

When working with multi-tenant deployments, things get a bit more complicated, but I think this is a good start.

[htdvisser]

Bumping back to triage for re-assignment and planning.

cc: @NicolasMrad

[NicolasMrad]

@nejraselimovic can you handle this?

[nejraselimovic]

@nejraselimovic can you handle this?

Not sure if I understand these concepts completely, but if it's not urgent you can assign it to me and I'll do a bit research and look into it.

[KrishnaIyer]

This is moved to the docs repo; #1784