Wiki Reference Articles for Session Management and Node Protocols, Gestalt Protocols, Identity Protocols
CMCDragonkai opened this issue · comments
Session management and node protocols include:
- Authentication system and token usage between Client GRPC and PK Agent
- Identity Claim (Augmentation) Process
- Node Claims Process
These wiki articles should go into Reference under js-polykey. As these are library references for how the system works. They are not usecases nor are they theory.
Keep them high level so they don't go out of date. However we should refer to the relevant exceptions expected.
Interacting side effects, and things to be ware of when programming with essential to document.
Use asciiflow to prototype the diagrams first, then use plantuml to finish off, in particular the sequence diagrams. Component diagrams are a more freeform, so they can stay as asciiflow diagrams.
Refer to the network reference article as an example: https://github.com/MatrixAI/js-polykey/wiki/network
Target wiki article is located here: https://github.com/MatrixAI/js-polykey/wiki/Session-Management
Tasks
- - Build component diagrams for all subsystems
- - Build sequence diagrams to illustrate the protocol
- - Introduce user as a lifeline in the sequence diagram to represent what the user does with respect to the Client. Such as providing the password when the user prompts.
- - Introduce concurrent effects in the sequence diagram, especially when multiple calls are updating the session token. To do this, add an additional life-line representing a second Client when it tries to call simultaneously and results in conflict when updating the session token (and thus resolving the update by making usage of lock). The lock itself can be represented as another lifeline.
- - Explain how our session tokens are not OTP tokens but are similar to access-tokens in OAuth2 protocol that uses short lifetimes. It has a similar effect to OTP tokens.
3 additional things missing in the wiki reference for sessions:
- Introduce user as a lifeline in the sequence diagram to represent what the user does with respect to the Client. Such as providing the password when the user prompts.
- Introduce concurrent effects in the sequence diagram, especially when multiple calls are updating the session token. To do this, add an additional life-line representing a second
Clientwhen it tries to call simultaneously and results in conflict when updating the session token (and thus resolving the update by making usage of lock). The lock itself can be represented as another lifeline. - Explain how our session tokens are not OTP tokens but are similar to access-tokens in OAuth2 protocol that uses short lifetimes. It has a similar effect to OTP tokens.
Sequence diagrams should be able to make use of plantuml as these concepts should be well-established in uml formality.
The 3 diagrams that are useful across alot of domains:
- Component Diagrams - these are so freeform it may be better to leave them as ASCIIflow diagrams, especially if a specific layout is required
- Sequence Diagrams - good to use plantuml for
- State Transition Diagrams - these are quite tricky so it's good to use plantuml for these
Gitlab natively supports plantuml, but our wiki will need this provided via plantuml.com and embedded as an image see: https://blog.anoff.io/2018-07-31-diagrams-with-plantuml/. Use this: http://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000
The plantuml should be saved in the wiki as well though to prevent us from losing the diagram code.
@emmacasolin since you are getting sessions stuff working. Your diagrams and documentation work there would satisfy this issue.
You might want to clarify this too:
Explain how our session tokens are not OTP tokens but are similar to access-tokens in OAuth2 protocol that uses short lifetimes. It has a similar effect to OTP tokens.
But this issue also requires moving/copying some content regarding gestalts and identity claims into reference oriented docs too.
Gestalt discovery reference should take some ideas/diagrams from: https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/195#note_597545555
This may be related to the decentralized trust, although this can be a separate document.
Interaction of ACL requires reference documentation as well, it's always been a bit complicated:
- MatrixAI/Polykey#184
- MatrixAI/Polykey#207 (comment)
- https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/188#note_601518284
- https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/199
People always forget how it works.
I've renamed the sessions wiki to "Service Authentication" (https://github.com/MatrixAI/js-polykey/wiki/Service-Authentication) to match the sidebar and updated the information there to include session interception, session token management, the CARL, and the new exceptions. Also created some puml diagrams which I've uploaded to the js-polykey wiki repo and embedded into the wiki page following these instructions: https://blog.anoff.io/2018-07-31-diagrams-with-plantuml/
Renamed to "Session Management" and updated sidebar to match https://github.com/MatrixAI/js-polykey/wiki/Session-Management
@joshuakarp can you review the session management wiki?
@emmacasolin a quick glance, looks really nice. However I think it's missing an architectural diagram that can be derived from:
- MatrixAI/Polykey#236 (comment)
- https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/213#note_728972375
Both of these architectural diagrams should be brought together and integrated into your documentation. These will be essential to understanding where logic is located, not just the flow of execution as you currently have with your sequence diagrams.
Recommend copying the ASCII diagram verbatim, and then adapt the second diagram into ASCII too.
Also are you also diagramming the flow of acquiring parameters too? In terms of PK_PASSWORD and PK_TOKEN for determining unattended or attended?
Also please document the 3 modes of authentication. Details are on the MR comments. I bolded it and we discussed before.
3 modes discussed here: https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/213#note_730292155
Please indicate this by how the tlsConfig is set and how that affects it. Document which modes we are using and why.
Some comments on the session management wiki article:
- I feel this would benefit from a quick paragraph or so about specifically what our session token is doing for Polykey (most likely at the very beginning, before "Starting a Session"). We kind of just start talking about it without giving motivation for it
- There's some discrepancies between spelling of "authorisation"/"authorization" - I believe @CMCDragonkai is preferring US English, so these should all be changed to "authorization"
- "Session Interception" section was really clear - diagram was great, and it's made me understand this process more as well
- "Session Management" diagram: I'm not sure that the 2 final returning blue dotted lines should be there (the "returns requested data B" and "displays requested data B"). Hasn't the call failed, so some kind of error is returned instead?
- "Retrying a CLI Call": I think some of the "programming-speak" should be using
codemarkdown style (e.g.ErrorClientAuthMissing, and perhaps evenPK_PASSWORD) - "This metadata is encoded using the first set value from the following in order:" the wording confused me here a bit. I initially thought this was referring to an actual set. Maybe something like "This metadata is encoded using the first defined value discovered from the following sources (in order of precedence):"
To be clear, session management and CARL is about "authentication" not "authorization".
I think it's missing an architectural diagram that can be derived from:
Draft combined diagram here. I tried to keep as much of both diagrams as I could without making it too confusing, but would appreciate feedback on how clear it is.
@startuml
!theme plain
hide empty description
title Session Management
state "A Unary Call" as UC ##green {
state "Call Option" as CO ##lightskyblue {
state "Call Credential" as CC ##lightskyblue {
}
}
}
state "GRPC Agent" as GA ##green
state "SessionManager" as SM ##lightskyblue
state "Unary Response" as UR ##green {
state "Metadata" as M ##lightskyblue : Session Token
}
state "GRPC Client" as GC ##green
state "GRPC Client" as GC2 ##green
state "GRPC Client" as GC3 ##green
state "Session" as S ##lightskyblue
state "Session" as S2 ##lightskyblue
state "Session" as S3 ##lightskyblue
state "User/CLI" as U ##orange
state "User/CLI" as U2 ##orange
state "GRPC Client" as GC4 ##green
state "Session" as S4 ##lightskyblue
state "\~/.polykey/client/token" as T ##lightskyblue
state "\~/.polykey/client/token" as T2 ##lightskyblue
CC : 1. empty
CC : 2. basic token
CC : 3. bearer token
GC -l[#green]-> UC
UC -d[#green]-> GA
GA -r[#green]-> UR
UR -r[#green]-> GC
GA -u[#lightskyblue]-> SM : generates token
SM -d[#lightskyblue]-> GA : new token
GC -[#lightskyblue]-> S : writeToken
S -[#lightskyblue]-> GC : readToken
GC -[#orange]-> U : prompt pass
U -[#orange]-> GC : password
S -[#lightskyblue]-> T : writeToken
T -[#lightskyblue]-> S : readToken
GC2 -u[#green]-> GA
GC3 -u[#green]-> GA
GC4 -u[#green]-> GA
GA -d[#green]-> GC2
GA -d[#green]-> GC3
GA -d[#green]-> GC4
GC2 -d[#lightskyblue]-> S2
S2 -u[#lightskyblue]-> GC2
GC3 -d[#lightskyblue]-> S3
S3 -u[#lightskyblue]-> GC3
GC4 -d[#lightskyblue]-> S4
S4 -u[#lightskyblue]-> GC4
GC2 -[#orange]-> U2
U2 -[#orange]-> GC2
GC3 -[#orange]-> U2
U2 -[#orange]-> GC3
GC4 -[#orange]-> U2
U2 -[#orange]-> GC4
S2 -d[#lightskyblue]-> T2
T2 -u[#lightskyblue]-> S2
S3 -d[#lightskyblue]-> T2
T2 -u[#lightskyblue]-> S3
S4 -d[#lightskyblue]-> T2
T2 -u[#lightskyblue]-> S4
GC2 -r[hidden]-> GC3
GC3 -r[hidden]-> GC4
S2 -r[hidden]-> S3
S3 -r[hidden]-> S4
UC -d[hidden]-> UR
note bottom of UR #lightskyblue
Session token may
not exist (if call
fails).
end note
note right of UC #lightskyblue
We use a Call Credential
"Generator" by default
which reads the token from
the session and attaches
it as a bearer token. If
the password is supplied
it overrides this as a
basic token. A valid call
must include either a
basic or bearer token.
end note
note bottom of T #lightskyblue
When the GRPC Client receives
a response with a Session
Token in Metadata it needs to
save the new token for
subsequent GRPC calls.
end note
note left of SM #lightskyblue
A new Session Token
is generated on
every GRPC call.
This is done
automatically by
the GRPC Agent.
end note
note bottom of T2 #orange
Clients on the same host share a Session Token.
Concurrency is managed via file locking.
end note
note left of GC2 #orange
There can be multiple
clients on the same
host/user, each one
handling its own call.
end note
note left of GA #green
The GRPC Agent accepts authenticated
requests (calls) from a number of
clients. It will return a response
to the client, and if the request is
valid the response will contain the
requested data along with a new
Session Token in its metadata.
end note
@enduml
Might want to incorporate the https://excalidraw.com/#room=57543403694c95eba2e9,5qJFVQlpWc0vegUgEAQIpA diagram too.
And this:
┌────────────────┐
│ SessionManager │ SessionManager generates and verifies session tokens
Client on different host/user └────────┬───────┘
│
┌───────────────┐ ┌───────┴──────┐
│ PolykeyClient ├───────────────────► PolykeyAgent │ Agent accepts authenticated requests
└───────┬───────┘ └───────▲──────┘
│ │
┌────┴────┐ ┌─────────────────┼─────────────────┐
│ Session │ │ │ │
└─────────┘ ┌───────┴───────┐ ┌───────┴───────┐ ┌───────┴───────┐
│ PolykeyClient │ │ PolykeyClient │ │ PolykeyClient │ Multiple CLI & GUI clients on same host/user
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
┌────┴────┐ ┌────┴────┐ ┌────┴────┐
│ Session │ │ Session │ │ Session │ Session manages token lifecycle
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└─────────────────┼─────────────────┘
│
┌────────────┴────────────┐
│ ~/.polykey/client/token │ Concurrency managed via file lock
└─────────────────────────┘
Shared session token for authenticated requests
For component diagram wise.
Draft combined diagram here. I tried to keep as much of both diagrams as I could without making it too confusing, but would appreciate feedback on how clear it is.
You should change GRPC Agent to GRPC Server to avoid confusion between our client and agent "servers".
Discovery is complex and is worth diagramming. Also consider sequence diagrams for its edge conditions: MatrixAI/Polykey#311 (comment)