Kubernetes

The IBM Security Verify Access OIDC Provider (ISVAOP) image is available on IBM Cloud Container Registry.

See Software Downloads > Containers for more information.

Pre-requisites

Configuration

The configuration for the container is supplied as YAML files, template files, JavaScript files along with other potential supporting files (e.g. PEM certificate files).

๐Ÿ“˜

Note

Boilerplate YAML configuration is available for download from the Resources Github Repository.

When the container starts, it processes configuration found at '/var/isvaop/config' directory. As such, the configuration for the container will need to be present in this directory before the container is started or mounted as part of startup.

There are different ways by which the ISVAOP container can be packaged to start with the configuration information. Here are some non-exhaustive options:

  1. Pre-baking the configuration into a new image which is based on the ISVAOP image. A Dockerfile which can be used to create a pre-baked image is shown below:
##
## You can build this image by issuing the following command:
##          docker build -t acme-isvaop:1.0 $PWD
##

## The container is based on the ISVAOP container.
FROM icr.io/isva/verify-access-oidc-provider:24.06

## Copy the configuration files from the data directory
## to the docker image.
COPY data/. /var/isvaop/config/


## Some labels which will be associated with the image.
LABEL maintainer="[email protected]" \
    vendor="ACME"
  1. Using Kubernetes ConfigMaps and Secrets to hold configuration information.

Approach: Using Kubernetes resources

