A User can interact with the Cluster and access its Services only through a valid Session that is automatically created by the Cluster upon a valid authentication. A User needs to periodically re-authenticate in order to keep the Session valid until it eventually expires. A Session can be either client-based or client-less:

• CLIENT is used by the octelium and octeliumctl clients.
• CLIENTLESS is used by HUMAN User via browsers or by WORKLOAD Users via the OAuth2 client credentials flow (read more here), direct access tokens (read more here), or simply via the SDK (read more here).

Session Tokens

Whenever a User successfully authenticates to the Cluster, the Cluster issues 2 JWT-like tokens to the User representing the Session's validity:

• Access token Used to access the Cluster's Services and is sent as a bearer token via the Authorization: Bearer <TOKEN> or X-Octelium-Auth: <TOKEN> headers or via an "HttpOnly" cookie for client-less browser requests. An access token should be considered a short-term credential. By default, the Cluster sets that duration to 4 hours. Once the access token expires, the User must re-authenticate in order to obtain new valid token-pair in order to be able to once again interact with the Cluster and access its Services.
• Refresh token Used to interact with the Cluster Auth API. The Auth API provides various gRPC methods for the Users to primarily re-authenticate themselves and log out from the Cluster. A refresh token has a longer duration than an access token (for example it is by default set to 16 hours for HUMAN Users). Once a refresh token expires before another re-authentication, the Session as a whole is considered expired and it's due automatic deletion by the Cluster. In other words, an expired refresh token means that the Session itself is expired and the User can no longer re-authenticate, and has to authenticate to the Cluster over again to obtain another Session and be able to interact with the Cluster once again.

Access tokens and refresh tokens are nearly identical. A token is similar to a JWT but it uses protobuf instead of json mainly to reduce its size. A token includes a payload/content and a signature for that payload. The payload has a few claims: a type (i.e. access token or refresh token), a subject (i.e. the Session UID), a token ID that is rotated with every re-authentication to keep track of the current valid token, a key ID to denote the corresponding key that signed the token and an expiry timestamp.

It's important to understand that just because an access token is valid and has not been expired, that does not mean that it will be accepted by the Cluster, namely Octovigil, to access a certain Service since all authorization is dynamically evaluated from within the Cluster side (read more about access control here) on a per-request basis. Even if the token's expiry timestamp hasn't been exceeded, the Session can still be refused if it has already been deleted either manually (i.e. via the octeliumctl delete session command) or by the Cluster. In other words, a valid signature of an access token is necessary but not sufficient to fully authenticate and authorize a request. It's also important to note that the authentication for client-based requests is done via the client private IP address that is tied to the x25519 identity in the case of WireGuard and not via the access token.

You can control the Cluster-wide default durations for both the access token and the refresh token, as well as the Session whole durations, in the ClusterConfig. Read more here. You can also control the Session durations on a per-User basis here.

Approving Sessions

You can approve a Session simply as follows:

octeliumctl update session --approve <SESSION_NAME>

Rejecting Sessions

You can reject a Session simply as follows:

octeliumctl update session --reject <SESSION_NAME>

Rejected Session are still managed by the Cluster but their Users are not authorized to access the Cluster APIs or Services until they are approved again.

Expiration

You can manually change the expiration date for a Session using the --expire-in flag as follows:

octeliumctl update session --expire-in 2days <SESSION_NAME>

Some examples are 600seconds, 45minutes, 7hour, 3days, 2weeks, 6months.

Deleting a Session

You can also delete a Session as follows:

octeliumctl delete session <SESSION_NAME>

Access Control

You can control access to Services in your Policies based on the Session information. Here is an example:

1
kind: Policy
2
metadata:
3
  name: session-misc
4
spec:
5
  rules:
6
    - effect: ALLOW
7
      condition:
8
        any:
9
          of:
10
            - match: 'ctx.session.status.type == "CLIENT"'
11
            - match: 'ctx.session.status.type == "CLIENTLESS" && ctx.session.status.isBrowser'
12
    - effect: ALLOW
13
      condition:
14
        all:
15
          of:
16
            - match: 'ctx.session.status.authentication.info.type == "AUTHENTICATION_METHOD"'
17
            - match: 'ctx.session.status.authentication.info.identityProvider.type in ["OIDC", "SAML"]'