Merge pull request #410 from jtnord/add-developer-docs

Add developer docs
jenkinsci · Oct 3, 2024 · d4eba97 · d4eba97
2 parents 3afbfca + b48a299
commit d4eba97
Show file tree

Hide file tree

Showing 64 changed files with 260 additions and 0 deletions.
diff --git a/docs/developer/AD-FS/adds-images/adds_additional-options.png b/docs/developer/AD-FS/adds-images/adds_additional-options.png
diff --git a/docs/developer/AD-FS/adds-images/adds_create-new-domain.png b/docs/developer/AD-FS/adds-images/adds_create-new-domain.png
diff --git a/docs/developer/AD-FS/adds-images/adds_dc-options.png b/docs/developer/AD-FS/adds-images/adds_dc-options.png
diff --git a/docs/developer/AD-FS/adds-images/adds_ignore-dns-delegation.png b/docs/developer/AD-FS/adds-images/adds_ignore-dns-delegation.png
diff --git a/docs/developer/AD-FS/adds-images/adds_paths.png b/docs/developer/AD-FS/adds-images/adds_paths.png
diff --git a/docs/developer/AD-FS/adds-images/adds_prerequisites-check.png b/docs/developer/AD-FS/adds-images/adds_prerequisites-check.png
diff --git a/docs/developer/AD-FS/adds-images/adds_promote-to-dc.png b/docs/developer/AD-FS/adds-images/adds_promote-to-dc.png
diff --git a/docs/developer/AD-FS/adds-images/adds_review-options.png b/docs/developer/AD-FS/adds-images/adds_review-options.png
diff --git a/docs/developer/AD-FS/adfs-client-images/ADFS_access-controll-permit-everyone.png b/docs/developer/AD-FS/adfs-client-images/ADFS_access-controll-permit-everyone.png
diff --git a/docs/developer/AD-FS/adfs-client-images/ADFS_complete-wizard.png b/docs/developer/AD-FS/adfs-client-images/ADFS_complete-wizard.png
diff --git a/docs/developer/AD-FS/adfs-client-images/ADFS_configure-web-api.png b/docs/developer/AD-FS/adfs-client-images/ADFS_configure-web-api.png
diff --git a/docs/developer/AD-FS/adfs-client-images/ADFS_create-application-gropup.png b/docs/developer/AD-FS/adfs-client-images/ADFS_create-application-gropup.png
diff --git a/docs/developer/AD-FS/adfs-client-images/ADFS_create-application-group-1.png b/docs/developer/AD-FS/adfs-client-images/ADFS_create-application-group-1.png
diff --git a/docs/developer/AD-FS/adfs-client-images/ADFS_create-client-and-redirect-uri.png b/docs/developer/AD-FS/adfs-client-images/ADFS_create-client-and-redirect-uri.png
diff --git a/docs/developer/AD-FS/adfs-client-images/ADFS_create-shared-secret.png b/docs/developer/AD-FS/adfs-client-images/ADFS_create-shared-secret.png
diff --git a/docs/developer/AD-FS/adfs-client-images/ADFS_post-install-start-tool.png b/docs/developer/AD-FS/adfs-client-images/ADFS_post-install-start-tool.png
diff --git a/docs/developer/AD-FS/adfs-client-images/ADFS_select-claims.png b/docs/developer/AD-FS/adfs-client-images/ADFS_select-claims.png
diff --git a/docs/developer/AD-FS/adfs-groups-images/ADFS_groups-application-group.png b/docs/developer/AD-FS/adfs-groups-images/ADFS_groups-application-group.png
diff --git a/docs/developer/AD-FS/adfs-groups-images/ADFS_groups-edit-web-api.png b/docs/developer/AD-FS/adfs-groups-images/ADFS_groups-edit-web-api.png
diff --git a/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-1.png b/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-1.png
diff --git a/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-2.png b/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-2.png
diff --git a/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-3.png b/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-3.png
diff --git a/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-4.png b/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-4.png
diff --git a/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-5.png b/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-5.png
diff --git a/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-6.png b/docs/developer/AD-FS/adfs-groups-images/ADFS_groups_transform-rules-6.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_configuration-user.png b/docs/developer/AD-FS/adfs-images/ADFS_configuration-user.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_configure_adfs.png b/docs/developer/AD-FS/adfs-images/ADFS_configure_adfs.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_create-first-server.png b/docs/developer/AD-FS/adfs-images/ADFS_create-first-server.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_database.png b/docs/developer/AD-FS/adfs-images/ADFS_database.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_display-name.png b/docs/developer/AD-FS/adfs-images/ADFS_display-name.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_post_install_warnings.png b/docs/developer/AD-FS/adfs-images/ADFS_post_install_warnings.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_pre-requisites-check.png b/docs/developer/AD-FS/adfs-images/ADFS_pre-requisites-check.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_review-options.png b/docs/developer/AD-FS/adfs-images/ADFS_review-options.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_review_options.png b/docs/developer/AD-FS/adfs-images/ADFS_review_options.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_search-account-1.png b/docs/developer/AD-FS/adfs-images/ADFS_search-account-1.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_search-account-2.png b/docs/developer/AD-FS/adfs-images/ADFS_search-account-2.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_select-account-1.png b/docs/developer/AD-FS/adfs-images/ADFS_select-account-1.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_select-account-2.png b/docs/developer/AD-FS/adfs-images/ADFS_select-account-2.png
diff --git a/docs/developer/AD-FS/adfs-images/ADFS_ssl-cert-choice.png b/docs/developer/AD-FS/adfs-images/ADFS_ssl-cert-choice.png
diff --git a/docs/developer/AD-FS/setup-images/OS_custom-install-choice.png b/docs/developer/AD-FS/setup-images/OS_custom-install-choice.png
diff --git a/docs/developer/AD-FS/setup-images/OS_disable-ipv6.png b/docs/developer/AD-FS/setup-images/OS_disable-ipv6.png
diff --git a/docs/developer/AD-FS/setup-images/OS_install-choice.png b/docs/developer/AD-FS/setup-images/OS_install-choice.png
diff --git a/docs/developer/AD-FS/setup-images/OS_installing.png b/docs/developer/AD-FS/setup-images/OS_installing.png
diff --git a/docs/developer/AD-FS/setup-images/OS_login.png b/docs/developer/AD-FS/setup-images/OS_login.png
diff --git a/docs/developer/AD-FS/setup-images/OS_password.png b/docs/developer/AD-FS/setup-images/OS_password.png
diff --git a/docs/developer/AD-FS/setup-images/OS_server-manager-dashboard.png b/docs/developer/AD-FS/setup-images/OS_server-manager-dashboard.png
diff --git a/docs/developer/AD-FS/setup-images/roles_add-features-adds.png b/docs/developer/AD-FS/setup-images/roles_add-features-adds.png
diff --git a/docs/developer/AD-FS/setup-images/roles_add-features-dns.png b/docs/developer/AD-FS/setup-images/roles_add-features-dns.png
diff --git a/docs/developer/AD-FS/setup-images/roles_add-role-adfs.png b/docs/developer/AD-FS/setup-images/roles_add-role-adfs.png
diff --git a/docs/developer/AD-FS/setup-images/roles_add-role-dns.png b/docs/developer/AD-FS/setup-images/roles_add-role-dns.png
diff --git a/docs/developer/AD-FS/setup-images/roles_adds-next.png b/docs/developer/AD-FS/setup-images/roles_adds-next.png
diff --git a/docs/developer/AD-FS/setup-images/roles_adds-role-adds.png b/docs/developer/AD-FS/setup-images/roles_adds-role-adds.png
diff --git a/docs/developer/AD-FS/setup-images/roles_adfs-next.png b/docs/developer/AD-FS/setup-images/roles_adfs-next.png
diff --git a/docs/developer/AD-FS/setup-images/roles_confirm-restart-and-install.png b/docs/developer/AD-FS/setup-images/roles_confirm-restart-and-install.png
diff --git a/docs/developer/AD-FS/setup-images/roles_dns-next.png b/docs/developer/AD-FS/setup-images/roles_dns-next.png
diff --git a/docs/developer/AD-FS/setup-images/roles_features-next.png b/docs/developer/AD-FS/setup-images/roles_features-next.png
diff --git a/docs/developer/AD-FS/setup-images/roles_install-complete.png b/docs/developer/AD-FS/setup-images/roles_install-complete.png
diff --git a/docs/developer/AD-FS/setup-images/roles_installation-type.png b/docs/developer/AD-FS/setup-images/roles_installation-type.png
diff --git a/docs/developer/AD-FS/setup-images/roles_installing.png b/docs/developer/AD-FS/setup-images/roles_installing.png
diff --git a/docs/developer/AD-FS/setup-images/roles_roles-and-features.png b/docs/developer/AD-FS/setup-images/roles_roles-and-features.png
diff --git a/docs/developer/AD-FS/setup-images/roles_server-role-next.png b/docs/developer/AD-FS/setup-images/roles_server-role-next.png
diff --git a/docs/developer/AD-FS/setup-images/roles_server-selection.png b/docs/developer/AD-FS/setup-images/roles_server-selection.png
diff --git a/docs/developer/AD-FS/setup-test-instance.md b/docs/developer/AD-FS/setup-test-instance.md
diff --git a/docs/developer/developer-testing.md b/docs/developer/developer-testing.md
@@ -0,0 +1,27 @@
+# Testing changes
+
+As well as the unit tests run as part of the build, there are additional tests that can be run to confirm there are no regressions
+
+## Acceptance Test Harness
+
+The [Jenkins acceptance test harness](https://github.com/jenkinsci/acceptance-test-harness) contains a test against a real OpenID Provider (OP).
+At the time of writing this is limited to a dynamically created [KeyCloak instance](https://www.keycloak.org/).
+
+Assuming you have an environment prepared to run the [ATH](https://github.com/jenkinsci/acceptance-test-harness?tab=readme-ov-file#running-tests) you can run these the tests against a local version of the plugin.
+
+1. create a local build of your changes with `mvn package`
+2. switch to the directory containing the ATH clone
+    1. run the plugins specific test using with `LOCAL_JARS=/full/path/to/oic-auth-plugin/target/oic-auth.hpi mvn test -Dtest=OicAuthPluginTest`
+
+## OpenID Conformance Tests
+
+The [OpenID Foundation](https://openid.net/) maintains a set of [conformance tests](https://openid.net/how-to-certify-your-implementation/) for both OpenID Providers (OPs) and OpenID Relying Parties (RPs).
+Details for how to run the majority of the tests (RP) for this plugin is detailed [here](https://openid.net/certification/connect_rp_testing/) with specifics for logout based tests [here](https://openid.net/certification/connect_rp_logout_testing/).
+It is recommended to create a static client for the tests.
+
+## Developer Testing against OPs
+
+Several OpenID Providers (OPs) are freely available in order to setup and test changes locally.
+Notable providers are [KeyCloak](https://www.keycloak.org/), [Dex](https://dexidp.io/), and [Google](https://developers.google.com/identity/openid-connect/openid-connect).
+
+Active Directory Federation Service ([AD FS](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/ad-fs-overview)) is another provider, however creating a test instance of this is complicated and is documented in [this page](./AD-FS/setup-test-instance.md).