Pre-deployment steps

  1. Create a Kubernetes Secret for Keystores, Certificates and Keys.

    Put the following files in the same folder and use the command line to create the Secret.

    • P12 keystore and the obf file contains the P12's obfuscated password.
    • Individual keystore .zip file. Make sure the keystore zip file has the personal and signer folders at its root.
    • PEM format certificate and key files.

    Use the following command to create the Secret:

    kubectl create secret generic isvaop-keystores --from-file=./keystores
    
  2. Create a Kubernetes Secret for Server Credentials.

    Create a Kubernetes Secret yaml file with the server credentials as shown in the following example.

    kind: Secret
    apiVersion: v1
    metadata:
      name: isvaop-server
    stringData:
      db_hostname: ...
      db_hostport: ...
      db_username: ...
      db_password: ...
      db_db_name: ...
       ...
    type: Opaque
    

    Use the following command to create the Secret:

    kuberctl apply -f server_secret.yml
    
  3. Create a Kubernetes Secret for obfuscation and encryption keys.
    Create a Kubernetes Secret yaml file with the server credentials as shown in the following example.

    kind: Secret
    apiVersion: v1
    metadata:
      name: isvaop-obf
    stringData:
      obf_key: "ENC:<encrypted_obf_key>"
      enc_key: |
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----
    type: Opaque
    

    Use the following command to create the Secret:

    oc apply -f obf_secret.yml
    
  4. If necessary, create more Kubernetes Secrets.

  5. Create a Kubernetes ConfigMap for static clients.

    Put the client yaml files in the same folder, and use the following command to create the ConfigMap:

     kubectl create configmap isvaop-clients --from-file=./clients
    
  6. Create a Kubernetes ConfigMap for access policies.

    Put the access policy files in the same folder, and use the following command to create the ConfigMap:

    kubectl create configmap isvaop-access-policies --from-file=./accesspolicy
    
  7. Create a Kubernetes ConfigMap for mapping rules.

    Put the mapping rule files in the same folder, and use the following command to create the ConfigMap:

    kubectl create configmap isvaop-mapping-rules --from-file=./mappingrule
    
  8. Create a Kubernetes ConfigMap for customized template pages.

    Compress the customized template pages. Make sure the .zip file has the language folders like C, fr, and it at its root.
    Use the following command to create the ConfigMap:

    kubectl create configmap isvaop-templates --from-file=./templates.zip
    
  9. If necessary, create more Kubernetes ConfigMaps.

  10. Create the main Kubernetes ConfigMap with top-level configuration keys.

    • For more information about top-level keys and an example, see Configuration.
    • For more information about YAML configuration details, see YAML Config Guide.

    Create yaml configuration files with top-level keys, and use configmap: or secret: annotation refer to configurations in Kubernetes ConfigMaps or Secrets.

    The configuration can in the same file or spread across multiple files.

    ๐Ÿ“˜

    Note

    The configuration file extensions must be .yml or .yaml.
    Set top-level key version to 24.06 to enable full yaml configuration.

    The following code is a configuration file example with all top-level keys.

    version: 24.06
    server:
      ssl:
        key: 'secret:isvaop-keystores/httpserverkey.pem'
        certificate: 'secret:isvaop-keystores/httpservercert.pem'
      pages:
        type: zip
        content: 'configmap:isvaop-templates/templates.zip'
    logging:
      level: debug
    secrets:
      obf_key: 'secret:isvaop-obf/obf_key'
      enc_key: 'secret:isvaop-obf/private.pem'
    template_macros:
      user_macros:
        - name
        - family_name
        - given_name
        - display_name
      request_macros:
        - authorization_details
        - claims
        - user_code
        - state
    ssl:
      certificate:
        - ks:rt_profile_keys
      disable_hostname_verification: true
    definition:
      id: 1
      name: OIDC Definition
      grant_types:
        - authorization_code
        - implicit
        - password
        - client_credentials
        - refresh_token
        - 'urn:openid:params:grant-type:ciba'
        - urn:ietf:params:oauth:grant-type:jwt-bearer
      access_policy_id: default_policy
      pre_mappingrule_id: pretoken
      post_mappingrule_id: posttoken
      base_url: 'https://auth.isvaop.com:445'
      mtls_base_url: 'https://auth.isvaop.com:445'
      mtls_certificate_header_name: X-Client-Certificate
      features:
        enable_fault_tolerance: false
        enable_dynamic_registration: true
        consent_prompt: NEVER_PROMPT
        fapi_compliant: false
        enforce_par: false
      token_settings:
        issuer: 'https://www.ibm.com'
        signing_alg: RS256
        signing_keystore: rt_profile
        signing_keylabel: rsa256
        authorization_code_lifetime: 300
        access_token_lifetime: 7200
        id_token_lifetime: 3600
        refresh_token_lifetime: 64800
      request_object:
        lifetime: 3600
        require_expiry: true
        only_request_object_params: false
        enforce_single_usage: false
      backchannel_settings:
        default_expiry: 900
        maximum_expiry: 1800
        polling_interval: 5
        notifyuser_mappingrule_id: notifyuser
        checkstatus_mappingrule_id: checkstatus
      attribute_map:
        name: name
        preferred_username: preferred_username
        email: email
      metadata:
        claims_supported:
          - iss
          - name
          - displayName
    janitor:
      batch_size: 1000
      max_duration: 0
      check_frequency: 10
    jwks:
      signing_keystore: rt_profile
      encryption_keystore: rt_profile_keys
    authentication:
      endpoint: >-
        https://auth.isvaop.com:445/oauth2/auth
      callback_param_name: Target
    javascript:
      timeout: 0
      max_load: 16
      max_idle_time: 600
      max_ctx_in_isolate: 60
      cleanup_frequency: 300
      use_pool: false
    dynamic_registration:
      recipe: Default
      mappingrule_id: dcr
      software_statement_validation:
        jwks_uri: >-
          https://isvaop.ibmcloudsecurity.com/oidc/endpoint/default/jwks
        signing_algs:
          - PS256
          - ES256
      registration_endpoint_authentication:
        require_mtls: false
        require_bearer_token: false
        require_software_statement: false
        allow_custom_client_creds: true
      management_endpoint_authentication:
        require_mtls: false
        require_bearer_token: true
        require_software_statement: false
      registration_access_token:
        generate: true
        lifetime: 86400
        scopes:
          - 'cdr:registration'
    runtime_db: db2srv
    session_cache:
      type: redis
      cfg: redis-standalone
    server_connections:
      - name: db2srv
        type: db2
        database_name: 'secret:isvaop-server/db_db_name'
        hosts:
          - hostname: 'secret:isvaop-server/db_hostname'
            hostport: 'secret:isvaop-server/db_hostport'
        credential:
          username: 'secret:isvaop-server/db_username' 
          password: 'secret:isvaop-server/db_password'
        ssl:
          certificate:
            - ks:db2client
          disable_hostname_verification: true
      - name: redis-standalone
        type: redis
        deployment:
          model: standalone
        hosts:
          - hostname: 'secret:isvaop-server/redis_hostname'
            hostport: 'secret:isvaop-server/redis_hostport'
        credential:
          username: 'secret:isvaop-server/redis_username' 
          password: 'secret:isvaop-server/redis_password'
        ssl:
          certificate:
            - ks:rt_profile
          disable_hostname_verification: true
      - name: ldap_staging
        type: ldap
        hosts:
          - hostname: 'secret:isvaop-server/ldap_hostname'
            hostport: 'secret:isvaop-server/ldap_hostport'
            credential:
              bind_dn: 'secret:isvaop-server/ldap_bind_dn'
              bind_password: 'secret:isvaop-server/ldap_bind_pwd'
        ssl:
          certificate:
            - ks:rt_profile
          disable_hostname_verification: true
    attribute_sources:
      - id: 1
        name: name
        type: ldap
        value: displayName
        scope: subtree
        filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
        selector: cn,displayName,mail
        srv_conn: ldap_staging
        baseDN: dc=ibm,dc=com
      - id: 2
        name: preferred_username
        type: ldap
        value: cn
        scope: subtree
        filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
        selector: cn,displayName,mail
        srv_conn: ldap_staging
        baseDN: dc=ibm,dc=com
      - id: 3
        name: email
        type: ldap
        value: mail
        scope: subtree
        filter: (objectclass=*)
        selector: cn,displayName,mail
        srv_conn: ldap_staging
        baseDN: dc=ibm,dc=com
    ldapcfg:
      - name: ldap_staging_cfg_01
        scope: subtree
        user_object_classes: top,Person,organizationalPerson,inetOrgPerson
        filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
        selector: objectClass,cn,sn,givenName,userPassword
        srv_conn: ldap_staging
        attribute: uid
        baseDN: dc=ibm,dc=com
    rules:
      access_policy:
        - name: default_policy
          content: 'configmap:isvaop-access-policies/default_policy.js'
      mapping:
        - name: pretoken
          content: 'configmap:isvaop-mapping-rules/pretoken.js'
        - name: posttoken
          content: 'configmap:isvaop-mapping-rules/posttoken.js'
        - name : dcr
          content: 'configmap:isvaop-mapping-rules/dcr.js'
        - name: ropc
          content: 'configmap:isvaop-mapping-rules/ropc.js'
        - name : notifyuser
          content: 'configmap:isvaop-mapping-rules/notifyuser.js'
        - name: checkstatus
          content: 'configmap:isvaop-mapping-rules/checkstatus.js'
    clients:
      - "configmap:isvaop-clients/client01.yml"
      - "configmap:isvaop-clients/client02.yml"
      - "configmap:isvaop-clients/client03.yml"
    keystore:
      - name: db2client
        type: p12
        content: "secret:isvaop-keystores/db2client.p12"
        password: "secret:isvaop-keystores/db2client.obf"
      - name: rt_profile
        type: zip
        content: "secret:isvaop-keystores/rt_profile.zip"
      - name: rt_profile_keys
        type: pem
        certificate:
          - label: cert01
            content: "secret:isvaop-keystores/rt_profile_keys_signer_cert01.pem"
          - label: cert02
            content: "secret:isvaop-keystores/rt_profile_keys_signer_cert02.pem"
        key:
          - label: key01
            content: "secret:isvaop-keystores/rt_profile_keys_personal_key01.pem"
          - label: key02
            content: "secret:isvaop-keystores/rt_profile_keys_personal_key02.pem"
    

    Put the configuration files with top-level keys in the same folder, and use the following command to create the ConfigMap:

    kubectl create configmap isvaop-config --from-file=./config
    
  11. Create a service account.

