search

TheThingsNetwork / lorawan-stack

The Things Stack, an Open Source LoRaWAN Network Server
https://www.thethingsindustries.com/stack/
Apache License 2.0
993 stars 309 forks source link

Documentation for building OAuth clients #1784

Closed htdvisser closed 1 year ago

htdvisser commented 4 years ago

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 commented 4 years ago

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

LasaleFamine commented 4 years ago

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 commented 3 years ago

Blocked on OAuth client management in the Console: #4300

htdvisser commented 3 years ago

Still blocked on #4300, which was pushed to the 2022 Conference milestone, so this will also have to wait a little longer.

htdvisser commented 2 years ago

It looks like @ryaplots didn't manage to address #4300 yet, so since this issue is blocked on that one, we also push it to 2022 Q2.

htdvisser commented 2 years ago

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:

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

htdvisser commented 2 years ago

Bumping back to triage for re-assignment and planning.

cc: @NicolasMrad

NicolasMrad commented 2 years ago

@nejraselimovic can you handle this?

nejraselimovic commented 2 years ago

@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 commented 1 year ago

This is moved to the docs repo; https://github.com/TheThingsNetwork/lorawan-stack/issues/1784