Identity Management Framework Deployment

Identity Management (IdM) Framework can be deployed as:

• On-premise solution: Identity Management Framework is a containerized solution that can be deployed over an on-premise environment. The solution can only be accessed within an organizational network.

• Cloud solution: Identity Management Framework is deployed as a containerized solution on cloud providers. It is compatible for deployment over the following platforms:

• Google Cloud Platform - Google Kubernetes Engine (GCP GKE)
• Amazon Web Services (AWS) Elastic Beanstalk

Identity Management Framework as an On-premise Solution

This section contains steps to deploy Identity Management Framework as an On-premise solution.

System Requirements

Ensure to meet the following system requirements.

Hardware	Minimal	Typical up to 5,000 users	Typical up to 50,000 users	Typical up to 100,000 users
CPU	1 core	4 cores	8 cores	16 cores
RAM	4GB	8GB	16GB	16GB
Disk space	2GB	10GB	20GB	40GB
Disk I/O	Negligible	Negligible	Negligible	Negligible

Prerequisites

Before you start the deployment process, you will need to fulfill the following prerequisites:

• Install Docker on your Ubuntu machine using these instructions.
• Ensure that ports 443 and 80 (default or non-default) are open on the perimeter firewall to allow the HTTPS external traffic to and from the server.
• Install Docker Compose using these instructions.

Installing IdM Framework

1. Click here to download the ZIP package containing containing the deployment files.

2. Run the following command to unzip the package:
   unzip <package_name>.zip

3. Run the following command to change the directory to the unzipped folder:
   cd <package_name>

4. Run the following command to go to the directory containing configuration files for docker deployment:

   cd deployments/docker/single-node-instance/

5. Run the following command to go to the nginx directory:

   cd configs-and-secrets/nginx/

6. In the nginx directory, place your SSL certificate and the corresponding private key file, which will be used to run the solution over HTTPS.

7. Open the default.conf file that is present in the nginx directory. Replace <Certificate.crt> and <private.key> with the names of certificate file and private key file that you just placed in the nginx directory.

8. Run the following command to go to the IdM_Framework directory:

   cd ../IdM_Framework/

9. Open the database_password.txt present in the IdM_Framework directory and change the default password for the DB initialization.

   We recommend you to set a strong password for the DB initialization.

10. Go to the single-node-instance directory that contains the docker-compose.yml file.

11. Open the docker-compose.yml file and replace <Certificate.crt> and <private.key> with the names of the private key file and certificate file, same as you did in step 7 above.

12. Save the docker-compose.yml file.

13. Run the following command to deploy the container using the docker-compose.yml file:
    docker compose up -d

    The docker compose version defined in the docker-compose.yml file is 3.3. If your docker engine is not compatible with this version, you can check the compatibility matrix here and change the version accordingly.

14. Run the following command to check the containers’ health and ensure that the IdM Framework container’s STATUS is healthy:
    docker ps -a

    

15. Run the following command to examine the container logs:
    docker logs -f <container ID>

16. Custom schemas and certificates required for Azure MS Graph API are included in the package. To add custom certificates to the IdM Framework keystore, perform the following steps:

    1. Run the following command to enter in the container, which has IdM Framework instance running on it:

       docker exec -it <container ID> bash

    2. Run the ./import_cert.sh script to add the required certificates into the IdM Framework keystore. If you get the permission denied error, assign appropriate permissions to the script and run it again.

    3. Ensure that the Schema-Extension.xsd file is present in the /opt/midpoint/var/schema/ directory of the IdM Framework container. If not, click here to download the file, place it in the /schema directory, and restart the IdM Framework container.

17. If you want to add other certificates as per your requirement, perform the following steps:

    1. Run the following command to enter in the container, which has IdM Framework instance running on it:

       docker exec -it <container ID> bash

    2. Place the required certificates in the var directory of IdM Framework. Run the following command to go to the var directory:

       cd /opt/midpoint/var

    3. Run the following command to add the required certificates in the keystore file:

       keytool -keystore keystore.jceks -storetype jceks -import -alias <alias_name> -trustcacerts -file <path_to_certificate_file>

       For example, 

       keytool -keystore keystore.jceks -storetype jceks -import -alias ADCert -trustcacerts -file IssuingCertificate.crt

