A Credential is simply a credential issued by the Cluster to a certain User in the form of a JWT-like token in order 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 IdP IdentityProvider such as OpenID Connect or SAML 2.0 (read more here). A Credential can be configured to have an expiration date, 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 has currently 3 types of Credentials: authentication tokens, OAuth2 Client Credentials and access tokens.

Authentication Tokens

Authentication tokens are mainly used to authenticate WORKLOAD Users. Authentication tokens can be used by both the client-based mode (i.e. via octelium CLI using the octelium login command) and the client-less mode from within applications. To create an Authentication token Credential, the command octeliumctl create credential is used. Here is an example:

octeliumctl create credential --user microservice1 cred01
# OR
octeliumctl create cred --user microservice1

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

You can also set the Session type for the Sessions to be created by the Credential to either CLIENT or CLIENTLESS via the --session-type flag as follows:

octeliumctl create credential --user microservice1 --session-type client cred01

octeliumctl create credential --user microservice2 --session-type clientless cred02

OAuth2 Client Credentials

Such Credential type enables client-less WORKLOAD Users to authenticate themselves via an ordinary OAuth2 client credentials authentication flow (You can read more about it here). This allow applications that are totally unaware of the existence of the Cluster to authenticate themselves and access the Cluster's publicly exposed Services (read more about the BeyondCorp/client-less mode here) via typical OAuth2 access tokens without having to use additional libraries in your applications (read more about using OAuth client credentials here). Here is an example of how to create OAuth2 client credential:

octeliumctl create cred --type oauth2 --user microservice1 cred02

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 in your HTTP/gRPC requests (i.e. Authorization: Bearer <ACCESS_TOKEN>). The difference between this type and the OAuth2 client credential flow type is that you are now skipping the OAuth2 flow to generate an access token. This might be especially useful for serverless applications triggered by, for example, webhooks and cannot store their own access tokens securely to be used when they are re-executed again. The downside is that this access token is simply static and cannot be refreshed automatically like in OAuth2 where most SDKs can obtain a new access token whenever it's expired 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). Here is an example of how to create an access token Credential:

octeliumctl create cred --type access-token --user microservice1 cred02

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

One-Time Credentials

By default, the Credential has no limitation on the number of times where 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

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

You can attach Policies (read more here) to any Session created by a certain Credential via the --policy flag as follows:

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

A Credential issued token has a unique ID, if a new token is generated for a Credential, the Credential gets 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