## Create a serviceaccount called isvaop.
kubectl create serviceaccount isvaop
  1. Assign ConfigMap and Secret read permission to the service account.
    Create a role with ConfigMap and Secret read permission using the following command:
kubectl create role view-configmap-secret --verb=get,list,watch --resource=secrets,configmaps

Create a Rolebinding to assign the role to the service account by using the following command.

๐Ÿ“˜

Note

The RoleBinding applies to the specific kubernetes namespace.

Replace <namespace> with the actual namespace.

The default kubernetes namespace is default.

kubectl create rolebinding --role=view-configmap-secret <namespace>-isvaop-view-configmap-secret --serviceaccount=<namespace>:isvaop

Deployment

In order to deploy a running IBM Security Verify Access OIDC Provider container in a Kubernetes environment a deployment descriptor must first be created. The following deployment YAML file (isvaop-deployment.yaml) is a sample, which references the configmaps and secret created in the previous section.

Use the following isvaop-deployment.yml to deploy the service.

## 
## A demo deployment description for the isvaop container. This deployment
## descriptor has dependencies on the file-based configuration.
##
apiVersion: apps/v1
kind: Deployment
metadata:
  name: isvaop
  labels:
    app: isvaop
spec:
  selector:
    matchLabels:
      app: isvaop
  replicas: 1
  template: 
    metadata:
      labels:
        app: isvaop
      annotations:
        version: "2.0"
        productName: "IBM Security Verify Access Virtual Edition Federation Module AOS"
        productId: "13ce5584032a42eab5704711369a11a4"
        productMetric: "PROCESSOR_VALUE_UNIT"
        productChargedContainers: "All"
    spec:
      # The name of the service account which has the required
      # capabilities enabled for the ISVAOP container.
      serviceAccountName: isvaop
      
      # Use volume to store the configuration data.
      volumes:
         - name: isvaop-config
           configMap:
              name: isvaop-config
      containers:
        - name: isvaop
          # The fully qualified name of the ISVAOP image.
          image: icr.io/isva/verify-access-oidc-provider:24.06
          # Mount our volumes to the expected configuration directory
          volumeMounts:
            - name: isvaop-config
              mountPath: /var/isvaop/config
          # The liveness and readiness probes are used by Kubernetes 
          # to obtain the health of the container.
          readinessProbe:
            httpGet:
              path: /healthcheck/ready
              port: 8436
              scheme: HTTPS
            initialDelaySeconds: 30
            timeoutSeconds: 30
            periodSeconds: 30
            successThreshold: 1
            failureThreshold: 2
          livenessProbe:
            httpGet:
              path: /healthcheck/alive
              port: 8436
              scheme: HTTPS
            initialDelaySeconds: 30
            timeoutSeconds: 30
            periodSeconds: 30
            successThreshold: 1
            failureThreshold: 10

