Enable Authenticators for Applications

The following topic describes how to enable authenticators for application deployment.

Policy

Define and upload the following policies:

At least one user needs write permission to load policy and variables into DAP. This is standard DAP policy that creates an administrative group of users for DAP.

Use the following policy as a template to assign permissions:

  
# Filename: policy_for_human_users.yml
# initializes users
# ted - kubernetes admin
# bob - devops admin
# alice - db admin
# carol - developer

- !group kube_admin
- !group devops
- !group ops
- !group db_admin

# kube_admin and devops groups are members of the ops admin group
- !grant
  role: !group ops
  members:
  - !group kube_admin
  - !group devops

- !user ted
- !grant
  role: !group kube_admin
  member: !user ted

- !user bob
- !grant
  role: !group devops
  member: !user bob

- !user alice
- !grant
  role: !group db_admin
  member: !user alice

- !user carol
- !grant
  role: !group devops
  member: !user carol

The identities that will be used to authenticate and retrieve secrets from DAP will also need to be defined in policy and added to the layer that was granted access to the Kubernetes authenticator webservice in the previous policy.

For details about the different identities that can be used in this policy, see Application Identity in OpenShift/Kubernetes

Variable

Description
AUTHENTICATOR_ID

The Conjur authenticator that your Kubernetes or OpenShift applications are using.

TEST_APP_NAMESPACE_NAME

The namespace you are deploying your applications to.

APPLICATION_SERVICE_ACCOUNT

The service account that the application is using.

 

  
---
# Filename: policy_for_authenticator_identities.yml
# This policy defines a layer of allowlisted identities permitted to authenticate to the authn-k8s endpoint.
- !policy
  id: conjur/authn-k8s/<AUTHENTICATOR_ID>/apps
  owner: !group devops
  annotations:
    description: Identities permitted to authenticate
  body:
  - !layer
    annotations:
      description: Layer of authenticator identities permitted to call authn svc
  - &hosts
    - !host
      id: namespace-based-app
      annotations:
        authn-k8s/namespace: <TEST_APP_NAMESPACE_NAME>
        authn-k8s/authentication-container-name: <AUTHENTICATOR_CLIENT_CONTAINER_NAME>
        openshift: "true"
    - !host
      id: service-account-based-app
      annotations:
        authn-k8s/namespace: <TEST_APP_NAMESPACE_NAME>
        authn-k8s/service-account: <APPLICATION_SERVICE_ACCOUNT>
        authn-k8s/authentication-container-name: <AUTHENTICATOR_CLIENT_CONTAINER_NAME>
        openshift: "true"
  - !grant
    role: !layer
    members: *hosts

DAP uses policy to allowlist the applications that have access to the Kubernetes authenticator and store the values necessary to create client certificates for mutual TLS. The authenticator service policy should include:

Resource

Description
Webservice A resources to represent the authenticator itself
Variable A resource to hold the CA certificate and key for creating client certificates
Permit statement Allowlists a layer of application identities

Use the following policy as a template to allowlist applications.

Replace the following variables with values:

Variable

Description
AUTHENTICATOR_ID The Conjur authenticator that your K8s / OC applications are using.
APPLICATION_NAMESPACE The namespace you are deploying your applications to.

 

  
---
# Filename: policy_for_k8s_authenticator_service.yml
# This policy defines an authn-k8s endpoint, CA creds and a layer for allowlisted identities permitted to authenticate to it
- !policy
  id: conjur/authn-k8s/<AUTHENTICATOR_ID>
  owner: !group devops
  annotations:
    description: Namespace defs for the Conjur cluster in dev
  body:
  - !webservice
    annotations:
      description: authn service for cluster