18. Now, you can access the IdM Framework portal using the below URL:

    https://<IP_ADDRESS_OF_NGINX_MACHINE>/midpoint

To access the IdM Framework solution, please follow the instructions below:
1. Locate the downloaded package and navigate to the configs-and-secrets folder.
2. In the folder, you will find a file named ReadOnly.txt. Open this file for further instructions.

Important: As an imperative security practice, it is crucial to update the default administrator's credentials of the IdM Framework.
Once logged in, you must change the password by following the steps given below:
1. After logging in, locate the left pane of the interface.
2. In the left pane, find and select the Credentials tab.
3. Within the Credentials tab, you should be able to update the password.

Appendix

Restarting a Docker container

If you want to restart the container, perform the following steps:

1. Run the following command to list all the running containers:

   docker ps -a

2. Copy the container ID of the container you want to restart.

3. Run the following command to restart the container:

   docker restart <container ID>

Copying Files to and from the container

• To copy a file to a docker container, run the following command:

  docker cp <file residing on base machine> <container ID>:<destination directory in the container>

  For example,

  docker cp demofile.txt XXXContainerIDXXX:/demo/path/of/container/

• To copy a file from a docker container to the base machine, run the following command:

  docker cp <container ID>:<path to file residing in the container> <destination directory in base machine>

  For example,

  docker cp XXXContainerIDXXX:/demo/path/of/container/demofile.txt /opt/demo/directory

Updating the default.conf file

If you change the value of container_name keyword under the IdM_Framework_server section of the docker-compose.yml file, ensure to change the same in the default.conf file present in the Nginx container. In the default.conf file, you can change this value by performing the following steps:

1. Run the following command to enter into the nginx container:

   docker exec -it <container ID of nginx> bash

2. Run the following command to go to the conf.d directory:

   cd /etc/nginx/conf.d/

3. Open the default.conf file and under the location /midpoint path, replace the exisiting hostname of the proxy_pass URL with updated name of the container.

   

   For example, if you change the container name to Test-IdM, the proxy_pass URL must be updated to http://Test-IdM:8080;

If the machine is down due to any reason, then after restoring the machine, you may find that all the containers running on it are in the down state. To run the solution, you need to start the PostgreSQL container followed by the IdM Framework container.

For further steps to provisioning users to STA, click here.

Identity Management Framework as a Cloud Solution (GCP GKE)

Google Cloud Platform - Google Kubernetes Engine (GCP GKE) is a managed environment for deploying, managing, and scaling containerized applications on Google infrastructure. The GKE environment consists of multiple machines grouped to form a cluster.

You can deploy Identity Management Framework as a containerized solution on GCP GKE.

Prerequisites

Before you start the deployment process, you need to fulfill the following prerequisites:

• Create a GKE cluster to deploy IdM Framework over it.
• Install NGINX Ingress Controller on the GKE cluster. It is used to manage HTTPS flows.
• A valid Fully Qualified Domain Name (FQDN) for accessing IdM Framework.
• A valid SSL certificate with host entry of the IdM Framework FQDN.

Deploying Identity Management Framework over GCP GKE

1. Click here to download the ZIP package containing the deployment files.

2. Unzip the package.

3. In the unzipped folder, go to deployments/kubernetes/single-node-instance. This folder contains the idm-framework.yaml file, which will be deployed to the GKE cluster using Cloud Shell.

   The current deployment file uses the default PostgreSQL DB password specified in the password tag of the Secret Service definition present in the .yaml file. The password is Base64 encoded. It is recommended to change this password.
   To change the password, first you need to select a password of your choice and encode it into the Base64 format using an online encoding tool or Kubernetes command-line tool (kubectl).
   
   Perform the following steps to encode a password into Base64 format using kubectl and replace it in the password tag:
   1. Run the following command to generate the secret in Base64 format:
   kubectl create secret generic -n <NameSpace> idm-framework --from-literal=password=<password of your choice>
   Where,
   - <NameSpace> is the namespace in which you are running the solution.
   - <password of your choice> is the password of your choice.
   
   2. Run the following command to retrieve the Base64 value of the secret that you generated in the previous step:
   kubectl -n <NameSpace> get secrets/idm-framework -o yaml
   Where <NameSpace> is the namespace in which you are running the solution.
   
   3. Under the Secret service definition, replace the value of password tag with the Base64 value that you retrieved in the previous step.