The Kubernetes pod can then be created using the following command:

[demouser@demovm ~]$ kubectl apply -f isvaop-deployment.yml

You can monitor the bootstrapping of the pod as below:

[demouser@demovm ~]$ kubectl logs -f `kubectl get -o json pods -l app=isvaop | jq -r .items[0].metadata.name`

Service

The isvaop container will expose a single port for each protocol which is enabled for the server. For the HTTPS protocol the 8436 port is exposed. To make this port available from outside of the Kubernetes cluster a new service must be created. The following YAML file (isvaop-service.yaml) contains an example service definition:

## 
## The service description of the isvaop service.  
##

apiVersion: v1
kind: Service

metadata:
  name: isvaop

spec:
  ports:
    - port: 8436
      name: isvaop
      protocol: TCP
      nodePort: 30443

  selector:
    app: isvaop

  type: NodePort

The service definition can then be created using the following command:

[demouser@demovm ~]$ kubectl apply -f isvaop-service.yaml

Updating the Configmap

  • To update the isvaop-config configmap, modify the configuration directory, then execute the following command:

    [demouser@demovm ~]$ kubectl create configmap isvaop-config --from-file=./config -o yaml --dry-run | kubectl apply -f -
    
  • Delete the existing pod.

    [demouser@demovm ~]$ kubectl delete pod <pod_name>
    

IBM Cloud

The IBM cloud container service provides advanced capabilities for building cloud-native apps, adding DevOps to existing apps, and relieving the pain around security, scale, and infrastructure management. Further information can be obtained from the IBM Cloud Web site: https://www.ibm.com/cloud/container-service

To set the context for the kubectl utility use the IBM Cloud CLI to obtain the kubectl configuration file:

## Log into IBM Cloud.
ibmcloud login -sso

## Obtain the list of available cluster.
ibmcloud ks clusters

## Show the details of the cluster.
ibmcloud ks workers <cluster-name>

## Create the kubectl configuration file.
ibmcloud ks cluster config <cluster-name>

## Set the kubectl configuration file.
export KUBECONFIG=<deployment-yaml>