DRAFT - [EDU-2066] - Add Auth section to Platform #2858
Conversation
GregHolmes
added
DRAFT
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the ✨ Finishing touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
| - /docs/general/authentication | ||
| --- | ||
|
|
||
| Ably provides secure authentication mechanisms across all of its products and services including Pub/Sub, Chat, LiveObjects, Spaces, and Asset Tracking. Before any client or server can interact with Ably services, it must authenticate using an Ably API key or token. |
There was a problem hiding this comment.
We generally go for a front-loaded (active) statement at the beginning of these opening paragraphs. For example, see Publish n Subscribe.
|
|
||
| Key authentication uses your Ably API key directly and is designed for trusted server environments. | ||
|
|
||
| **When to use:** |
There was a problem hiding this comment.
I'd drop the "When to use" for clearer sentences at this intro stage.
| - Secure environments where API keys can be safely stored | ||
| - Backend services and servers | ||
|
|
||
| **Benefits:** |
There was a problem hiding this comment.
Maybe just use "recommendations" type sentences here, we could even introduce a brief use case?
| 3. **Key Secret** (`EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0`) - Private secret for authentication | ||
|
|
||
| **Important:** The key secret should never be shared with untrusted parties or embedded in client applications. | ||
|
|
There was a problem hiding this comment.
I think we need a kind of "how auth works" section. We outline what we offer, but not how we link it together -- and that might be of interest to the user (and we do this in other areas of the docs). For example Push process!
|
|
||
| The `clientId` can be set during authentication and is included in all messages and presence events from that client. | ||
|
|
||
| ## Security Best Practices |
There was a problem hiding this comment.
I think direct sentences would be better here. The explanation that follows the initial statement comes across as less important. I also think we could split these out and add something like an "important" callout in the relevant sections (on this page), for example, we could add "3. Use clientId for user identity - This enables presence and user-specific features" to " Security best practices".
| @@ -0,0 +1,1062 @@ | |||
| --- | |||
| title: Authentication Methods | |||
There was a problem hiding this comment.
We mention security best practices rather boldly in src/pages/docs/platform/auth/index.mdx; however, we don't seem to make a point of it when deep diving into these auth methods. I think this would be a nice addition to add extra value to the user.
| - /docs/auth/token | ||
| --- | ||
|
|
||
| Ably provides multiple authentication methods designed for different use cases and security requirements. This page covers the implementation details for each method and when to use them. |
There was a problem hiding this comment.
This is super generic and bypasses a great opportunity to explain what the user needs to know. For example "use key auth for trusted servers, or token authentication for client apps needing strick control"
|
|
||
| The following table provides guidelines on what to consider when choosing your authentication method. Many applications will most naturally use a mixed strategy: one or more trusted application servers will use basic authentication to access the service and issue tokens over HTTPS, whereas remote browsers and devices will use individually issued tokens: | ||
|
|
||
| | Scenario | [Key](#key-authentication) | [Token](#token-based-authentication) | Description | |
There was a problem hiding this comment.
The description column kind of replicates the yes or no column. Can we try to solve the problem here or give better value? Just an idea (i might be wrong on this one)
|
|
||
| Key authentication is designed for server-side applications where the API key can be securely stored and not accessed by external clients. | ||
|
|
||
| ### Ably API keys |
There was a problem hiding this comment.
This page may be used by a reader wanting more info from a "getting started" section. They may not be the most seasoned dev, I know we aim for senior devs (but they may be the next unicorm 🦄 ). We should at least breifly cover what an API key is as its very basic Ably stuff :)
| ``` | ||
| </Code> | ||
|
|
||
| ## Token-based authentication |
There was a problem hiding this comment.
This still assumes a high understanding of how token auth patterns work. A little more hand-holding is needed here. I get that the target persona is a senior dev, but this is still, IMO, basic learning material needed to succeed with Ably.
Description
This is the introduction of an Auth section in Platform. The structure and content of this is ready for an initial review. The idea of this would be the foundation of all the authentication, then each product will have their own auth section branched from this.