Types

There are currently two types of Users in Octelium:

1. HUMAN Users, utilized by humans. HUMAN Users primarily authenticate themselves via the web portal of the Auth Server using IdentityProviders such as GitHub OAuth2 or any identity provider that supports OpenID Connect or SAML 2.0 (read more about IdentityProviders here).

Here is an example of a HUMAN User:

1
kind: User
2
metadata:
3
  name: alice
4
spec:
5
  type: HUMAN

2. WORKLOAD Users, used by non-human entities such as containers, servers, programmable environments, etc.... By default, WORKLOAD Users have 3 options to authenticate themselves to the Cluster:
   1. Authentication token Credentials
   2. OpenID Connect-based assertion by an external identity provider (read more here).
   3. OAUth2 client credentials Credentials and used by applications written in any programming language to authenticate in a client-less way via the standard OAuth2 client credentials flow (read more here).

Here is an example of a WORKLOAD User:

1
kind: User
2
metadata:
3
  name: k8s-1
4
spec:
5
  type: WORKLOAD

Groups

A User may belong to one or more Groups (more details on Groups can be found here). Here is an example:

1
kind: User
2
metadata:
3
  name: usr-1
4
spec:
5
  type: WORKLOAD
6
  groups: ["group-1", "group-2"]

Email

You can set a primary email address for HUMAN Users to be used as the main identifier with OpenID Connect and SAML 2.0-based IdentityProviders (read more here). Here is an example:

1
kind: User
2
metadata:
3
  name: alice
4
spec:
5
  type: HUMAN
6
  email: [email protected]

Authentication

In addition to using a primary email as a main identifier, A User can have one or more explicit identities that can be used to authenticate the User for a certain IdentityProvider (read more about IdentityProviders here) such as OpenID Connect, SAML 2.0, GitHub OAuth 2 for HUMAN Users. In practice, identities are more useful for WORKLOAD Users when used with OpenID Connect assertions (read more here).

Here is an example of a User that has multiple identities that can be used for authentication:

1
kind: User
2
metadata:
3
  name: usr-1
4
spec:
5
  type: HUMAN
6
  authentication:
7
    identities:
8
    - identityProvider: github
9
      identifier: linus
10
    - identityProvider: okta-oidc
11
      identifier: [email protected]
12
    - identityProvider: saml-idp1
13
      identifier: [email protected]

The identityProvider field is the IdentityProvider name. The identifier is the value used for verification upon obtaining the User's information from the IdentityProvider during the authentication flow. Such information could be the OIDC identity token in the case of an OpenID Connect IdentityProvider or a SAML assertion in the case of SAML 2.0 IdentityProviders. It's important to note that the default value of the identifier depends on the IdentityProvider type:

• For GitHub OAuth2-based IdentityProviders, the identifier is the username (read more here).
• For OpenID Connect IdentityProviders, the identifier, by default, is the value of the email claim in the identity token (read more here).
• For SAML 2.0 IdentityProviders, the identifier by default is the value of the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress attribute. The Cluster administrators can override the default identifier claim in the case of OIDC or identifier attribute in the case of SAML 2.0 (read more here).

Session

Users can interact with the Cluster and access its Services as long as their Sessions are valid. You can set a per-User Session duration value, after which the Session is deemed expired and is automatically deleted by the Cluster (namely by Nocturne). These per-User Session options override the Cluster-wide values set in the ClusterConfig (read more here). Here is an example:

1
kind: User
2
metadata:
3
  name: usr-1
4
spec:
5
  type: HUMAN
6
  session:
7
    clientDuration:
8
      days: 1
9
    clientlessDuration:
10
      hours: 10
11
    maxPerUser: 100
12
    accessTokenDuration:
13
      hours: 4
14
    refreshTokenDuration:
15
      days: 1

Disabling Users

You can disable/deactivate a User and immediately revoke their ability to interact with the Cluster or access its Services. Here is an example:

1
kind: User
2
metadata:
3
  name: usr-1
4
spec:
5
  type: HUMAN
6
  isDisabled: true

To re-activate the User, you simply set the isDisabled field back to false.

Policies

Policies (read more about Policies and access control here) can be created and/or attached to User where they serve as principal-based policies for a specific User. Here is an example:

1
kind: User
2
metadata:
3
  name: john
4
spec:
5
  type: HUMAN
6
  authorization:
7
    policies: ["policy-1", "policy-2"]
8
    inlinePolicies:
9
      - spec:
10
          rules:
11
            - effect: DENY
12
              condition:
13
                match: 'ctx.service.metadata.namespace == "production"'

Listing Users

You can list the Cluster's Credentials as follows:

octeliumctl get user
# Or simply
octeliumctl get usr

# Show a certain User
octeliumctl get usr <NAME>

Privileged Users

Octelium, by design, has no inherent concept of an "admin" or "superuser" User by default. All access to any Service including to the Cluster API Servers (note that the API Servers are deployed as typical Octelium Services) has to be explicitly allowed by a Policy (read more about access control here). It should be noted that Octelium's API Server itself is exposed to Users as an ordinary gRPC Service.

The closest to an "administrator" privilege that can be granted to a certain User is to attach a Policy or add an InlinePolicy that allows all access for that User. For example, you can achieve that via an InlinePolicy as follows:

1
kind: User
2
metadata:
3
  name: john
4
spec:
5
  type: HUMAN
6
  authorization:
7
    inlinePolicies:
8
      - spec:
9
          rules:
10
            - effect: ALLOW
11
              condition:
12
                matchAny: true

Alternatively, you can attach the allow-all Policy that's installed automatically upon the Cluster installation as follows:

1
kind: User
2
metadata:
3
  name: john
4
spec:
5
  type: HUMAN
6
  authorization:
7
    policies: ["allow-all"]

It's very important to understand that ALLOW rules are overridden by DENY rules of the same or higher priorities. Therefore, the above Policy/InlinePolicy rule only guarantees full access as long as there are no DENY rules overriding it in any of the one or more Policies that are relevant for a certain request (i.e. any rules of any of the Policies and InlinePolicies attached to the Session,the User, the User's Groups, Device if available, as well as the Service and its Namespace). You can read in detail about Policies and access control here.

Attributes

You can extend the information of a User by providing it additional, whether manually or dynamically, via the APIs (read more here) from external sources (e.g. IAM platforms, SIEM tools, threat intelligence tools, incident alerting and on-call management tools, etc...). Such additional information can be especially useful for extending access control and making it as fine-grained and dynamic as you wish (read more here). Here is an example:

1
kind: User
2
metadata:
3
  name: john
4
spec:
5
  type: HUMAN
6
  email: [email protected]
7
  attrs:
8
    pagerDuty:
9
      onCall: true
10
    azureAD:
11
      isAdmin: true
12
    isFriend: true
13
    age: 27
14
    anotherTool:
15
      key1: val1
16
      key2: 100
17
      key3: true
18
      key4:
19
        subKey1: subVal1