Manage Identity Pools on StreamNative Cloud

Note

This feature is currently in Private Preview. To access this feature, you need to join our Early Access Program.

Please note that currently, StreamNative Cloud only supports managing identity pools through snctl. Support for the Console and Terraform will be available soon.

Once you have registered an OAuth/OIDC identity provider, you can use identity pools to manage the access of external application identities. An identity pool is a group of external application identities that are assigned a certain level of access based on a claims-based policy. The use of identity pools is defined by the pool filter expression. Access is controlled by using role-based access control (RBAC).

You can use the following instructions to create, read, update, list, and delete identity pools.

Prerequisites

Before managing identity pools, ensure you have:

A StreamNative Cloud account with Super Admin privileges
An OAuth/OIDC identity provider registered

Create an identity pool

You can create an identity pool by running the following command. Note that the provider-name must be the name of an existing OAuth/OIDC identity provider. The expression parameter specifies which identities can authenticate using this pool based on their claims. See identity pool filters for more information about the expression syntax.

snctl create identitypool <pool-name> \
  --description '<pool description>' \
  --provider-name '<provider name>' \
  --expression 'claims.sub==abc'

Alternatively, you can prepare a manifest file identitypool.yaml as follows:

apiVersion: cloud.streamnative.io/v1alpha1
kind: IdentityPool
metadata:
  name: <pool-name>
  namespace: <namespace>
spec:
  description: '<pool-description>'
  expression: 'claims.sub==abc'
  providerName: '<provider-name>'

Then, you can create an identity pool by running the following command:

snctl create identitypool -f identitypool.yaml

You can use snctl get identitypool to check the status of the identity pool.

snctl get identitypool <pool-name> -o yaml

You should be able to see the status of the identity pool as Ready.

Update an identity pool

You can update the description and filter expression of an identity pool. However, when you update the filter expression, ensure that the change does not disrupt applications and services that use the identity pool.

To update an identity pool, follow these steps:

You can update an identity pool by editing the identity pool object with snctl edit or by editing the manifest file identitypool.yaml and then applying the changes by running the following command:

snctl apply -f identitypool.yaml

You can check the status of the identity pool by running the following command:

snctl get identitypool <pool-name> -o yaml

Delete an identity pool

Warning

Deleting an identity pool is irreversible and will remove all the information associated with the identity pool. This can cause disruption to the applications and services that use the identity pool.

You can delete an identity pool by running the following command:

snctl delete identitypool <pool-name>

List identity pools

You can list all identity pools by running the following command:

snctl get identitypool

You should be able to see the list of identity pools.

Identity pool filters

Identity pool filters allow you to control which identities can authenticate using an identity pool by evaluating their OIDC claims. Each identity pool requires at least one filter to determine which identities are allowed access.

The filters are written using Common Expression Language (CEL), a simple but powerful expression language that evaluates claims from the OIDC provider.

CEL filter expressions

The following table lists the supported CEL filter expressions and how to use them:

All token fields used in filter definitions must be prefixed with claims. For development purposes, you can temporarily set the filter to true to allow all identities with a valid token to authenticate.

Use case	CEL expression
Equality	`claims.iss == "google"`
Inclusion	`claims.appid in ["app1", "app2"]`
	`!(claims.appid in ["app1", "app2"])`
	`'admins' in claims.groups`
	`!('admins' in claims.groups)`
Presence check	`has(claims.iss)`
	`!has(claims.iss)`
Prefix matching	`claims.principal.startsWith("user")`
Suffix matching	`claims.principal.endsWith("user")`

For more complex use cases, use the following operators:

Use case	Operator precedence	CEL expression
Logical NOT	1	`!(claims.iss == "google")`
Logical AND	2	`claims.iss == "google" && claims.principal == "user1"`
Logical OR	3	`claims.iss == "google" \|\| claims.principal == "user1"`

The rules can grouped into parentheses to form more complex expressions, like this Expression && (Expression || Expression). For example:

claims.iss == "google" && (claims.principal == "user1" || claims.principal == "user2")

Grant access to an identity pool

Note

To grant access to an identity pool, you need to have the RBAC feature enabled for your StreamNative organization.

After creating an identity pool, you can grant access to it by creating a role binding.

snctl create rolebinding <binding-name> --role <role-name> --identitypool <identitypool-name>

Learn more about role bindings in RBAC.

Verify OIDC Token

Now, you can verify whether an exchanged OIDC token from your OAuth/OIDC identity provider is able to match the identity pool. You can use the following command to verify it:

curl -X GET <broker-admin-service-url>/admin/sn/oidc/v1/getPrincipals -H "Authorization: Bearer <super-user-api-key>" -H "Content-Type: application/json" -H "token: '<OIDC-token>'"

Please replace the following placeholders with your actual values:

<broker-admin-service-url>: The URL of the broker admin service of your StreamNative Cloud cluster.
<super-user-api-key>: The API key of a Service Account with the Super Admin permission.
<OIDC-token>: The OIDC token exchanged from your OAuth/OIDC identity provider to verify.

Verify the role binding of an identity pool

You can verify the role binding of an identity pool by running the following command:

curl -X GET <broker-admin-service-url>/admin/sn/rbac/v1/role-bindings/<identitypool-name> -H "Authorization: Bearer <super-user-api-key>" -H "Content-Type: application/json"

Please replace the following placeholders with your actual values:

<broker-admin-service-url>: The URL of the broker admin service of your StreamNative Cloud cluster.
<super-user-api-key>: The API key of a Service Account with the Super Admin permission.
<identitypool-name>: The name of the identity pool to verify.