> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Identity Pools on StreamNative Cloud

<Note title="Note">
  This feature is currently in **Private Preview**. To access this feature, you need to join our [Early Access Program](https://hs.streamnative.io/early-access-program-for-streamnative).

  Please note that currently, StreamNative Cloud only supports managing identity pools through [`snctl`](/tools/cli/snctl/snctl-overview). Support for the Console and Terraform will be available soon.
</Note>

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)](/cloud/security/access/rbac/cloud-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](/cloud/security/authentication/oidc-identity-providers/manage-oidc-identity-providers#register-an-o-auth-oidc-identity-provider)

## Create an identity pool

<Tabs>
  <Tab title="snctl">
    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](#identity-pool-filters) for more information about the expression syntax.

    ```bash theme={null}
    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:

    ```yaml theme={null}
    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:

    ```bash theme={null}
    snctl create identitypool -f identitypool.yaml
    ```

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

    ```bash theme={null}
    snctl get identitypool <pool-name> -o yaml
    ```

    You should be able to see the status of the identity pool as `Ready`.
  </Tab>
</Tabs>

## 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:

<Tabs>
  <Tab title="snctl">
    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:

    ```bash theme={null}
    snctl apply -f identitypool.yaml
    ```

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

    ```bash theme={null}
    snctl get identitypool <pool-name> -o yaml
    ```
  </Tab>
</Tabs>

## Delete an identity pool

<Warning title="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.
</Warning>

<Tabs>
  <Tab title="snctl">
    You can delete an identity pool by running the following command:

    ```bash theme={null}
    snctl delete identitypool <pool-name>
    ```
  </Tab>
</Tabs>

## List identity pools

<Tabs>
  <Tab title="snctl">
    You can list all identity pools by running the following command:

    ```bash theme={null}
    snctl get identitypool
    ```

    You should be able to see the list of identity pools.
  </Tab>
</Tabs>

## 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)](https://github.com/google/cel-spec), 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:

```yaml theme={null}
claims.iss == "google" && (claims.principal == "user1" || claims.principal == "user2")
```

## Grant access to an identity pool

<Note title="Note">
  To grant access to an identity pool, you need to have the RBAC feature enabled for your StreamNative organization.
</Note>

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

```bash theme={null}
snctl create rolebinding <binding-name> --role <role-name> --identitypool <identitypool-name>
```

Learn more about role bindings in [RBAC](/cloud/security/access/rbac/cloud-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:

```bash theme={null}
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:

```bash theme={null}
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.