4. In a text editor, open the idm-framework.yaml file and make the following changes in it:

   1. Replace each instance of the <NameSpace> tag with your namespace, where you will deploy the application.
   2. Replace all the instances of the <FQDN> tag with the FQDN of your IdM Framework instance.
   3. Replace the <SSL-Secret> tag with the valid certificate name.
   4. Save the idm-framework.yaml file.

5. Go to Google Cloud Console and select the Kubernetes Engine tile.

   

6. On the Kubernetes Engine window, perform the following steps:

   1. In the left pane, under Resource Management, click Clusters.
   2. In the right pane, copy the name of the cluster from the Name column. You will need the cluster name later while updating the kubeconfig file.
   3. In upper-right corner of the window, click on the icon to open Cloud Shell.

   

7. In Cloud Shell, perform the following steps:

   1. Run the following command to authenticate with gcloud:

      gcloud auth login

   2. Run the following command to list the project IDs:

      gcloud config list project

   3. Copy the value of the project ID to which you want to deploy the application.

   4. Run the following command to set the project ID:

      gcloud config set project <PROJECT_ID>

      Where <PROJECT_ID> is the ID that you copied in previous step.

   5. Run the following command to update the kubeconfig file and to point kubectl to a specific cluster in GKE:

      gcloud container clusters get-credentials <Cluster_name> --region <Region>

      Where,
      - <Cluster_name> is the name of the cluster you copied in step 6(b).
      - <region> is the location of this deployment.

   6. Open the idm-framework.yaml file that you saved earlier in step 4(d) and copy the contents of the file.

   7. Go to Cloud Shell, create a new file in a text editor and paste the content that you copied in previous step.

   8. Save the file as idm-framework.yaml.

   9. Run the following command to deploy the application:

      kubectl apply -f idm-framework.yaml -n=<NameSpace>

      Where, <NameSpace> is the namespace, where you want to deploy the application.

8. On Google Cloud Console, go to the Workloads tab to check and ensure that Status of all the workloads is OK.

   

9. Go to the Services & Ingress tab and on the Services tag, ensure that Status of all the services is OK.

   

10. Go to the INGRESS tab, in the Frontends column, click on the URL. The URL is the FQDN of your Identity Management Farmework service.

    

    After you click on the URL, you will be able to aceess the Identity Management Farmework portal.

    For production environments, it is highly recommended to change the default password of the IdM Framework administrator account. Once you are logged in using the default credentials, go to the Credentials tab and change the password.

11. Custom schemas and certificates required for Microsoft Graph API are included in the package. To add custom certificates to the IdM Farmework keystore, perform the following steps:

    1. Run the following command to enter into the IdM Framework pod, which has IdM Framework instance running on it:

       kubectl exec -it -n=<NameSpace> <pod_NAME> -- bash

    2. Run the ./import_cert.sh script to add the required certificates into the IdM Framework keystore.

    3. Ensure that the Schema-Extension.xsd file is present in the /opt/midpoint/var/schema/ directory of the IdM Framework pod. If not, click here to download the file, place it in the /schema directory, and restart the IdM Framework pod.

12. If you want to add other certificates as per your requirement, perform the following steps:

    1. Run the following command to enter into the pod, which has IdM Framework instance running on it:

       kubectl exec -it -n=<NameSpace> <pod_NAME> -- bash

    2. Place the required certificates in the var directory of IdM Framework. Run the following command to go to the var directory:

       cd /opt/midpoint/var

    3. Run the following command to add the required certificates in the keystore file:

       keytool -keystore keystore.jceks -storetype jceks -import -alias <alias_name> -trustcacerts -file <path_to_certificate_file>

       For example, 

       keytool -keystore keystore.jceks -storetype jceks -import -alias ADCert -trustcacerts -file IssuingCertificate.crt

