mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
Update existing endpoints in API reference to support Identities, update Identities docs
This commit is contained in:
Tuan Dang
54
docs/documentation/platform/identities/overview.mdx
Normal file
54
docs/documentation/platform/identities/overview.mdx
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Identities
|
||||
description: "Programmatically interact with Infisical"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Currently, identities can only be used to make authenticated requests to the Infisical API and do not work with any clients such as [Node SDK](https://github.com/Infisical/infisical-node)
|
||||
, [Python SDK](https://github.com/Infisical/infisical-python), CLI, K8s operator, Terraform Provider, etc.
|
||||
|
||||
We will be releasing compatibility with it across clients in the coming quarter.
|
||||
</Note>
|
||||
|
||||
## Concept
|
||||
|
||||
A (machine) identity is an entity that you can create in an Infisical organization to represent a workload or application that requires access to the Infisical API. This is conceptually similar to an IAM user in AWS or service account in Google Cloud Platform (GCP).
|
||||
|
||||
Each identity must authenticate with the API using a supported authentication method like [Universal Auth](/documentation/platform/identities/universal-auth) to get back a short-lived access token to be used in subsequent requests.
|
||||
|
||||
Key Features:
|
||||
|
||||
- Role Assignment: Identities must be assigned [roles](/documentation/platform/role-based-access-controls). These roles determine the scope of access to resources, either at the organization level or project level.
|
||||
- Auth/Token Configuration: Identities must be configured with auth methods and access token properties to securely interact with the Infisical API.
|
||||
|
||||
## Workflow
|
||||
|
||||
A typical workflow for using identities consists of four steps:
|
||||
|
||||
1. Creating the identity with a name and [role](/documentation/platform/role-based-access-controls) in Organization Access Control > Machine Identities.
|
||||
This step also involves configuring an authentication method for it such as [Universal Auth](/documentation/platform/identities/universal-auth).
|
||||
2. Adding the identity to the project(s) you want it to have access to.
|
||||
3. Authenticating the identity with the Infisical API based on the configured authentication method on it and receiving a short-lived access token back.
|
||||
4. Authenticating subsequent requests with the Infisical API using the short-lived access token.
|
||||
|
||||
Check out the following authentication method-specific guides for step-by-step instruction on how to use identities to access Infisical:
|
||||
|
||||
- [Universal Auth](/documentation/platform/identities/universal-auth)
|
||||
|
||||
**FAQ**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="What is the difference between an identity and service token?">
|
||||
A service token is a project-level authentication method that is being phased out in favor of identities.
|
||||
|
||||
Amongst many differences, identities provide broader access over the Infisical API, utilizes the same role-based
|
||||
permission system used by users, and comes with ample more configurable authentication and security features.
|
||||
</Accordion>
|
||||
<Accordion title="Why can I not create, read, update, or delete an identity?">
|
||||
There are a few reasons for why this might happen:
|
||||
|
||||
- You have insufficient organization permissions to create, read, update, delete identities.
|
||||
- The identity you are trying to read, update, or delete is more privileged than yourself.
|
||||
- The role you are trying to create an identity for or update an identity to is more privileged than yours.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@@ -1,44 +1,34 @@
|
||||
---
|
||||
title: Identity
|
||||
description: "Programmatically interact with Infisical"
|
||||
title: Universal Auth
|
||||
description: "Authenticate with Infisical from any platform/environment"
|
||||
---
|
||||
|
||||
A (machine) identity is an entity that you can create in Infisical.
|
||||
Each identity represents a workload that wishes to access the Infisical API via an authentication method; this is similar to an IAM user in AWS or service account in GCP.
|
||||
**Universal Auth** is the most versatile authentication method that can be configured on an identity from any platform/environment to access Infisical.
|
||||
|
||||
An identity can be provisioned scoped access to resources at the organization or project-level via [role-based access controls (RBAC)](/documentation/platform/role-based-access-controls). For instance, you may create a identity with scoped access to
|
||||
fetch secrets back from the `/` path of the `development` environment in some project.
|
||||
In this method, each identity is given a **Client ID** for which you can generate one or more **Client Secret(s)**. Together, a **Client ID** and **Client Secret** can be exchanged for an access token to authenticate with the Infisical API.
|
||||
|
||||
<Note>
|
||||
The identity feature is in beta.
|
||||
|
||||
Currently, an identity can only be used to make authenticated requests to the Infisical API and does not work with any clients such as [Node SDK](https://github.com/Infisical/infisical-node)
|
||||
, [Python SDK](https://github.com/Infisical/infisical-python), CLI, K8s operator, Terraform Provider, etc.
|
||||
## Properties
|
||||
|
||||
We will be releasing compatibility with it across clients in the coming quarter.
|
||||
</Note>
|
||||
Universal Auth supports many settings that can be beneficial for tightening your workflow security configuration:
|
||||
|
||||
Each identity can be configured an authentication method. The only supported method at the moment is **Universal Auth (UA)**
|
||||
which has the following properties:
|
||||
- Support for restrictions on the number of times that the **Client Secret(s)** and access token(s) can be used.
|
||||
- Support for expiration, so, if specified, the **Client Secret** of the identity will automatically be defunct after a period of time.
|
||||
- Support for IP allowlisting; this means you can restrict the usage of **Client Secret(s)** and access token to a specific IP or CIDR range.
|
||||
|
||||
- In UA, each identity is assigned a **Client ID** for which you can generate one or more **Client Secret(s)**. Together, a **Client ID** and **Client Secret** can be exchanged for an access token (i.e. login operation) to authenticate with the Infisical API.
|
||||
- UA supports restrictions on the number of times that the **Client Secret(s)** and access token(s) can be used.
|
||||
- UA supports token renewal that is the ability to extend the lifetime of a token by its TTL up to its maximum TTL since its creation.
|
||||
- UA supports IP allowlisting; this means you can restrict the usage of **Client Secret(s)** and access token to a specific IP or CIDR range.
|
||||
- UA support expiration, so, if specified, the client secret of the identity will automatically be defunct after a period of time.
|
||||
- UA tracks most recent usage of their client secrets and access tokens; it also keeps track of each token's usage count.
|
||||
## Workflow
|
||||
|
||||
## Using identities
|
||||
|
||||
In the following steps, we explore how to create and use identities for your applications to access the Infisical API.
|
||||
In the following steps, we explore how to create and use identities for your workloads and applications to access the Infisical API
|
||||
using the Universal Auth authentication method.
|
||||
|
||||
<Steps>
|
||||
<Step title="Creating an identity">
|
||||
To create an identity, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**.
|
||||
|
||||
|
||||
|
||||
|
||||
When creating an identity, you specify an organization level [role](/documentation/platform/role-based-access-controls) for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles.
|
||||
|
||||
|
||||
|
||||
|
||||
Now input a few details for your new identity. Here's some guidance for each field:
|
||||
|
||||
@@ -46,6 +36,10 @@ In the following steps, we explore how to create and use identities for your app
|
||||
- Role (required): A role from the **Organization Roles** tab to permit the identity to access certain resources.
|
||||
|
||||
Once you've created an identity, you'll be prompted to configure the **Universal Auth** authentication method for it.
|
||||
|
||||
|
||||
|
||||
Here's some more guidance on each field:
|
||||
|
||||
- Access Token TTL (default is `7200`): The incremental lifetime for an acccess token in seconds; a value of `0` implies an infinite incremental lifetime.
|
||||
- Access Token Max TTL (default is `7200`): The maximum lifetime for an acccess token in seconds; a value of `0` implies an infinite maximum lifetime.
|
||||
@@ -66,9 +60,9 @@ In the following steps, we explore how to create and use identities for your app
|
||||
and password used to authenticate with the Infisical API. With that, press on the key icon on the identity to generate a **Client Secret**
|
||||
for it.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Feel free to input any (optional) details for the **Client Secret** configuration:
|
||||
|
||||
@@ -83,13 +77,13 @@ In the following steps, we explore how to create and use identities for your app
|
||||
|
||||
Next, select the identity you want to add to the project and the role you want to assign it.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Accessing the Infisical API with the identity">
|
||||
To access the Infisical API as the identity, you should first perform a login operation
|
||||
that is to exchange the **Client ID** and **Client Secret** of the MI for an access token
|
||||
that is to exchange the **Client ID** and **Client Secret** of the identity for an access token
|
||||
by making a request to the `/api/v1/auth/universal-auth/login` endpoint.
|
||||
|
||||
#### Sample request
|
||||
@@ -126,12 +120,6 @@ In the following steps, we explore how to create and use identities for your app
|
||||
**FAQ**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="What is the difference between an identity and service token?">
|
||||
A service token is a project-level authentication method that is being phased out in favor of identities.
|
||||
|
||||
Amongst many differences, identities provide broader access over the Infisical API, utilizes the same role-based
|
||||
permission system used by users, and comes with ample more configurable security measures.
|
||||
</Accordion>
|
||||
<Accordion title="Why is the Infisical API rejecting my identity credentials?">
|
||||
There are a few reasons for why this might happen:
|
||||
|
||||
@@ -149,20 +137,4 @@ In the following steps, we explore how to create and use identities for your app
|
||||
|
||||
Note that the max TTL cannot be less than the TTL for an access token.
|
||||
</Accordion>
|
||||
<Accordion title="Why can I not create, read, update, or delete an identity?">
|
||||
There are a few reasons for why this might happen:
|
||||
|
||||
- You have insufficient organization permissions to create, read, update, delete identities.
|
||||
- The identity you are trying to read, update, or delete is more privileged than yourself.
|
||||
- The role you are trying to create an identity for or update an identity to is more privileged than yours.
|
||||
</Accordion>
|
||||
<Accordion title="Can you provide examples for using glob patterns?">
|
||||
1. `/**`: This pattern matches all folders at any depth in the directory structure. For example, it would match folders like `/folder1/`, `/folder1/subfolder/`, and so on.
|
||||
|
||||
2. `/*`: This pattern matches all immediate subfolders in the current directory. It does not match any folders at a deeper level. For example, it would match folders like `/folder1/`, `/folder2/`, but not `/folder1/subfolder/`.
|
||||
|
||||
3. `/*/*`: This pattern matches all subfolders at a depth of two levels in the current directory. It does not match any folders at a shallower or deeper level. For example, it would match folders like `/folder1/subfolder/`, `/folder2/subfolder/`, but not `/folder1/` or `/folder1/subfolder/subsubfolder/`.
|
||||
|
||||
4. `/folder1/*`: This pattern matches all immediate subfolders within the `/folder1/` directory. It does not match any folders outside of `/folder1/`, nor does it match any subfolders within those immediate subfolders. For example, it would match folders like `/folder1/subfolder1/`, `/folder1/subfolder2/`, but not `/folder2/subfolder/`.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
Reference in New Issue
Block a user