A Credential is simply a credential issued by the Cluster to a certain User in the form of a confidential token to be used later for authentication. Credentials are typically, but not necessarily, created for WORKLOAD Users since HUMAN Users should almost always authenticate with an IdentityProvider such as OpenID Connect or SAML 2.0 (read more here). A Credential can be configured with an expiration date, and can also have a set of Policies and inline Policies attached to it that are automatically copied to the Sessions created by the Credential upon a successful authentication.

Types

Octelium currently has 3 types of Credentials: authentication tokens, OAuth2 Client Credentials, and access tokens.

Authentication Tokens

Authentication tokens are primarily used to authenticate WORKLOAD Users. Authentication tokens are mainly used for authentication in the client-based mode (i.e. via octelium login and octeliumctl login commands). To create an authentication token Credential for a certain User, use the command octeliumctl create credential as follows:

octeliumctl create credential --user my-user my-auth-token
# OR let the CLI automatically generate a name for you 
octeliumctl create cred --user my-user

# The output should be something like
Authentication Token: AQpA0f-8AQE2SLLZG3UDvviNBBd91MmmKA6penqXXZS00N6tOe4Fhpjl7LmqKSnKvAOBM8nSYePFfSOGbPRzS0HEBRI4CAMSEDfsj7P_gUROri5QfX1GW6saEB2QDbTszEk5ms781BM665YiECaG6zEGQEhXvIqBVrEqHuw

Now the authentication token holder can use it to authenticate (read more here) as follows:

export OCTELIUM_DOMAIN=<DOMAIN>
octelium login --auth-token=<AUTH_TOKEN>
# OR
octeliumctl login --auth-token=<AUTH_TOKEN> 

OAuth2 Client Credentials

Such a Credential type enables clientless WORKLOAD Users to authenticate themselves via an ordinary OAuth2 client credentials authentication flow (You can read more here). This allows applications that are totally unaware of the existence of the Cluster to authenticate themselves to the Cluster, via a standard OAuth2 /token endpoint that is located at https://<DOMAIN>/oauth2/token, to access the Cluster's publicly exposed Services (read more about the BeyondCorp/clientless mode here) via typical OAuth2 bearer access tokens without using any special libraries or SDKs in your applications (read more about using OAuth client credentials here). Here is an example of how to create OAuth2 client credentials Credential:

octeliumctl create cred --type oauth2 --user my-user my-oauth2
# OR let the CLI automatically generate a name for you
octeliumctl create cred --type oauth2 --user my-user

Client ID: spxg-cdyx
CLient Secret: AQpAN9OT1az6DQH69dNklhretPxlGjJ_qoXuwLMJfMNHwUiLsFGmixmU9klBjw2QLr1TNhgc9PzeL2bVYjeAYMnZDxI4CAMSEDfsj7P_gUROri5QfX1GW6saEKCiOwWyf0LDuE-9Fu8seI0iEPMGpIZKlUTknLzFO6uJH_8

Access Tokens

You can also generate access tokens for WORKLOAD Users and use such tokens directly as standard bearer tokens to access any HTTP-based Service, including the API Server, in your HTTP/gRPC requests from within the Authorization: Bearer <ACCESS_TOKEN> HTTP request header. Here is an example:

octeliumctl create cred --type access-token --user my-user my-access-token
# OR let the CLI automatically generate a name for you
octeliumctl create cred --type access-token --user my-user

Access Token: AQpArnTiiWeM4B_qFM9vfvctBrDuBsYruNa3zdOTOT9j1OiLz_RwqY_HW2z-HBQ8X-gmIupo5XZhgmN1eihNgJeuAhJACAESEMtVTdE-T0BJhy0O40xsIqUaECLckVnjWExUs_DierHaG3QiEGSqDxZGTk_mpugpA6dzP28qBgj-poTBBg

You might now wonder what the difference between the OAuth2 client credentials Credential described above and access token Credentials is, since OAuth2 client credentials are used via the Cluster's OAuth2 token endpoint to obtain access tokens. The main difference is that access token Credentials immediately create Sessions upon creating the Credential while OAuth2 client Credentials, just like authentication token Credentials, only create Sessions only after a successful authentication.

Access token Credentials can be especially useful for serverless applications that are invoked frequently, sometimes even simultaneously, in ephemeral, immutable environments that are practically unable to store their own issued access tokens securely to be used when they are invoked later again. The downside for access tokens is that they are static and cannot be rotated automatically like in OAuth2 where most SDKs can obtain a new access token whenever it expires or about to expire. Therefore, you need to make sure that the access token duration for the owner User is long enough for your use case (read more here).

Automatic Name Generation

As show above, you need to specify the User you're creating the Credential for via the --user flag, as well as the Credential name you want to create. Starting from OCtelium v0.18, you can let the CLI automatically create a Credential name for you in the form of <USER_NAME>-<CREDENTIAL_TYPE>-<RANDOM_ID> that will be shown to you upon the Credential creation. Here is an example:

octeliumctl create cred --user my-user

Listing Credentials

You can list the Cluster's Credentials (read more about listing resources here) as follows:

octeliumctl get credential
# Or simply
octeliumctl get cred

# Or list by a certain User
octeliumctl get cred --user john

# Show a certain Credential
octeliumctl get cred <NAME>

One-Time Credentials

By default, the Credential has no limitation on the number of times it can be used to authenticate Users. However, you can explicitly set the Credential to be a one-time Credential where it can be used for authentication only once using the --one-time flag as follows:

octeliumctl create cred --user usr1 --one-time cred01

Max Authentications

The one-time Credential option, set by the --one-time flag, is a special case for a more generic --max-authn flag that enables you to set any arbitrary number for the maximum number of authentications that can be used by a Credential. Here is an example:

# Only use this Credential up to 10 times
octeliumctl create cred --user my-user --max-authn 10

Session Type

By default, an authentication token Credential is used to create CLIENT-based Sessions used by octelium and octeliumctl CLIs. You can, however, override that behavior and explicitly set the type of the Sessions created by a certain Credential to CLIENTLESS via the --session-type in order for the issued authentication token to be used with the clientless mode. This can be useful when issuing authentication tokens to be used within the Octelium Golang-SDK (read more here). Here is an example:

octeliumctl create credential --user my-user-2 --session-type clientless cred01

# Or you can explicitly set the Session type to CLIENT, which is the default value
octeliumctl create cred --user my-user --session-type client cred02

Expiration

You can set an expiration for your Credential using the --expire-in flag as follows:

octeliumctl create cred --user usr1 --expire-in 2days cred01

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

Policies

By default, Sessions created by a certain Credential are subjected to Policies and InlinePolicies (read more about Policies and access control here) attached to the User, all of the User's Groups if existent, Device, as well as the _Service and its Namespace. However, you can additionally attach Policies to the Credential to be passed to the Sessions created by it upon a successful authentications. Here is an example:

octeliumctl create cred --user usr1 --policy policy1 cred01

You can also use multiple Policies as follows:

octeliumctl create cred --user usr1 --policy policy1 --policy policy2 cred01

Credential Rotation

Tokens issued by a Credential have a unique ID. If a new token is generated for a Credential, the Credential is rotated and its older token automatically becomes invalid and can no longer be used for authentication. To rotate a Credential, you can use the octeliumctl create cred command with the --rotate flag as follows:

octeliumctl create cred --rotate cred01