Identity and Access Management (IAM) Deployment Guide⚓︎

The EOEPCA Identity and Access Management (IAM) Building Block provides secure authentication and authorisation for all platform services. It enables you to manage users, roles, policies, and integrate with external identity providers.

Key Features:

Central user management via Keycloak
Fine-grained policy decisions using OPA & OPAL
Integration with external IdPs (e.g., GitHub)
Enforcement of policies at the APISIX ingress layer

Prerequisites⚓︎

Component	Requirement	Documentation Link
Kubernetes	Cluster (tested on v1.28)	Installation Guide
Helm	Version 3.5 or newer	Installation Guide
kubectl	Configured for cluster access	Installation Guide
Ingress Controller	Properly installed	Installation Guide
TLS Certificates	Managed via `cert-manager` or manually	TLS Certificate Management Guide

Clone the Deployment Guide Repository:

git clone https://github.com/EOEPCA/deployment-guide
cd deployment-guide/scripts/iam

Check Prerequisites:

bash check-prerequisites.sh

If any checks fail, address them before proceeding.

Overview of Deployment Steps⚓︎

Configure the IAM Environment: Provide ingress host, storage classes, etc.
Install APISIX Ingress (if not done already): Ensure APISIX is ready.
Deploy Keycloak: Set up the central identity provider.
Create the eoepca Realm and Basic Users: Keep master for admin tasks only.
(Optional) Integrate External IdPs: Add GitHub or other providers.
Deploy OPA & OPAL: For advanced policy decisions.
Set up Policies & Permissions: Restrict access to services as needed.
Test & Validate: Confirm that IAM is working as intended.

For production, use proper TLS, stable storage, and consider external identity providers. For development, simpler self-signed certs and test credentials may suffice.

Step-by-Step Deployment⚓︎

1. Configure the IAM Deployment⚓︎

bash configure-iam.sh

Configuration Parameters

During the script execution, you will be prompted to provide:

INGRESS_HOST: Base domain for ingress hosts.
- Example: example.com
STORAGE_CLASS: Kubernetes storage class for persistent volumes.
- Example: standard
CLUSTER_ISSUER: Issuer for TLS certificates
- Example: letsencrypt-http01-apisix

The script will also generate secure passwords for:

KEYCLOAK_ADMIN_PASSWORD: Password for the Keycloak admin account.
KEYCLOAK_POSTGRES_PASSWORD: Password for the Keycloak PostgreSQL database.
OPA_CLIENT_SECRET: Secret for the opa (Open Policy Agent) client in Keycloak

These credentials will be stored in a state file at ~/.eoepca/state.

2. Ensure APISIX is Installed⚓︎

If you haven’t installed APISIX yet, see the instructions in section APISIX Ingress Controller.

3. Apply Secrets⚓︎

bash apply-secrets.sh

This creates Kubernetes secrets from the credentials generated earlier.

4. Deploy Keycloak⚓︎

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update bitnami
helm upgrade -i keycloak bitnami/keycloak \
  --values keycloak/generated-values.yaml \
  --version 21.4.4 \
  --namespace iam \
  --create-namespace

Apply Keycloak ingress:

kubectl -n iam apply -f keycloak/generated-ingress.yaml

Custom Keycloak Image

If you have a custom Keycloak image that includes the Keycloak-OPA adapter plugin, you can specify it in the keycloak/values-template.yaml file by uncommenting and modifying the image section:

image:
  registry: your.registry
  repository: eoepca/keycloak-with-opa-plugin
  tag: your-tag
  pullPolicy: Always

Replace your.registry, eoepca/keycloak-with-opa-plugin, and your-tag with your registry, repository, and tag.

5. Create the `eoepca` Realm and a Test User⚓︎

Instead of using master, create a dedicated eoepca realm - using the Keycloak REST API.
For convenience we also create an eoepcauser (test) user to support usage examples in this guide where a user must be assumed.

Create the eoepca realm…

source ~/.eoepca/state

# Get access token for Keycloak admin user
ACCESS_TOKEN=$( \
  curl --silent --show-error \
    -X POST \
    -d "username=${KEYCLOAK_ADMIN_USER}" \
    --data-urlencode "password=${KEYCLOAK_ADMIN_PASSWORD}" \
    -d "grant_type=password" \
    -d "client_id=admin-cli" \
    "https://auth.${INGRESS_HOST}/realms/master/protocol/openid-connect/token" | jq -r '.access_token' \
)

# Create the `eoepca` realm
curl --silent --show-error \
  -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- \
  "https://auth.${INGRESS_HOST}/admin/realms" <<EOF
{
  "realm": "eoepca",
  "enabled": true
}
EOF