Deployment of Identity Management Framework for Amazon Elastic Beanstalk

Amazon Elastic Beanstalk is an AWS-managed platform as a service (PaaS) model that simplifies the process of deploying and managing web applications. With a pre-configured server, developers can focus on their code and business logic without worrying about the infrastructure. In addition, it reduces the cost of managing the deployment locally.

Deploying IdM Framework on Amazon Elastic Beanstalk makes the adoption of the solution easier and quicker.

Prerequisites

Before you start the configuration to deploy the IdM Framework on Amazon Elastic Beanstalk, ensure the following:

1. You must have an active Amazon Web Services (AWS) account with Amazon Elastic Beanstalk enabled on it.

2. Download the Single Instance-Beanstalk_IdM.zip package by clicking the Download raw file icon on the right side and save it on your local machine.

Single Instance of IdM Framework

Perform the following steps:

1. Update the "Single Instance-Beanstalk_IdM.zip" package

2. Configure a single instance

Update the "Single Instance-Beanstalk_IdM.zip" package

Update the Single Instance-Beanstalk_IdM.zip package that you downloaded as a prerequisite.

1. Open the zip package and replace the Certificate.crt and private.key with your own TLS Certificate and Private Key file for the HTTPS Traffic (Do not change the file names as they are mentioned in default.conf for the NGINX)

Configure a Single Instance

Perform the following steps to configure the application for a single instance of IdM Framework on Elastic Beanstalk:

1. On the Amazon Elastic Beanstalk (EBS) console, in the right pane, under Get started, click Create application.

   

2. On the Configure environment window, under Environment tier, select Web server environment.

3. Under Application information, in the Application name field, enter a name for the application (for example, POC-IdM-Framework).

4. (Optional) Under Application tags, click Add tag or Remove tag to add or remove the tags according to your preferred configuration.

   

5. Under Environment information, in the Environment name field, change the name (for example, POC-IdM-Framework-ENV), and then enter the domain name according to the availability for domain and your application.

   

6. Under Platform, perform the following steps:

   1. Under Platform type, select Managed platform.
   2. In the Platform field, select Docker.
   3. In the Platform branch field, select Docker running on 64bit Amazon Linux 2023 or the latest version available.

   4. In the Platform version field, select the latest version of Docker. For example, 4.1.1 (Recommended) or the latest version available.

      

7. Under Application code, select Upload your code.

8. Under Version label, add a unique name for the version of your application code.

9. Under Source code origin, select Local file, select Choose file to search, and then select the Single Instance-Beanstalk_IdM.zip file that you downloaded.

   

10. Under Presets, select Single instance (free tier eligible), and then select Next.

    

11. On the Configure service access window, keep the default settings for Service role, EC2 key pair, and EC2 instance profile. Select Next.

    

12. (Optional) On the Set up networking, database, and tags window, configure as per the required AWS Network Configuration and then select Next.

    

13. On the Configure instance traffic and scaling window, configure EC2 security groups.

    Make sure that the security group assigned to your configuration has an inbound rule allowing HTTPS and HTTP traffic on port 443 and 8080 from the security group associated with the Elastic Beanstalk EC2 instances. It is advisable to first create a custom security group and then select it in the step above. If not selected, a new group will be created and assigned.

    

14. In the Instance types field, make sure t3.medium or a higher configuration instance type is selected. The rest of the settings can be configured as required. Once done, select Next.

    

15. On the Configure updates, monitoring, and logging window, under Platform software > Container options, select Proxy server as none. The rest of the settings can be configured as required. Select Next.

    

16. On the Review window, review the configurations and select Submit. After the POC-IdM-Framework-ENV environment is successfully created, the following window is displayed:

    

Test the Solution

Perform the following steps to verify the successful deployment of SafeNet Application Gateway:

1. Copy the environment URL (for example, aws-idm.us-west-1.elasticbeanstalk.com) from the Amazon Elastic Beanstalk Environment window.

2. Navigate to the login URL of the IdM Framework login console, log in using https://< Environment URL>/midpoint URL.

   

3. Enter the default administrator credentials. You should be successfully logged in to the IdM Framework.