diff --git a/docs/authentication.md b/docs/authentication.md index 4efb03f93..544839b2c 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -35,7 +35,18 @@ The hash algorithm used is SHA-256 ECDSA public key corresponding to the private key being used to sign a message. It is the primary user identity and is used to determine the request originator. -## Session token +## Tokens + +Generally, the request owner, i.e. an account all access control checks are applied to +is taken from the request signature. +However, session and bearer tokens can alter authentication process by making "effective" request owner differ from the actual one. +The general scheme is given by the following picture: + +![Token processing](images/authentication/impersonate.svg) + +It is important to note, that the token is only valid when the request signature corresponds to the actor token is issued to. + +### Session token Session token can override the rules of determining request owner. It is defined in the [frostfs-api](https://git.frostfs.info/TrueCloudLab/frostfs-api/src/branch/master/session/types.proto#L89). @@ -50,7 +61,9 @@ Session token may have some restrictions: 2. Set of operations it applies to. 3. The entity it is given to. This is provided in `session_key` field containing the public key. -## Bearer token +### Bearer token + +Bearer token is generally used for access control but can also affect authentication if `allow_impersonate` flag is set. With this flag it behaves similarly to session token. ## FrostFS ID diff --git a/docs/images/authentication/impersonate.puml b/docs/images/authentication/impersonate.puml new file mode 100644 index 000000000..e9feae6e5 --- /dev/null +++ b/docs/images/authentication/impersonate.puml @@ -0,0 +1,15 @@ +@startuml impersonate +start + +if (The request has bearer token with allow_impersonate=true?) then (yes) + :Treat bearer token issuer as the request owner.; + end +(no) elseif (The request has session token?) then (yes) + :Treat session token issuer as the request owner.; + end +else (no) + :Determine request owner from the request signature.; + end +endif + +@enduml \ No newline at end of file diff --git a/docs/images/authentication/impersonate.svg b/docs/images/authentication/impersonate.svg new file mode 100644 index 000000000..add2c5439 --- /dev/null +++ b/docs/images/authentication/impersonate.svg @@ -0,0 +1 @@ +yesThe request has bearer token with allow_impersonate=true?Treat bearer token issuer as the request owner.yesThe request has session token?nonoTreat session token issuer as the request owner.Determine request owner from the request signature. \ No newline at end of file