HashiCorp Vault

This guide configures HashiCorp Vault so that users sign in with Ironchip through 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

   

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

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.

   

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

   

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

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

   

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.

   

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.

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"]
}

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

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:

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:

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.