# CA cert and key for creating client certificates
  - !policy
    id: ca
    body:
    - !variable
      id: cert
      annotations:
        description: CA cert for Kubernetes Pods.
    - !variable
      id: key
      annotations:
        description: CA key for Kubernetes Pods.

  # permit a layer of allowlisted authn ids to call authn service
  - !permit
    resource: !webservice
    privilege: [ read, authenticate ]
    role: !layer /conjur/authn-k8s/<AUTHENTICATOR_ID>/apps

  1. Save policy as .yml files in a location accessible to the DAP Master.

  2. Log into DAP.

  3. Load each policy file:

      
    $ conjur policy load root <policy_for_human_users.yml>
    $ conjur policy load root <policy_for_authenticator_identities.yml>
    $ conjur policy load root <policy_for_k8s_authenticator_service.yml>

Initialize the CA

The DAP uses policy to allowlist the applications that have access to the Kubernetes authenticator and store the values necessary to create client certificates for mutual TLS. The authenticator service policy should include: declares variables to hold a CA certificate and key. After loading the policy, run the following commands to initialize those resources.

To initialize the CA, run the following script:

  
#!/bin/bash
set -e
AUTHENTICATOR_ID='<AUTHENTICATOR_ID>'
CONJUR_ACCOUNT='<CONJUR_ACCOUNT>'

# Generate OpenSSL private key
openssl genrsa -out ca.key 2048

CONFIG="
[ req ]
distinguished_name = dn
x509_extensions = v3_ca
[ dn ]
[ v3_ca ]
basicConstraints = critical,CA:TRUE
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always,issuer:always
"

# Generate root CA certificate
openssl req -x509 -new -nodes -key ca.key -sha1 -days 3650 -set_serial 0x0 -out ca.cert \
  -subj "/CN=conjur.authn-k8s.$AUTHENTICATOR_ID/OU=Conjur Kubernetes CA/O=$CONJUR_ACCOUNT" \
  -config <(echo "$CONFIG")

# Verify cert
openssl x509 -in ca.cert -text -noout

# Load variable values
conjur variable values add conjur/authn-k8s/$AUTHENTICATOR_ID/ca/key "$(cat ca.key)"
conjur variable values add conjur/authn-k8s/$AUTHENTICATOR_ID/ca/cert "$(cat ca.cert)"

These commands create a private key and root certificate and store contents of those files in the variables conjur/authn-k8s/<AUTHENTICATOR_ID>/ca/key and conjur/authn-k8s/<AUTHENTICATOR_ID>/ca/cert.

Login or auth calls to the webservice will fail if these resources are not properly defined in policy and initialized.

Configure Conjur authenticators

 

The deployment scripts for DAP already performed this step using the value you set in the SERVICE_ID environment variable. You need to be aware of this step to add additional application clusters or additional authenticator types.

The CONJUR_AUTHENTICATORS environment variable in the DAP deployment YAML file defines the authentication types used to authenticate with the DAP cluster.

 

This variable is set on followers.

To enable Kubernetes authentication, use:

  
CONJUR_AUTHENTICATORS=authn-k8s/<AUTHENTICATOR_ID>

where AUTHENTICATOR_ID is the id assigned to the authn-k8s webservice in DAP policy. It is important that the AUTHENTICATOR_ID used here match the webservice id declared in the Kubernetes policy.

For example, in this snippet from the Conjur webservice policy, a policy branch named conjur declares the authn-k8s service with the authenticator_id of prod:

  
- !policy
  id: conjur/authn-k8s/prod

The authentication value is:

  
CONJUR_AUTHENTICATORS=authn-k8s/prod

One authn-k8s service can serve multiple application authenticator ids. Additional DAP policy for hosts and applications will control which namespaces get access to DAP and which applications get access to specific secrets. There should be a separate authn-k8s policy (and corresponding authenticator id) for each or Kubernetes cluster.

CONJUR_AUTHENTICATORS can include more than one authenticator and more than one authentication type as a comma-separated list. For example, the following shows two authn-k8s services and another unrelated authenticator:

  
CONJUR_AUTHENTICATORS=authn-k8s/prod,authn-k8s/dev,authn-iam/prod

To disable an authenticator, remove it from the list.