# HashiCorp Vault

> Integrate Ironchip with HashiCorp Vault using OIDC: create the application in Ironchip, enable the oidc auth method, and define the policies and roles.

URL: https://docs.ironchip.com/en/identidad/integraciones/puestos/vault/

This guide configures HashiCorp Vault so that users sign in with Ironchip through [OIDC](https://docs.ironchip.com/en/identidad/protocolos/oidc/). It covers the application in Ironchip, the auth method in Vault, and the user and administrator policies and roles.

## Requirements

- Access to the Ironchip admin console.
- A user with permissions to configure Vault.

## Configure Ironchip

In the **Applications** section you can see all the protected services added to Ironchip and their features.

1. Click **New application**. A new window opens.
2. Click **Custom application**.
3. Fill in the parameters of the new application:

   - **Application name**.
   - **Integration type**: OIDC - OAuth 2.0.
   - **Redirect URIs**:

     - `http://<your-service-host>:8250/oidc/callback`
     - `http://<your-service-host>:8200/ui/vault/auth/oidc/oidc/callback`

   [Image: Custom OIDC application form with the redirect URIs]

4. Click **Add service**. The service appears in the corresponding section.

:::caution[Save the application data]
Save the fields that Ironchip returns when you create the service (the client ID and client secret). They only appear this once.
:::

## Configure Vault

### Enable the OIDC auth method

1. In the **Access** tab, create a new **oidc** authentication method.

   [Image: Vault Access tab with the option to create an auth method]

2. Enter the path `oidc`, enable **List method when unauthenticated**, and click the button to enable the method.

   [Image: Enabling the oidc method with the path oidc]

3. In the OIDC configuration, fill in these parameters:

   - **OIDC discovery url**: `https://idp.ironchip.com/oidc`
   - **Default role**: `demo`
   - **OIDC response mode**: `query`

   [Image: Discovery url, default role and response mode parameters]

4. Fill in these two fields with the data Ironchip returned when you created the application:

   - **OIDC client ID**: the client ID.
   - **OIDC client secret**: the client secret.

   [Image: OIDC client ID and OIDC client secret fields]

5. Click save. The new oidc authentication method is created.

### Create the policies

In the policies tab, if no `default` policy is defined, create it with the following content. It is the policy for ordinary users, who will not have access to the policies tab.

```hcl title="default policy"
# Allow tokens to look up their own properties
path "auth/token/lookup-self" {
    capabilities = ["read"]
}

# Allow tokens to renew themselves
path "auth/token/renew-self" {
    capabilities = ["update"]
}

# Allow tokens to revoke themselves
path "auth/token/revoke-self" {
    capabilities = ["update"]
}

# Allow a token to look up its own capabilities on a path
path "sys/capabilities-self" {
    capabilities = ["update"]
}

# Allow a token to look up its own entity by id or name
path "identity/entity/id/{{identity.entity.id}}" {
  capabilities = ["read"]
}
path "identity/entity/name/{{identity.entity.name}}" {
  capabilities = ["read"]
}

# Allow a token to look up its resultant ACL from all policies. This is useful
# for UIs. It is an internal path because the format may change at any time
# based on how the internal ACL features and capabilities change.
path "sys/internal/ui/resultant-acl" {
    capabilities = ["read"]
}

# Allow a token to renew a lease via lease_id in the request body; old path for
# old clients, new path for newer
path "sys/renew" {
    capabilities = ["update"]
}
path "sys/leases/renew" {
    capabilities = ["update"]
}

# Allow looking up lease properties. This requires knowing the lease ID ahead
# of time and does not divulge any sensitive information.
path "sys/leases/lookup" {
    capabilities = ["update"]
}

# Allow a token to manage its own cubbyhole
path "cubbyhole/*" {
    capabilities = ["create", "read", "update", "delete", "list"]
}

# Allow a token to wrap arbitrary values in a response-wrapping token
path "sys/wrapping/wrap" {
    capabilities = ["update"]
}

# Allow a token to look up the creation time and TTL of a given
# response-wrapping token
path "sys/wrapping/lookup" {
    capabilities = ["update"]
}

# Allow a token to unwrap a response-wrapping token. This is a convenience to
# avoid client token swapping since this is also part of the response wrapping
# policy.
path "sys/wrapping/unwrap" {
    capabilities = ["update"]
}

# Allow general purpose tools
path "sys/tools/hash" {
    capabilities = ["update"]
}
path "sys/tools/hash/*" {
    capabilities = ["update"]
}

# Allow checking the status of a Control Group request if the user has the
# accessor
path "sys/control-group/request" {
    capabilities = ["update"]
}

# Allow a token to make requests to the Authorization Endpoint for OIDC providers.
path "identity/oidc/provider/+/authorize" {
	capabilities = ["read", "update"]
}
```

[Image: Vault policies tab with the default policy]

If you want to configure an administrator user, create an `admin` policy with this content:

```hcl title="admin policy"
path "sys/health"
{
  capabilities = ["read", "sudo"]
}

path "sys/policies/acl"
{
  capabilities = ["list"]
}

path "sys/policies/acl/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

path "auth/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

path "sys/auth/*"
{
  capabilities = ["create", "update", "delete", "sudo"]
}

path "sys/auth"
{
  capabilities = ["read"]
}

path "secret/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

path "sys/mounts/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

path "sys/mounts"
{
  capabilities = ["read"]
}
```

### Create the roles

Once the policies are defined, create a role for each one. You do it from the terminal enabled in the Vault application. Replace `CLIENT_ID` with the client ID of the Ironchip application.

For the common user, create the `demo` role:

```bash
vault write auth/oidc/role/demo \
        bound_audiences="CLIENT_ID" \
        allowed_redirect_uris="http://<your-service-host>:8200/ui/vault/auth/oidc/oidc/callback" \
        allowed_redirect_uris="http://<your-service-host>:8250/oidc/callback" \
        user_claim="sub" \
        policies="default" \
        verbose_oidc_logging="true"
```

For the administrator, create the `admin` role:

```bash
vault write auth/oidc/role/admin \
        bound_audiences="CLIENT_ID" \
        allowed_redirect_uris="http://<your-service-host>:8200/ui/vault/auth/oidc/oidc/callback" \
        allowed_redirect_uris="http://<your-service-host>:8250/oidc/callback" \
        user_claim="sub" \
        policies="admin" \
        verbose_oidc_logging="true"
```

:::note
The role set as default in the OIDC configuration does not need to be entered when you sign in. To sign in as administrator, you do need to enter the `admin` role.
:::

## Verify the integration

Before you test, make sure the user is added to the Ironchip application.

1. Open the Vault sign-in page and select the **OIDC** method.
2. For an ordinary user, leave the **Role** empty: Vault uses the default role `demo`. To sign in as administrator, enter `admin`.
3. Click **Sign in with OIDC Provider**. Vault redirects you to Ironchip.
4. Authorize the access with Ironchip. You return to Vault signed in with the policies of the role.