The octelium and octeliumctl CLIs currently provide multiple ways for Users to authenticate themselves in order to create a new valid Session in order to able to interact with the Cluster and access its _Services.

Initial authentication can be achieved through one of the following methods:

• Web identity providers (IdPs) such as any OpenID Connect or SAML 2.0 providers (e.g. Okta, Azure AD, etc...). This is available for HUMAN Users.
• Authentication tokens which can be used mainly by WORKLOAD Users but can also be used by HUMAN Users.
• Assertion tokens (e.g. OIDC-based assertions) which are used by WORKLOAD Users.

Users can also re-authenticate their already existent Session via Authenticators and Device authentication to extend the validity of their Sessions.

Web Identity Providers

HUMAN Users can easily login to a Cluster via the command:

octelium login --domain <DOMAIN>
# OR
export OCTELIUM_DOMAIN=example.com
# using octelium
octelium login
# OR using octeliumctl
octeliumctl login
# OR more specifically via the --web flag
octelium login --web

This will open a browser window for the User to authenticate themselves via the available identity providers defined by the Cluster. Once authenticated, the User can then interact with the Cluster via octelium or octeliumctl, connect to the Cluster and access its Services.

Authentication Token

The second way for authenticating Users in order to obtain Sessions is via authentication tokens. You can use the Credential either using octelium login or octeliumctl login. You can also use the authentication token Credential to directly connect to the Cluster in a single step using the octelium connect command without having to use octelium login. This can be useful for running octelium inside containers or other programmable environments. Here are some examples:

export OCTELIUM_DOMAIN=example.com
# using octelium
octelium login --auth-token <TOKEN>
# OR using octeliumctl
octeliumctl login --auth-token <TOKEN>

# Authenticate and connect directly. Useful when used by automated environments (e.g. containers)
octelium connect --auth-token <TOKEN>

OIDC-based Assertion Authentication for Workloads

WORKLOAD Users can use OpenID Connect based assertion to authenticate to the Cluster in a "secret-less" way without having to use an authentication token Credential.

octelium login --assertion <AUTHENTICATION_METHOD_NAME>:<ASSERTION_TYPE>[:<OPTIONS>]

Kubernetes

The Kubernetes mode is designed for WORKLOAD Users running from within Kubernetes pods. It simply looks for the service account ID token stored in the /var/run/secrets/kubernetes.io/serviceaccount/token path and uses it as the assertion.

octelium login --assertion k8s-idp-01:k8s

Azure

This mode works for WORKLOAD Users running on Azure services that support managed identity and can obtain an access token that is used as an assertion (read more here).

octelium login --assertion azure-01:azure

By default, the Cluster domain (e.g. example.com) is used as the audience. You can override the audience as follows:

octelium login --assertion azure-01:azure:audience=custom-aud

GitHub Actions

This mode works for WORKLOAD Users running from within GitHub actions workflows (read more here).

octelium login --assertion gh-01:github-actions

By default, the Cluster domain (e.g. example.com) is used as the audience. You can override the audience as follows:

octelium login --assertion gh-01:github-actions:audience=custom-aud

JWT

For other environments, you can directly use the issued JWT assertion that can be found in either a file path or an environment variable.

Here is an example for a JWT assertion that is stored in a file:

octelium login --assertion jwt-01:jwt:file=/path/to/jwt-file

You can also use a JWT that is stored in an environment variable as follows:

octelium login --assertion jwt-02:jwt:env=JWT_KEY

Registering Device

You can register/enroll or re-register your Device via the octelium auth device register or simply octelium auth dev as follows:

octelium auth dev
# OR using octeliumctl
octeliumctl auth dev

Logout from a Cluster

Logging out simply removes your Session both locally and at the Cluster side. Once you log out from a Cluster, you have to login again through one of the above methods in order to be able to interact with the Cluster again.

# using octelium
octelium logout
# OR using octeliumctl
octeliumctl logout