diff --git a/bundles/uds-bundle.yaml b/bundles/uds-bundle.yaml
index aca9390..447fc20 100644
--- a/bundles/uds-bundle.yaml
+++ b/bundles/uds-bundle.yaml
@@ -39,6 +39,18 @@ packages:
- name: TENANT_TLS_CACERT
description: "The CA cert for the tenant gateway (must be base64 encoded)"
path: tls.cacert
+ istio-controlplane:
+ uds-global-istio-config:
+ values:
+ - path: classificationBanner.text
+ value: "UNCLASSIFIED" # Possible values: UNCLASSIFIED, CUI, CONFIDENTIAL, SECRET, TOP SECRET, TOP SECRET//SCI, UNKNOWN
+ - path: classificationBanner.addFooter
+ value: true
+ - path: classificationBanner.enabledHosts
+ value:
+ - keycloak.admin.{{ .Values.domain }}
+ - sso.{{ .Values.domain }}
+ - grafana.admin.{{ .Values.domain }}
- name: core-identity-authorization
path: ../uds-core/build/
@@ -61,6 +73,12 @@ packages:
GOOGLE_IDP_CORE_ENTITY_ID: "https://sso.uds.dev/realms/uds"
GOOGLE_IDP_ADMIN_GROUP: "uds-core-dev-admin"
GOOGLE_IDP_AUDITOR_GROUP: "uds-core-dev-auditor"
+ - path: realmAuthFlows
+ value:
+ USERNAME_PASSWORD_AUTH_ENABLED: true
+ X509_AUTH_ENABLED: true
+ SOCIAL_AUTH_ENABLED: true
+ OTP_ENABLED: true
- name: core-monitoring
path: ../uds-core/build/
diff --git a/docs/.images/diagrams/README.md b/docs/.images/diagrams/README.md
new file mode 100644
index 0000000..5edebda
--- /dev/null
+++ b/docs/.images/diagrams/README.md
@@ -0,0 +1,13 @@
+# UDS Identity Config Diagrams
+
+## How to Customize
+To customize the diagram, download the svg and in [draw.io](https://draw.io) create a new diagram and load in the svg.
+
+To download the [svg from github](https://github.com/defenseunicorns/uds-identity-config/tree/main/docs/.images), select one of the svg files, then select the download button in the top right of the `Preview` view.
+
+Alternatively you can also download the svg from the [uds.defenseunicorns.com](https://uds.defenseunicorns.com) docsite by right clicking and selecting the `Save image as` option.
+
+It doesn't matter which svg you download, they all contain the metadata for the other layers mentioned above (you may need to enable the layers pop up in [draw.io](https://draw.io) to change your layer).
+
+
+#### If you have suggestions for the diagrams, we welcome issues or pull requests contributions to [uds-core](https://github.com/defenseunicorns/uds-identity-config).
diff --git a/docs/.images/diagrams/uds-core-auth-flows-basic.svg b/docs/.images/diagrams/uds-core-auth-flows-basic.svg
new file mode 100644
index 0000000..a2a9217
--- /dev/null
+++ b/docs/.images/diagrams/uds-core-auth-flows-basic.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/.images/diagrams/uds-core-auth-flows-complex.svg b/docs/.images/diagrams/uds-core-auth-flows-complex.svg
new file mode 100644
index 0000000..8e06a13
--- /dev/null
+++ b/docs/.images/diagrams/uds-core-auth-flows-complex.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/docs/.images/diagrams/uds-core-auth-flows-options.svg b/docs/.images/diagrams/uds-core-auth-flows-options.svg
new file mode 100644
index 0000000..ed4cf57
--- /dev/null
+++ b/docs/.images/diagrams/uds-core-auth-flows-options.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/reference/UDS Core/IdAM/authentication-flows.md b/docs/reference/UDS Core/IdAM/authentication-flows.md
index 976d4f9..7062753 100644
--- a/docs/reference/UDS Core/IdAM/authentication-flows.md
+++ b/docs/reference/UDS Core/IdAM/authentication-flows.md
@@ -4,17 +4,59 @@ tableOfContents:
maxHeadingLevel: 5
---
-# Authentication Flow Customization
+## Authentication Flow Options
+
+UDS Core comes equipped with a robust authentication framework that supports multiple authentication methods to meet diverse security requirements and user preferences. Here’s a breakdown of the authentication options available:
+
+---
+
+1. Username and Password
+
+ The most traditional form of authentication involves users providing a username and password that must match the credentials stored in the system. This method is widely used due to its simplicity and direct control over access credentials.
+
+ ---
+
+2. SSO (Single Sign-On)
+
+ Single Sign-On (SSO) allows users to authenticate with one set of credentials to access multiple applications. UDS Core can be configured to integrate with various SSO providers, such as Google SSO, Microsoft Entra, and others, streamlining the login process and reducing the burden of managing multiple usernames and passwords.
+
+ ---
+
+3. x509 Certificate
+
+ x509 certificates provide a way to authenticate using digital certificates. It is commonly used in environments that require higher security, such as corporate or governmental networks. This method uses public key infrastructure (PKI) to verify the user's identity through a trusted certificate authority.
+
+---
+
+
+
+## Authentication Flows in UDS Core
+
+UDS Core is shipped with a basic authentication flow that includes all three options out of the box. The following diagram shows the basic authentication flows that are deployed with standard UDS Core:
+
+
+
+### Customizing Authentication Flows
+
+Different operational environments may necessitate distinct authentication flows to comply with specific security policies, regulatory demands, or demographic requirements. UDS Core facilitates the customization of these flows, allowing for tailored security measures and user interfaces. The diagram below illustrates various combinations of the three authentication methods that can be adapted to meet unique operational needs:
+
+
+
+These customizations not only ensure appropriate security configurations by enabling or disabling specific flows but also maintain a seamless user experience by adjusting the Keycloak theme accordingly.
+
+The following sections provide a step-by-step guide on how to customize UDS Core to deploy specific authentication flows, catering to the particular needs and guidelines of your environment.
+
+## Authentication Flow Customization
:::note
-Environment variables configured in the [uds-core Keycloak values.yaml file](https://github.com/defenseunicorns/uds-core/blob/main/src/keycloak/chart/values.yaml#L30-32) have `REALM_` appended to them during creation. See [ Customization docs](https://uds.defenseunicorns.com/reference/uds-core/idam/customization/) for more information.
+Environment variables configured in the [uds-core Keycloak values.yaml file](https://github.com/defenseunicorns/uds-core/blob/main/src/keycloak/chart/values.yaml#L30-32) have `REALM_` appended to them during creation. See [ Customization docs](https://uds.defenseunicorns.com/reference/uds-core/idam/image-customizations/) for more information.
:::
:::warning
If upgrading uds-core, be aware that Keycloak Admin manual configuration will probably be required to set new Realm values. See the manual configuration section below for how to do this.
:::
-## Bundle Overrides
+### Bundle Overrides
To simplify the configuration of the available authentication flows, the following three environment variables have been exposed. These variables default to `true` in UDS Core, override their values in a bundle to disable.
:::note
@@ -29,12 +71,12 @@ These settings allow for enabling/disabling one or more of the Auth flows. Be aw
These three variables handle the complexities of configuring the following environment variables, which are responsible for both visual (theme) and security (realm). The following variables are not exposed for overriding.
-## Manual Configuration
+### Manual Configuration
-### Theme Configurations
+#### Theme Configurations
Theme's cannot be clickops'ed, for these changes to take affect an upgrade or fresh deployment will be required. Another option is exec-ing into the the keycloak pod and copying in the new themes to the `/opt/keycloak/theme/themes/login/` directory. After copying in the theme changes, the theme changes depend on environment variables being defined in the [theme.properties file](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/theme/login/theme.properties). The above table demonstrates the different environment variables for the `theme.properties` file.
-### Realm Configurations
+#### Realm Configurations
All Realm Configurations require accesss to the Keycloak admin portal.
| Configuration | How to Configure |
diff --git a/docs/reference/UDS Core/IdAM/customization.md b/docs/reference/UDS Core/IdAM/customization.md
index b9a228a..2962895 100644
--- a/docs/reference/UDS Core/IdAM/customization.md
+++ b/docs/reference/UDS Core/IdAM/customization.md
@@ -1,67 +1,35 @@
---
-title: Customization
+title: Image Customizations
tableOfContents:
maxHeadingLevel: 5
---
-## Testing custom image in UDS Core
-
-### Build a new image
-
-```bash
-# create a dev image uds-core-config:keycloak
-uds run dev-build
-
-# optionally, retag and publish to temporary registry for testing
-docker tag uds-core-config:keycloak ttl.sh/uds-core-config:keycloak
-docker push ttl.sh/uds-core-config:keycloak
-```
-
-### Update UDS Core references
-
-The custom image reference will need to be update in a few places in the `uds-core` repository:
-
-* Update [zarf.yaml](https://github.com/defenseunicorns/uds-core/blob/main/src/keycloak/zarf.yaml#L24) to include updated image
-* Specify `configImage` in Keycloak [values.yaml](https://github.com/defenseunicorns/uds-core/blob/main/src/keycloak/chart/values.yaml#L10)
-* If the truststore has been updated, see [gateway configuration instructions](./CUSTOMIZE.md#configure-istio-gateways-cacert-in-uds-core)
-
-### Deploy UDS Core
-
-```bash
-# build and deploy uds-core
-uds run test-uds-core
-```
-
-See [UDS Core](https://github.com/defenseunicorns/uds-core/blob/main/README.md) for further details
-
-## Customizations
-
-### Add additional jars
+## Add additional jars
Adding additional jars to Keycloak's deployment is as simple as adding that jar to the [src/extra-jars directory](https://github.com/defenseunicorns/uds-identity-config/tree/main/src/extra-jars).
Adding new jars will require building a new identity-config image for [uds-core](https://github.com/defenseunicorns/uds-core).
-See [Testing custom image in UDS Core](./CUSTOMIZE.md#testing-custom-image-in-uds-core) for building, publishing, and using the new image with `uds-core`.
+See [Testing custom image in UDS Core](https://uds.defenseunicorns.com/reference/uds-core/idam/testing-deployment-customizations/) for building, publishing, and using the new image with `uds-core`.
Once `uds-core` has sucessfully deployed with your new image, viewing the Keycloak pod can provide insight into a successful deployment or not. Also describing the Keycloak pod, should display your new image being pulled instead of the default image defined [here](https://github.com/defenseunicorns/uds-core/blob/main/src/keycloak/chart/values.yaml#L10) in the events section.
-### Customize Theme
+## Customizing Theme
-#### Official Theming Docs
+**Official Theming Docs**
* [Official Keycloak Theme Docs](https://www.keycloak.org/docs/latest/server_development/#_themes)
* [Official Keycloak Theme Github](https://github.com/keycloak/keycloak/tree/b066c59a83c99d757d501d8f5e6061372706d24d/themes/src/main/resources/theme)
-Changes can be made to the [src/theme](https://github.com/defenseunicorns/uds-identity-config/tree/main/src/theme) directory. At this time only Account and Login themes are included, but could be changed to include email, admin, and welcome themes as well.
+Changes can be made to the [src/theme](https://github.com/defenseunicorns/uds-identity-config/tree/main/src/theme) directory. At this time only Account and Login themes are included, but c email, admin, and welcome themes could be added as well.
-#### Testing Changes
+### Testing Changes
To test the `identity-config` theme changes, a local running Keycloak instance is required.
Don't have a local Keycloak instance? The simplest testing path is utilizing [uds-core](https://github.com/defenseunicorns/uds-core), specifically the `dev-identity` task. This will create a k3d cluster with Istio, Pepr, Keycloak, and Authservice.
-Once that cluster is up and healthy and after making theme changes:
+Once that cluster is up and healthy and after making theme changes, utilize this task to :
1. Execute this command:
@@ -71,17 +39,17 @@ Once that cluster is up and healthy and after making theme changes:
2. View the changes in the browser
-### Customizing Realm
+## Customizing Realm
The `UDS Identity` realm is defined in the realm.json found in [src/realm.json](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/realm.json). This can be modified and will require a new `uds-identity-config` image for `uds-core`.
:::note
-Be aware that changing values in the realm may also need be to updated throughout the configuration of Keycloak and Authservice in `uds-core`. For example, changing the realm name will break a few different things within Keycloak unless those values are changed in `uds-core` as well.
+Be aware that changing values in the realm may also need to be updated throughout the configuration of Keycloak and Authservice in `uds-core`. For example, changing the realm name will break a few different things within Keycloak unless those values are changed in `uds-core` as well.
:::
-See the [Testing custom image in UDS Core](./CUSTOMIZE.md#testing-custom-image-in-uds-core) for building, publishing, and using the new image with `uds-core`.
+See the [Testing custom image in UDS Core](https://uds.defenseunicorns.com/reference/uds-core/idam/testing-deployment-customizations/) for building, publishing, and using the new image with `uds-core`.
-#### Templated Realm Values
+### Templated Realm Values
Keycloak supports using environment variables within the realm configuration, see [docs](https://www.keycloak.org/server/importExport).
@@ -127,175 +95,7 @@ overrides:
> These environment variables can be found in the [realm.json](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/realm.json).
-#### Customize Session and Access Token Timeouts
+### Customizing Session and Access Token Timeouts
The `SSO_SESSION_IDLE_TIMEOUT` specifies how long a session remains active without user activity, while the `ACCESS_TOKEN_LIFESPAN` defines the validity duration of an access token before it requires refreshing. The `SSO_SESSION_MAX_LIFESPAN` determines the maximum duration a session can remain active, regardless of user activity.
-To ensure smooth session management, configure the idle timeout to be longer than the access token lifespan (e.g., 10 minutes idle, 5 minutes lifespan) so tokens can be refreshed before the session expires, and ensure the max lifespan is set appropriately (e.g., 8 hours) to enforce session limits. Misalignment, such as setting a longer token lifespan than the idle timeout or not aligning the max lifespan with session requirements, can result in sessions ending unexpectedly or persisting longer than intended.
-
-### Customize Truststore
-
-The default truststore is configured in a [script](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/truststore/ca-to-jks.sh) and excuted in the [Dockerfile](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile). There is a few different ways the script could be customized.
-
-* [Change where the DoD CA zip file are pulled from.](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile#L31), defualting to DOD UNCLASS certs but could be updated for local or another source.
-* [Change the Regex Exclusion Filter](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile#30), used by the ca-to-jks script to exclude certain certs from being added to the final truststore.
-* [Change the truststore password](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/truststore/ca-to-jks.sh#L29)
-
-#### Build test `authorized_certs.zip`
-
-Utilizing the [`regenerate-test-pki` task](https://github.com/defenseunicorns/uds-identity-config/blob/main/tasks.yaml), you can create a test `authorized_certs.zip` to use for the truststore.
-
-To use the `regenerate-test-pki` task:
-
-* Create `csr.conf`
-
- ```conf
- [req]
- default_bits = 2048
- default_keyfile = key.pem
- distinguished_name = req_distinguished_name
- req_extensions = req_ext
- x509_extensions = v3_ext
-
- [req_distinguished_name]
- countryName = Country Name (2 letter code)
- countryName_default = US
- stateOrProvinceName = State or Province Name (full name)
- stateOrProvinceName_default = Colorado
- localityName = Locality Name (eg, city)
- localityName_default = Colorado Springs
- organizationName = Organization Name (eg, company)
- organizationName_default = Defense Unicorns
- commonName = Common Name (e.g. server FQDN or YOUR name)
- commonName_default = uds.dev
-
- [req_ext]
- subjectAltName = @alt_names
-
- [v3_ext]
- subjectAltName = @alt_names
-
- [alt_names]
- DNS.0 = *.uds.dev
- ```
-
-* ```bash
- # Generates new authorized_certs.zip
- uds run regenerate-test-pki
- ```
-
-#### Update Dockerfile and build image
-
-Update `CA_ZIP_URL` in [Dockerfile](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile) to refer to the generated `authorized_certs.zip`
-
-```bash
-ARG CA_ZIP_URL=authorized_certs.zip
-```
-
-Build config image
-
-```bash
-# build image
-uds run dev-build
-```
-
-:::note
-If you're getting errors from the ca-to-jks.sh script, verify your zip folder is in the correct directory.
-:::
-
-#### Configure Istio Gateways CACERT in UDS Core
-
-```bash
-# In `uds-core` create cacert from the new identity-config image
-uds run -f src/keycloak/tasks.yaml cacert --set IMAGE_NAME= --set VERSION=
-```
-
-```bash
-# Update tenant and admin gateway with generated cacerts
-uds run -f src/keycloak/tasks.yaml dev-cacert
-```
-
-#### Deploy UDS Core with new uds-identity-config
-
-See [Testing custom image in UDS Core](./CUSTOMIZE.md#testing-custom-image-in-uds-core)
-
-#### Verify Istio Gateway configuration
-
-```bash
-# Verify the "Acceptable client certificate CA names"
-openssl s_client -connect sso.uds.dev:443
-```
-
-### Custom Plugin
-
-:::note
-This isn't recommended, however can be achieved if necessary
-:::
-
-:::note
-Making these changes iteratively and importing into Keycloak to create a new realm can help to alleviate typo's and mis-configurations. This is also the quickest solution for testing without having to create,build,deploy with new images each time.
-:::
-
-The plugin provides the auth flows that keycloak uses for x509 (CAC) authentication as well as some of the surrounding registration flows.
-
-One nuanced auth flow is the creation of a Mattermost ID attribute for users. [CustomEventListener](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/plugin/src/main/java/com/defenseunicorns/uds/keycloak/plugin/eventListeners/RegisterEventListenerProvider.java is responsible for generating the unique ID.
-
-:::note
-When creating a user via ADMIN API or ADMIN UI, the 'REGISTER' event is not triggered, resulting in no Mattermost ID attribute generation. This will need to be done manually via click ops or the api. An example of how the attribute can be set via api can be seen [here](https://github.com/defenseunicorns/uds-common/blob/b2e8b25930c953ef893e7c787fe350f0d8679ee2/tasks/setup.yaml#L46).
-:::
-
-### Developing
-
-See [PLUGIN.md](./PLUGIN.md).
-
-### Configuration
-
-In addition, modify the realm for keycloak, otherwise the realm will require plugin capabilities for registering and authenticating users. In the current [realm.json](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/realm.json) there is a few sections specifically using the plugin capabilities. Here is the following changes necessary:
-
-* Remove all of the `UDS ...` authenticationFlows:
- * `UDS Authentication`
- * `UDS Authentication Browser - Conditional OTP`
- * `UDS Registration`
- * `UDS Reset Credentials`
- * `UDS registration form`
-
-* Make changes to authenticationExecutions from the `browser` authenticationFlow:
- * Remove `auth-cookie`
- * Remove `auth-spnego`
- * Remove `identity-provider-redirector`
- * Update the remaining authenticationFlow
- * `"requirement": "REQUIRED"`
- * `"flowAlias": "Authentication"`
-
-* Remove `registration-profile-action` authenticationExecution from the `registration form` authenticationFlow
-
-* Update the realm flows:
- * `"browserFlow": "browser"`
- * `"registrationFlow": "registration"`
- * `"resetCredentialsFlow": "reset credentials"`
-
-### Disabling
-
-If desired the Plugin can be removed from the identity-config image by commenting out these lines in the [Dockerfile](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile):
-
-```bash
-COPY plugin/pom.xml .
-COPY plugin/src ../src
-
-RUN mvn clean package
-```
-
-### Building New Image with Updates
-
-Once satisfied with changes and tested that they work, see [Testing custom image in UDS Core](./CUSTOMIZE.md#testing-custom-image-in-uds-core) for building, publishing, and using the new image with `uds-core`.
-
-### Transport Custom Image with Zarf
-
-For convenience, a Zarf package definition has been included to simplify custom image transport and install in air-gapped systems.
-
-#### Build the Zarf package
-
-Use the included UDS task to build the custom image and package it with Zarf:
-
-```bash
-uds run build-zarf-pkg
-```
+To ensure smooth session management, configure the idle timeout to be longer than the access token lifespan (e.g., 10 minutes idle, 5 minutes lifespan) so tokens can be refreshed before the session expires, and ensure the max lifespan is set appropriately (e.g., 8 hours) to enforce session limits. Misalignment, such as setting a longer token lifespan than the idle timeout or not aligning the max lifespan with session requirements, can result in sessions ending unexpectedly or persisting longer than intended.
\ No newline at end of file
diff --git a/docs/reference/UDS Core/IdAM/plugin.md b/docs/reference/UDS Core/IdAM/plugin.md
index cf7617b..e68f9a4 100644
--- a/docs/reference/UDS Core/IdAM/plugin.md
+++ b/docs/reference/UDS Core/IdAM/plugin.md
@@ -1,5 +1,5 @@
---
-title: Keycloak Plugin
+title: Custom Keycloak Plugins
description: This documentation discusses the Keycloak plugin and the additional logic it provides.
---
@@ -41,7 +41,7 @@ mvn -version
After making changes to the plugin code and verifying that unit tests are passing ( and hopefully writing some more ), test against Keycloak.
-See the `New uds-identity-config Image` section in the [CUSTOMIZE.md](./CUSTOMIZE.md#new-uds-identity-config-image) for building, publishing, and using the new image with `uds-core`.
+See the `New uds-identity-config Image` [section](https://uds.defenseunicorns.com/reference/uds-core/idam/testing-deployment-customizations/#build-a-new-image) for building, publishing, and using the new image with `uds-core`.
## Plugin Unit Testing / Code Coverage
@@ -77,3 +77,58 @@ Open the `src/plugin/target/site/surefire-report.html` file in your browser to v
Open the `src/plugin/target/site/jacoco/index.html` file in your browser to view the unit test coverage report generated by jacoco.
Both reports will hot reload each time they are regenerated, no need to open each time.
+
+## New Custom Plugin Development
+
+:::caution
+This isn't recommended, however can be achieved if necessary
+:::
+
+:::note
+Making these changes iteratively and importing into Keycloak to create a new realm can help to alleviate typo's and mis-configurations. This is also the quickest solution for testing without having to create,build,deploy with new images each time.
+:::
+
+The plugin provides the auth flows that keycloak uses for x509 (CAC) authentication as well as some of the surrounding registration flows.
+
+One nuanced auth flow is the creation of a Mattermost ID attribute for users. [CustomEventListener](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/plugin/src/main/java/com/defenseunicorns/uds/keycloak/plugin/eventListeners/RegisterEventListenerProvider.java) is responsible for generating the unique ID.
+
+:::note
+When creating a user via ADMIN API or ADMIN UI, the 'REGISTER' event is not triggered, resulting in no Mattermost ID attribute generation. This will need to be done manually via click ops or the api. An example of how the attribute can be set via api can be seen [here](https://github.com/defenseunicorns/uds-common/blob/b2e8b25930c953ef893e7c787fe350f0d8679ee2/tasks/setup.yaml#L46).
+:::
+
+### Configuration
+
+In addition, modify the realm for keycloak, otherwise the realm will require plugin capabilities for registering and authenticating users. In the current [realm.json](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/realm.json) there is a few sections specifically using the plugin capabilities. Here is the following changes necessary:
+
+* Remove all of the `UDS ...` authenticationFlows:
+ * `UDS Authentication`
+ * `UDS Authentication Browser - Conditional OTP`
+ * `UDS Registration`
+ * `UDS Reset Credentials`
+ * `UDS registration form`
+
+* Make changes to authenticationExecutions from the `browser` authenticationFlow:
+ * Remove `auth-cookie`
+ * Remove `auth-spnego`
+ * Remove `identity-provider-redirector`
+ * Update the remaining authenticationFlow
+ * `"requirement": "REQUIRED"`
+ * `"flowAlias": "Authentication"`
+
+* Remove `registration-profile-action` authenticationExecution from the `registration form` authenticationFlow
+
+* Update the realm flows:
+ * `"browserFlow": "browser"`
+ * `"registrationFlow": "registration"`
+ * `"resetCredentialsFlow": "reset credentials"`
+
+### Disabling
+
+If desired the Plugin can be removed from the identity-config image by commenting out these lines in the [Dockerfile](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile):
+
+```bash
+COPY plugin/pom.xml .
+COPY plugin/src ../src
+
+RUN mvn clean package
+```
diff --git a/docs/reference/UDS Core/IdAM/testing-deployment-customizations.md b/docs/reference/UDS Core/IdAM/testing-deployment-customizations.md
new file mode 100644
index 0000000..b95c4c8
--- /dev/null
+++ b/docs/reference/UDS Core/IdAM/testing-deployment-customizations.md
@@ -0,0 +1,53 @@
+---
+title: Testing and Deployment Customizations
+tableOfContents:
+ maxHeadingLevel: 5
+---
+
+## Image Management
+
+This document provides comprehensive guidelines for managing custom images within the UDS Core system, from creation and testing to deployment and transportation, particularly in restricted environments like air-gapped systems.
+
+### Building and Testing Custom Images
+
+#### Build a new image
+
+Build a custom development image for UDS Core using the following commands:
+
+```bash
+# create a dev image uds-core-config:keycloak
+uds run dev-build
+
+# optionally, retag and publish to temporary registry for testing
+docker tag uds-core-config:keycloak ttl.sh/uds-core-config:keycloak
+docker push ttl.sh/uds-core-config:keycloak
+```
+
+#### Update UDS Core references
+
+Update the custom image references in the `uds-core` repository:
+
+* Update zarf.yaml to include updated image.
+* Specify configImage in Keycloak values.yaml.
+* For truststore updates, see gateway configuration instructions.
+
+#### Deploy UDS Core
+
+Deploy UDS Core with the new custom image:
+
+```bash
+# build and deploy uds-core
+uds run test-uds-core
+```
+
+See [UDS Core](https://github.com/defenseunicorns/uds-core/blob/main/README.md) for further details
+
+## Building New Image with Updates
+
+For convenience, a Zarf package definition has been included to simplify custom image transport and install in air-gapped systems.
+
+Use the included UDS task to build the custom image and package it with Zarf:
+
+```bash
+uds run build-zarf-pkg
+```
diff --git a/docs/reference/UDS Core/IdAM/truststore-customization.md b/docs/reference/UDS Core/IdAM/truststore-customization.md
new file mode 100644
index 0000000..663538d
--- /dev/null
+++ b/docs/reference/UDS Core/IdAM/truststore-customization.md
@@ -0,0 +1,98 @@
+---
+title: Truststore Customization
+tableOfContents:
+ maxHeadingLevel: 5
+---
+
+## Customizing Truststore
+
+The default truststore is configured in a [script](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/truststore/ca-to-jks.sh) and excuted in the [Dockerfile](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile). There is a few different ways the script could be customized.
+
+* [Change where the DoD CA zip file are pulled from.](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile#L31), defualting to DOD UNCLASS certs but could be updated for local or another source.
+* [Change the Regex Exclusion Filter](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile#30), used by the ca-to-jks script to exclude certain certs from being added to the final truststore.
+* [Change the truststore password](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/truststore/ca-to-jks.sh#L29)
+
+### Build test `authorized_certs.zip`
+
+Utilizing the [`regenerate-test-pki` task](https://github.com/defenseunicorns/uds-identity-config/blob/main/tasks.yaml), you can create a test `authorized_certs.zip` to use for the truststore.
+
+To use the `regenerate-test-pki` task:
+
+* Create `csr.conf`
+
+ ```conf
+ [req]
+ default_bits = 2048
+ default_keyfile = key.pem
+ distinguished_name = req_distinguished_name
+ req_extensions = req_ext
+ x509_extensions = v3_ext
+
+ [req_distinguished_name]
+ countryName = Country Name (2 letter code)
+ countryName_default = US
+ stateOrProvinceName = State or Province Name (full name)
+ stateOrProvinceName_default = Colorado
+ localityName = Locality Name (eg, city)
+ localityName_default = Colorado Springs
+ organizationName = Organization Name (eg, company)
+ organizationName_default = Defense Unicorns
+ commonName = Common Name (e.g. server FQDN or YOUR name)
+ commonName_default = uds.dev
+
+ [req_ext]
+ subjectAltName = @alt_names
+
+ [v3_ext]
+ subjectAltName = @alt_names
+
+ [alt_names]
+ DNS.0 = *.uds.dev
+ ```
+
+* ```bash
+ # Generates new authorized_certs.zip
+ uds run regenerate-test-pki
+ ```
+
+### Update Dockerfile and build image
+
+Update `CA_ZIP_URL` in [Dockerfile](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/Dockerfile) to refer to the generated `authorized_certs.zip`
+
+```bash
+ARG CA_ZIP_URL=authorized_certs.zip
+```
+
+Build config image
+
+```bash
+# build image
+uds run dev-build
+```
+
+:::note
+If you're getting errors from the ca-to-jks.sh script, verify your zip folder is in the correct directory.
+:::
+
+### Configure Istio Gateways CACERT in UDS Core
+
+```bash
+# In `uds-core` create cacert from the new identity-config image
+uds run -f src/keycloak/tasks.yaml cacert --set IMAGE_NAME= --set VERSION=
+```
+
+```bash
+# Update tenant and admin gateway with generated cacerts
+uds run -f src/keycloak/tasks.yaml dev-cacert
+```
+
+### Deploy UDS Core with new uds-identity-config
+
+See [Testing custom image in UDS Core](https://uds.defenseunicorns.com/reference/uds-core/idam/testing-deployment-customizations/)
+
+### Verify Istio Gateway configuration
+
+```bash
+# Verify the "Acceptable client certificate CA names"
+openssl s_client -connect sso.uds.dev:443
+```
\ No newline at end of file
diff --git a/docs/reference/UDS Core/IdAM/uds-identity-config-overview.md b/docs/reference/UDS Core/IdAM/uds-identity-config-overview.md
index 7a9b93f..13fead4 100644
--- a/docs/reference/UDS Core/IdAM/uds-identity-config-overview.md
+++ b/docs/reference/UDS Core/IdAM/uds-identity-config-overview.md
@@ -1,9 +1,23 @@
---
-title: UDS Identity Config Overview
+title: Overview
sidebar:
order: 1
---
+## What is IdAM?
+
+Identity and Access Management (IdAM) refers to a framework of policies and technologies that ensure the proper people in an enterprise have the appropriate access to technology resources. IdAM systems provide tools and technologies for controlling user access to critical information within an organization through a set of business processes and by managing identities and access rights. The technology typically helps IT managers control user access to critical information within an organization by using a digital identity—which is considered unique in the system—and setting up roles, permissions, and policies. IdAM solutions ensure that users are who they claim to be (authentication) and that they can access the applications and resources they are allowed to use (authorization).
+
## What is UDS Identity Config?
-UDS Identity Config supplies the configuration for Keycloak to UDS Core.
+UDS Identity Config is a component of the UDS Core that supplies the necessary configuration for Keycloak, an open-source Identity and Access Management solution. This configuration includes setting up realms, clients, roles, and other Keycloak settings tailored specifically for the UDS environment. By managing these configurations, UDS Identity Config facilitates the seamless integration of authentication and authorization functionalities into various services within the UDS ecosystem, ensuring that security protocols are consistently applied across platforms.
+
+## IdAM Contents
+
+1. [Custom Image Testing and Deployment](https://uds.defenseunicorns.com/reference/uds-core/idam/testing-deployment-customizations/)
+2. [Image Customizations](https://uds.defenseunicorns.com/reference/uds-core/idam/image-customizations/)
+3. [Image Truststore Customization](https://uds.defenseunicorns.com/reference/uds-core/idam/truststore-customization/)
+4. [Authentication Flows Customization](https://uds.defenseunicorns.com/reference/uds-core/idam/authentication-flows/)
+5. [UDS Core Integration Testing](https://uds.defenseunicorns.com/reference/uds-core/idam/integration/)
+6. [Custom Keycloak Plugins](https://uds.defenseunicorns.com/reference/uds-core/idam/plugin/)
+7. [Upgrading Identity Config Versions](https://uds.defenseunicorns.com/reference/uds-core/idam/upgrading-versions/)