Create the eoepcauser user in the eoepca realm…
Set the user/password according to your needs

bash ../utils/create-user.sh

6. (Optional) Integrate External Identity Providers⚓︎

If you wish to add GitHub or another IdP, see Advanced Configuration for detailed instructions and examples.

7. Create the `opa` Client⚓︎

Use the create-client.sh script in the /scripts/utils/ directory. This script prompts you for basic details and automatically creates a Keycloak client in your chosen realm:

bash ../utils/create-client.sh

When prompted:

Keycloak Admin Username and Password: Enter the credentials of your Keycloak admin user
See ~/.eoepca/state
Keycloak base domain: e.g. auth.${INGRESS_HOST}
Realm: Typically eoepca.
Client ID: For OPA, you should use opa.
Client name and description: Provide any helpful text
e.g. name=OPA Client and description=Open Policy Agent
Client secret: Enter the OPA Client Secret that was generated during the configuration script (check ~/.eoepca/state).
Subdomain: Use opa for Open Policy Agent.

After it completes, you should see a JSON snippet confirming the newly created client.

8. Deploy OPA & OPAL⚓︎

helm repo add opal https://permitio.github.io/opal-helm-chart
helm repo update opal
helm upgrade -i opa opal/opal \
  --values opa/values.yaml \
  --version 0.0.28 \
  --namespace iam \
  --create-namespace

Apply OPA ingress:

kubectl -n iam apply -f opa/generated-ingress.yaml

9. Testing & Validation⚓︎

bash validation.sh

Check all pods:

kubectl get pods -n iam

Ensure all components (Keycloak, OPA, etc.) are running and accessible.

Further Configuration & Usage⚓︎

For detailed steps on:

Creating and managing Keycloak clients
Integrating external IdPs
Applying advanced resource protection (groups, roles, OPA policies)
Using the device flow to obtain tokens in a script or notebook

Refer to the Client Administration and Advanced Configuration.

After deployment, the IAM exposes several endpoints for authentication, authorization, and administration. Replace ${INGRESS_HOST} with your actual ingress host domain in the URLs below.

Keycloak⚓︎

Keycloak Home Page:

URL: https://auth.${INGRESS_HOST}/

OpenID Connect Discovery Endpoint:

URL: https://auth.${INGRESS_HOST}/realms/${REALM}/.well-known/openid-configuration

OAuth 2.0 Authorization Endpoint:

URL: https://auth.${INGRESS_HOST}/realms/${REALM}/protocol/openid-connect/auth

OAuth 2.0 Token Endpoint:

URL: https://auth.${INGRESS_HOST}/realms/${REALM}/protocol/openid-connect/token

Administration Console:

URL: https://auth.${INGRESS_HOST}/admin/

Accessing the Administration Console:

Retrieve Admin Credentials

The admin credentials are stored in the state file. Retrieve them using:

source ~/.eoepca/state
echo "Username: $KEYCLOAK_ADMIN_USER"
echo "Password: $KEYCLOAK_ADMIN_PASSWORD"

Login to the Console

Navigate to the Administration Console URL and log in with the retrieved credentials.

Open Policy Agent (OPA)⚓︎

OPA Endpoint:

URL: https://opa.${INGRESS_HOST}/

You can test policy evaluations by sending requests to OPA’s REST API. For example:

source ~/.eoepca/state
# Authenticate as test user `eoepcauser`
ACCESS_TOKEN=$( \
  curl --silent --show-error \
    -X POST \
    -d "username=${KEYCLOAK_TEST_USER=}" \
    --data-urlencode "password=${KEYCLOAK_TEST_PASSWORD}" \
    -d "grant_type=password" \
    -d "client_id=admin-cli" \
    "https://auth.${INGRESS_HOST}/realms/${REALM}/protocol/openid-connect/token" | jq -r '.access_token' \
)
# Interogate OPA using the access token for `eoepcauser`
curl -X POST "https://opa.${INGRESS_HOST}/v1/data/example/allow" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"input": {"user": "alice"}}'

Validating Kubernetes Resources⚓︎

Ensure that all Kubernetes resources are running correctly.

kubectl get pods -n iam

Expected Output:

All pods should be in the Running state.
No pods should be in CrashLoopBackOff or Error states.

Cleanup⚓︎

To remove IAM components:

kubectl -n iam delete -f keycloak/generated-ingress.yaml
bash delete-secrets.sh
helm -n iam uninstall keycloak

kubectl -n iam delete -f opa/generated-ingress.yaml
helm -n iam uninstall opa

If you created custom clients or realms, remove them using the scripts in scripts/ or the instructions in the appendices.