A Credential is simply a credential issued by the Cluster to a certain User in the form of a JWT-like 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 IdP 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.

Listing Credentials

You can list the Cluster's Credentials 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>

Authentication Tokens

Authentication tokens are primarily 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, use the command octeliumctl create credential as follows:

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

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

You can also set the Session type for Sessions 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 a Credential type enables client-less 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 and access the Cluster's publicly exposed Services (read more about the BeyondCorp/client-less mode here) via typical OAuth2 access tokens without using additional libraries 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 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>). 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 only create Sessions when they are used by the applications via the Cluster's OAuth2 token endpoint.

Access token Credentials can be especially useful for serverless applications that are invoked frequently, sometimes even simultaneously, in ephemeral, immutable environments that cannot store their own access tokens securely to be used when they are invoked later again. The downside is that this access token is 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). 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 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

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