diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a4532e3c..263425c9 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -15,7 +15,7 @@ Link to Github issue. Please delete options that are not relevant. - [ ] I have followed the [contributing guidelines](https://github.com/eclipse-tractusx/portal-assets/blob/main/developer/Technical%20Documentation/Dev%20Process/How%20to%20contribute.md#commit-and-pr-guidelines) -- [ ] I have added a copyright and license header in all affected files +- [ ] I have added copyright and license headers, footers (for .md files) or files (for images) - [ ] I have performed a self-review of my changes - [ ] I have successfully tested my changes - [ ] I have added comments in the default values.yaml file with helm-docs syntax ('# -- ') if relevant for installation diff --git a/docs/consultation/consultation.md b/docs/consultation/consultation.md index 349f6675..62e220ce 100644 --- a/docs/consultation/consultation.md +++ b/docs/consultation/consultation.md @@ -112,4 +112,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC - SPDX-License-Identifier: Apache-2.0 - SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation -- Source URL: https://github.com/eclipse-tractusx/portal-iam \ No newline at end of file +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/consultation/workshop-20230927.md b/docs/consultation/workshop-20230927.md index e07bc178..0d47f474 100644 --- a/docs/consultation/workshop-20230927.md +++ b/docs/consultation/workshop-20230927.md @@ -6,7 +6,7 @@ ### Overall System Diagram -![Overall System Diagram](./img/overall-system.png) +![Overall System Diagram](/docs/static/overall-system.png) Portal IdP is formed by two Keycloak instances: @@ -17,7 +17,7 @@ Portal IdP is formed by two Keycloak instances: * Shared IdP * User management -![Portal IdP Workflow](./img/portal-idp.png) +![Portal IdP Workflow](/docs/static/portal-idp.png) The high level Auth/Authz workflow is: diff --git a/docs/static/2-factor-auth.png b/docs/static/2-factor-auth.png new file mode 100644 index 00000000..346de33c Binary files /dev/null and b/docs/static/2-factor-auth.png differ diff --git a/docs/static/2-factor-auth.png.license b/docs/static/2-factor-auth.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/2-factor-auth.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/add-idp.png b/docs/static/add-idp.png new file mode 100644 index 00000000..6789122d Binary files /dev/null and b/docs/static/add-idp.png differ diff --git a/docs/static/add-idp.png.license b/docs/static/add-idp.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/add-idp.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/add-provider-menu.png b/docs/static/add-provider-menu.png new file mode 100644 index 00000000..132f944d Binary files /dev/null and b/docs/static/add-provider-menu.png differ diff --git a/docs/static/add-provider-menu.png.license b/docs/static/add-provider-menu.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/add-provider-menu.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/auth-flow.png b/docs/static/auth-flow.png new file mode 100644 index 00000000..460b1cc7 Binary files /dev/null and b/docs/static/auth-flow.png differ diff --git a/docs/static/auth-flow.png.license b/docs/static/auth-flow.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/auth-flow.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/authentication-flow.png b/docs/static/authentication-flow.png new file mode 100644 index 00000000..5c2031d7 Binary files /dev/null and b/docs/static/authentication-flow.png differ diff --git a/docs/static/authentication-flow.png.license b/docs/static/authentication-flow.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/authentication-flow.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/authentication-protocol.png b/docs/static/authentication-protocol.png new file mode 100644 index 00000000..e279969e Binary files /dev/null and b/docs/static/authentication-protocol.png differ diff --git a/docs/static/authentication-protocol.png.license b/docs/static/authentication-protocol.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/authentication-protocol.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/bpdm-gate-overview.png b/docs/static/bpdm-gate-overview.png new file mode 100644 index 00000000..e13cebee Binary files /dev/null and b/docs/static/bpdm-gate-overview.png differ diff --git a/docs/static/bpdm-gate-overview.png.license b/docs/static/bpdm-gate-overview.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/bpdm-gate-overview.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/bpdm-pool-overview.png b/docs/static/bpdm-pool-overview.png new file mode 100644 index 00000000..11bc8b6d Binary files /dev/null and b/docs/static/bpdm-pool-overview.png differ diff --git a/docs/static/bpdm-pool.png.license b/docs/static/bpdm-pool.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/bpdm-pool.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/bpn.png b/docs/static/bpn.png new file mode 100644 index 00000000..555c9c35 Binary files /dev/null and b/docs/static/bpn.png differ diff --git a/docs/static/bpn.png.license b/docs/static/bpn.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/bpn.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/brute-force.png b/docs/static/brute-force.png new file mode 100644 index 00000000..4bec8c92 Binary files /dev/null and b/docs/static/brute-force.png differ diff --git a/docs/static/brute-force.png.license b/docs/static/brute-force.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/brute-force.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/client-authentication-concept.png b/docs/static/client-authentication-concept.png new file mode 100644 index 00000000..40aa7d9c Binary files /dev/null and b/docs/static/client-authentication-concept.png differ diff --git a/docs/static/client-authentication-concept.png.license b/docs/static/client-authentication-concept.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/client-authentication-concept.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/client-data.png b/docs/static/client-data.png new file mode 100644 index 00000000..96b338fa Binary files /dev/null and b/docs/static/client-data.png differ diff --git a/docs/static/client-data.png.license b/docs/static/client-data.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/client-data.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/client-roles.png b/docs/static/client-roles.png new file mode 100644 index 00000000..9762b379 Binary files /dev/null and b/docs/static/client-roles.png differ diff --git a/docs/static/client-roles.png.license b/docs/static/client-roles.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/client-roles.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/common-parameters.png b/docs/static/common-parameters.png new file mode 100644 index 00000000..93b03d2b Binary files /dev/null and b/docs/static/common-parameters.png differ diff --git a/docs/static/common-parameters.png.license b/docs/static/common-parameters.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/common-parameters.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/composite-roles.png b/docs/static/composite-roles.png new file mode 100644 index 00000000..0cd9823a Binary files /dev/null and b/docs/static/composite-roles.png differ diff --git a/docs/static/composite-roles.png.license b/docs/static/composite-roles.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/composite-roles.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/create-user.png b/docs/static/create-user.png new file mode 100644 index 00000000..d5501808 Binary files /dev/null and b/docs/static/create-user.png differ diff --git a/docs/static/create-user.png.license b/docs/static/create-user.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/create-user.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/event-config.png b/docs/static/event-config.png new file mode 100644 index 00000000..a178cd0a Binary files /dev/null and b/docs/static/event-config.png differ diff --git a/docs/static/event-config.png.license b/docs/static/event-config.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/event-config.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/first-login-flow.png b/docs/static/first-login-flow.png new file mode 100644 index 00000000..7aa4103f Binary files /dev/null and b/docs/static/first-login-flow.png differ diff --git a/docs/static/first-login-flow.png.license b/docs/static/first-login-flow.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/first-login-flow.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/identity-providers.png b/docs/static/identity-providers.png new file mode 100644 index 00000000..eba85e44 Binary files /dev/null and b/docs/static/identity-providers.png differ diff --git a/docs/static/identity-providers.png.license b/docs/static/identity-providers.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/identity-providers.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/import-external-idp-config.png b/docs/static/import-external-idp-config.png new file mode 100644 index 00000000..25ba26df Binary files /dev/null and b/docs/static/import-external-idp-config.png differ diff --git a/docs/static/import-external-idp-config.png.license b/docs/static/import-external-idp-config.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/import-external-idp-config.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/login-event-filter.png b/docs/static/login-event-filter.png new file mode 100644 index 00000000..8b8b0f3b Binary files /dev/null and b/docs/static/login-event-filter.png differ diff --git a/docs/static/login-event-filter.png.license b/docs/static/login-event-filter.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/login-event-filter.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/login-events.png b/docs/static/login-events.png new file mode 100644 index 00000000..7434b040 Binary files /dev/null and b/docs/static/login-events.png differ diff --git a/docs/static/login-events.png.license b/docs/static/login-events.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/login-events.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/managed-wallets-overview.png b/docs/static/managed-wallets-overview.png new file mode 100644 index 00000000..7ed9a970 Binary files /dev/null and b/docs/static/managed-wallets-overview.png differ diff --git a/docs/static/managed-wallets-overview.png.license b/docs/static/managed-wallets-overview.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/managed-wallets-overview.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/mappers.png b/docs/static/mappers.png new file mode 100644 index 00000000..5593f853 Binary files /dev/null and b/docs/static/mappers.png differ diff --git a/docs/static/mappers.png.license b/docs/static/mappers.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/mappers.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/new-flow.png b/docs/static/new-flow.png new file mode 100644 index 00000000..b82e9af8 Binary files /dev/null and b/docs/static/new-flow.png differ diff --git a/docs/static/new-flow.png.license b/docs/static/new-flow.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/new-flow.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/consultation/img/overall-system.png b/docs/static/overall-system.png similarity index 100% rename from docs/consultation/img/overall-system.png rename to docs/static/overall-system.png diff --git a/docs/consultation/img/overall-system.png.license b/docs/static/overall-system.png.license similarity index 77% rename from docs/consultation/img/overall-system.png.license rename to docs/static/overall-system.png.license index 237685b9..8bbb33d7 100644 --- a/docs/consultation/img/overall-system.png.license +++ b/docs/static/overall-system.png.license @@ -2,4 +2,5 @@ This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses - SPDX-License-Identifier: CC-BY-4.0 - SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation -- Source URL: https://github.com/eclipse-tractusx/portal-iam +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/password-policy.png b/docs/static/password-policy.png new file mode 100644 index 00000000..ec25ff64 Binary files /dev/null and b/docs/static/password-policy.png differ diff --git a/docs/static/password-policy.png.license b/docs/static/password-policy.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/password-policy.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/password-recovery.png b/docs/static/password-recovery.png new file mode 100644 index 00000000..ac5c42ce Binary files /dev/null and b/docs/static/password-recovery.png differ diff --git a/docs/static/password-recovery.png.license b/docs/static/password-recovery.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/password-recovery.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/portal-application-overview.png b/docs/static/portal-application-overview.png new file mode 100644 index 00000000..4c98f5a6 Binary files /dev/null and b/docs/static/portal-application-overview.png differ diff --git a/docs/static/portal-application-overview.png.license b/docs/static/portal-application-overview.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/portal-application-overview.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/consultation/img/portal-idp.png b/docs/static/portal-idp.png similarity index 100% rename from docs/consultation/img/portal-idp.png rename to docs/static/portal-idp.png diff --git a/docs/consultation/img/portal-idp.png.license b/docs/static/portal-idp.png.license similarity index 77% rename from docs/consultation/img/portal-idp.png.license rename to docs/static/portal-idp.png.license index 237685b9..8bbb33d7 100644 --- a/docs/consultation/img/portal-idp.png.license +++ b/docs/static/portal-idp.png.license @@ -2,4 +2,5 @@ This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses - SPDX-License-Identifier: CC-BY-4.0 - SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation -- Source URL: https://github.com/eclipse-tractusx/portal-iam +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/registration-application-overview.png b/docs/static/registration-application-overview.png new file mode 100644 index 00000000..de724d74 Binary files /dev/null and b/docs/static/registration-application-overview.png differ diff --git a/docs/static/registration-application-overview.png.license b/docs/static/registration-application-overview.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/registration-application-overview.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/required-authenticaction.png b/docs/static/required-authenticaction.png new file mode 100644 index 00000000..6a8407ea Binary files /dev/null and b/docs/static/required-authenticaction.png differ diff --git a/docs/static/required-authenticaction.png.license b/docs/static/required-authenticaction.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/required-authenticaction.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/roles-permissions.png b/docs/static/roles-permissions.png new file mode 100644 index 00000000..edc6eaca Binary files /dev/null and b/docs/static/roles-permissions.png differ diff --git a/docs/static/roles-permissions.png.license b/docs/static/roles-permissions.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/roles-permissions.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/save-events.png b/docs/static/save-events.png new file mode 100644 index 00000000..1ea69c66 Binary files /dev/null and b/docs/static/save-events.png differ diff --git a/docs/static/save-events.png.license b/docs/static/save-events.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/save-events.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/scenario1.png b/docs/static/scenario1.png new file mode 100644 index 00000000..47028834 Binary files /dev/null and b/docs/static/scenario1.png differ diff --git a/docs/static/scenario1.png.license b/docs/static/scenario1.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/scenario1.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/scenario2-1.png b/docs/static/scenario2-1.png new file mode 100644 index 00000000..669d7132 Binary files /dev/null and b/docs/static/scenario2-1.png differ diff --git a/docs/static/scenario2-1.png.license b/docs/static/scenario2-1.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/scenario2-1.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/scenario2.png b/docs/static/scenario2.png new file mode 100644 index 00000000..ae04d0b2 Binary files /dev/null and b/docs/static/scenario2.png differ diff --git a/docs/static/scenario2.png.license b/docs/static/scenario2.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/scenario2.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/technical-user-accounts-overview.png b/docs/static/technical-user-accounts-overview.png new file mode 100644 index 00000000..1f542bef Binary files /dev/null and b/docs/static/technical-user-accounts-overview.png differ diff --git a/docs/static/technical-user-accounts-overview.png.license b/docs/static/technical-user-accounts-overview.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/technical-user-accounts-overview.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/technical-user-overview.png b/docs/static/technical-user-overview.png new file mode 100644 index 00000000..febbdced Binary files /dev/null and b/docs/static/technical-user-overview.png differ diff --git a/docs/static/technical-user-overview.png.license b/docs/static/technical-user-overview.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/technical-user-overview.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/tokens.png b/docs/static/tokens.png new file mode 100644 index 00000000..707feb6f Binary files /dev/null and b/docs/static/tokens.png differ diff --git a/docs/static/tokens.png.license b/docs/static/tokens.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/tokens.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/static/users-view.png b/docs/static/users-view.png new file mode 100644 index 00000000..3a3faf4e Binary files /dev/null and b/docs/static/users-view.png differ diff --git a/docs/static/users-view.png.license b/docs/static/users-view.png.license new file mode 100644 index 00000000..8bbb33d7 --- /dev/null +++ b/docs/static/users-view.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + diff --git a/docs/technical documentation/00. External Identity Provider.md b/docs/technical documentation/00. External Identity Provider.md new file mode 100644 index 00000000..da3d5ed9 --- /dev/null +++ b/docs/technical documentation/00. External Identity Provider.md @@ -0,0 +1,50 @@ +# External Identity Provider + +For federated identities, external identity providers are needed. +To support the external identity provider configuration, a user interface flow [Technical Integration IdP](https://github.com/eclipse-tractusx/portal-assets/tree/v1.6.1/developer/02.%20Technical%20Integration/02.%20Identity%20Provider%20Management) is implement in the Portal with which company admins can create / configure the company IdP as external IdP. +For details, please follow the provided link. + +## How does the external IdP connection work? + +External company IdPs are getting similarly configured similarly to the sharedIdP which is configured for all companies using the Catena-X IdP as authentication provider. +The company idP is created as external IdP inside the "Identity Provider" menu of the central realm. + +![identityProviders](/docs/static/identity-providers.png) + +Keycloak does in general support a huge number of idp(s) - however for Catena-X social network IdPs as well as SAML connections are not planned to get supported. Instead all connections are considered as OIDC connections. + +![addProviderMenu](/docs/static/add-provider-menu.png) + +IdPs are created with the following parameter + +- Alias (unique name) +- Display Name (IdP display name in the login page) +- Metadata URL (metadata url of the external IdP for automatic configuration) + +![addIdp](/docs/static/add-idp.png) + +![importExternalIdpConfig](/docs/static/import-external-idp-config.png) + +To ensure that the auto user creation is disabled (important to not generate a out of sync mode between the Keycloak db and portal db) the "First Login Flow" need to get set to "Login without auto user creation" (customized theme create by CX consortia and part of the release package). + +![firstLoginFlow](/docs/static/first-login-flow.png) + +Last but not least the client id and secret of the external IdP is needed to establish the trust between both the IdPs. + +![client-data](/docs/static/client-data.png) + +After this generic settings are done, the idp is successfully configured. +Each IdP will get automatically (when created via endpoint - which is strongly suggested to ensure a in-sync state of the Keycloak and portal db) generate the necessary mappers. +IdP mappers are used to import OIDC ID/Access token claims into user attributes and user role mappings. + +![mappers](/docs/static/mappers.png) + +Individual mappers are possible, but not suggested. + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/01. Introduction.md b/docs/technical documentation/01. Introduction.md new file mode 100644 index 00000000..50b58332 --- /dev/null +++ b/docs/technical documentation/01. Introduction.md @@ -0,0 +1,22 @@ +## Identity & Access Management + +### As-Is Authentication Management + +Authentication Flow - User login to Catena-X + +![AuthenticationFlow](/docs/static/authentication-flow.png) + +\*(Schatten-) User: The „Schatten-User“ (shadow user) is defined as an empty User frame holding limited information. The actual user is managed in the respective Identity Provider. +The Schatten-User are always federated identities + +### Authentication Protocol - OpenID Connect (OIDC) + +![AuthenticationProtocol](/docs/static/authentication-protocol.png) + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/02. Generic Setup.md b/docs/technical documentation/02. Generic Setup.md new file mode 100644 index 00000000..d63a9a47 --- /dev/null +++ b/docs/technical documentation/02. Generic Setup.md @@ -0,0 +1,123 @@ +## Generic Setup + +### Identity Provider + +#### Requirement + +- [x] Identity Providers are configured on CX-Central Realm level only +- [x] Identity Providers are Azure Active Directory, WebEAM, SAP, Amazon,... +- [x] Default Protocol used is OIDC +- [x] Users getting authenticated by an identity provider should only be able to login to the CX Services if a user in Keycloak is available +- [ ] ... + +#### What's a Keycloak identity provider + +An Identity Broker is an intermediary service connecting service providers with identity providers. The identity broker creates a relationship with an external identity provider to use the provider’s identities to access the internal services the service provider exposes. + +From a user perspective, identity brokers provide a user-centric, centralized way to manage identities for security domains and realms. You can link an account with one or more identities from identity providers or create an account based on the identity information from them. + +An identity provider derives from a specific protocol used to authenticate and send authentication and authorization information to users. It can be: + +- A social provider such as Facebook, Google, or Twitter. +- A business partner whose users need to access your services. +- A cloud-based identity service you want to integrate. + +Typically, Keycloak bases identity providers on the following protocols: + +- SAML v2.0 +- OpenID Connect v1.0 ![Tag](https://img.shields.io/static/v1?label=&message=CATENA-X-Standard&color=green&style=flat) +- OAuth v2.0 + +#### Brokering overview + +When configuring Identity Providers in Keycloak, Keycloak does not force users to provide their credentials to authenticate in a specific realm. +Keycloak displays a list of identity providers from which they can authenticate. + +If you configure a default identity provider, Keycloak redirects users to the default provider. For Catena-X, this is not necessary. + +#### (Change) Identity Provider Display Name + +The Identity Provider display name can get changed by the operator without any negative impact. +The change should still only get executed if necessarily needed. The change is resulting into a new IdP Button Name on the application login side. + +#### Delete Identity Provider + +There are a few different scenarios where the deletion of a identity provider within Keycloak might be needed. + +- Company wants to move back to Shared CX IdP (currently not supported) +- Company is off-boarding from Catena-X +- Company is changing the company IdP internally (UI supported; no intervention by the platform operator needed) +- Identity Provider link to Shared IdP is not needed anymore (UI supported; no intervention by the platform operator needed) + +More details regarding the function flow of deleting IdP's can get found here: [Get there](https://github.com/eclipse-tractusx/portal-assets/blob/v1.6.1/docs/02.%20Technical%20Integration/02.%20Identity%20Provider%20Management/04.%20FAQ.md) + +### Realms + +> **Note** +> Realms don't get much detailed explained; since it is not planned that they are manually created; all realm related services are automated. + +#### Requirement + +- [x] Realm is created for each registration company +- [x] Realms are created inside the Shared IdP only; the Central IdP only holds the realms of the platform operator +- [x] A realm hold the user data of a company (kind of tenant management) +- [x] Roles and Groups are not managed on realm level +- [ ] ... + +#### Realm Emails + +Keycloak can send emails to users for several different scenario + +- to verify the user email address +- to recreate a password in case it was forgotten +- or when an administrator needs to receive notifications about a server event + +To enable Keycloak to send emails, SMTP server settings need to get configured by following steps: + +- Login to the respective Keycloak instance and open the relevant realm +- Click Realm Settings in the menu. +- Click the Email tab. +- Fill in the fields and toggle the switches as needed. + +> **Note** +> The email realm config is automatically taking place when a realm is getting created; no manual adjustments needed. However the config of the email service attributes is needed via the env. var files. + +###### Host + +SMTP server hostname used for sending emails. + +###### Port + +SMTP server port. + +###### From + +Address used for the From SMTP-Header for the emails sent. + +###### From Display Name + +Allows to configure a user friendly email address aliases (optional). If not set the plain From email address will be displayed in email clients. + +###### Reply To + +Reply To denotes the address used for the Reply-To SMTP-Header for the mails sent (optional). If not set the plain From email address will be used. + +###### Reply To Display Name + +Reply To Display Name allows to configure a user friendly email address aliases (optional). If not set the plain Reply To email address will be displayed. + +###### Envelope From + +Envelope From denotes the Bounce Address used for the Return-Path SMTP-Header for the mails sent (optional).Enable SSL and Enable StartTSLToggle one of these switches to ON to support sending emails for recovering usernames and passwords, especially if the SMTP server is on an external network. You will most likely need to change the Port to 465, the default port for SSL/TLS. + +###### Enable Authentication + +Set this to ON if your SMTP server requires authentication. When prompted, supply the Username and Password. + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/03. Clients.md b/docs/technical documentation/03. Clients.md new file mode 100644 index 00000000..bd57cc3d --- /dev/null +++ b/docs/technical documentation/03. Clients.md @@ -0,0 +1,81 @@ +## Clients + +### Overview Clients + +Clients are entities that can request Keycloak to authenticate a user. Most often, clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution. + +Clients can have 3 different client types + +- public (For client-side clients that perform browser logins. As it is not possible to ensure that secrets can be kept safe with client-side clients, it is important to restrict access by configuring correct redirect URIs) +- confidential (For server-side clients that perform browser logins and require client secrets when making an Access Token Request. This setting should be used for server-side applications) +- bearer-only (The application allows only bearer token requests. When turned on, this application cannot participate in browser logins) + +### Client Creation + +clients are created with the portal & marketplace services: + +- App Services +- Service Services + +Manual creation of clients is not expected/needed + +### Initial Client Load + +In the initial system deployment/data load provided by the catena-x migration script, the relevant core clients are included. + +### Client Authentication Concept + +** example DFT / SDE ** + +The DFT (Data Format Transformer) is planned to get offered as a data provider essential services, hosted/operated by 3rd party service providers. + +In the design of the authentication flow, it was analyzed which authentication flows are available and how do they differ. + +Two main scenarios are possible and shown in the picture below + +- One Central DFT Client Registration for all costumer +- Multiple Central DFT Client Registration, each customer one registration + +![ClientAuthenticationConcept](/docs/static/client-authentication-concept.png) + +In the chapter/details both scenarios are detailed. + +##### Scenario 1 - Only one DFT Client - one for all customer + +In the example of one DFT registrations for all customer, following tasks are necessary. + +Whenever a new customer is approaching a service provider for a DFT instance, the service provider needs to request the enhancement of the allowed redirect URIs from the central portal instance. + +Additionally, no additional effort is needed on the portal side. + +For the authentication the result would look the following: + +Below a picture is added with the user JWT token (used for authentication). Green highlighted the identical section and yellow highlighted the difference + +![Scenario1](/docs/static/scenario1.png) + +Summary: in this scenario the difference of user of company 1 and user of company 2 is only the organization and bpn tag. Everything else is identical and cant get used to ensure that users of company 1 are not able to access the dft instance of company 2. + +Security: MEDIUM + +##### Scenario 2 - Multiple DFT Clients - one for each customer + +Instead of Scenario 1 "one app registration for all tenants" - Scenario 2 is focusing on a tenant-specific authorization setup. With that, the operator of the app can distinguish the assigned roles on a tenant basis. In the following figure, you can see that there is a specific section of roles for each tenant. With this setup, a user can only access the tenant to which he actually has roles assigned. If the user gets a link to a tenant of a different customer he will get a not authorized error. There is no Catena-X specific check based on the bpn necessary. + +![Scenario2](/docs/static/scenario2.png) + +Summary: the user of company 1 will only retrieve jwt token roles/client attributes for the DFT Instance 1. The user of company 2 only receives a JWT token roles/client attributes for DFT instance 2. In case the user is trying to login to another DFT Instance, a JWT token will get created, but the section + +![Scenario2](/docs/static/scenario2-1.png) + +..wont be existing + +Security: HIGH + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/04 User Management.md b/docs/technical documentation/04 User Management.md new file mode 100644 index 00000000..90f24def --- /dev/null +++ b/docs/technical documentation/04 User Management.md @@ -0,0 +1,94 @@ +## User Management + +We differentiate between real users and technical users (aka service accounts). +Both scenarios are completely automated / FE supported. There is no necessarily to setup/configure users in Keycloak directly. + +Even more, it should get prohibited to create users via the Keycloak admin console; reason: those users would be missing in the portal db since there is no synchronization back to the portal db. This would result into an internal service issue. +When using the available services for real and technical user creation; the issue wont appear since portal will create first of all the relevant user accounts in the portal db and afterwards create the same in Keycloak. +With help of the portal db table iam_users; the user id in Keycloak central IdP (user_entity_id) and the user id inside the portal (company_user_id) are linked. +For service accounts the mapper is the service account clientId. + + +### Technical User + +For the type of technical (non-human) users, service accounts are to be used. +Service accounts differ from normal user accounts in multiple ways: + +- They don't have a password and can't be used for browser-based sign-in. +- They're created and managed as a user that belongs to a client. +- How to setup technical user authentication +- The service account should have it's own client. + + Each OIDC client has a built-in service account which allows it to obtain an access token. This is covered in the OAuth 2.0 specification under Client Credentials Grant. To use this feature the Access Type of your client is set to confidential. + + +#### Role Management + +The technical user relevant roles are managed within a shadow client called "technical-user-management". + +All composite roles available for technical user creation inside the portal are configured in this area. + +Additionally, the role need to be available inside the portal db - user_roles. + + +### User Attributes + +All users can get specific user attributes added - currently the following attributes are supported / implemented + +- bpn-mapper +- username-mapper + + +#### bpn-mapper + +The Business Partner Number (BPN) is a verified company credential which is getting added as attribute to each user inside the network. + +The bpn provides an extended user authentication possibility. + + +How is the attribute added to the user + +- Option1: With the registration approval: with the registration, a user is invited without the company/bpn connection. The actual confirmation of user / BPN mapping will only take place with the registration approval => if the company registration is getting approved, a backend service is calling the function to add the company BPN to the respective user +- Option 2: Automatically added with the user invite/creation: the IT Administrator is adding one or multiple users to the CX network. By doing so, the user accounts get created => as part of this flow, the newly created user(s) should get a user attribute added which is the same as the Company BPN from the table "company" +- Option 3: Manual added, by permission (via the user management permission "add user"): by opening the user admin account inside the portal, the administrator can add another BPN to the user account. Currently without any limitations. However there is the plan to limit the functionality and to restrict the BPNs which can get selected / added by the admin + +#### username-mapper + +Is handling the username created for each user account inside the central IdP. +{idpalias}+uuid + + +### View Users in a realm + +> **_NOTE:_** +> In general users should not get created via the IdP admin console - it will result into a de-sync of the portal db and Keycloak db. Also necessary security validations and connections will be missing. We strongly suggest to use the build api(s) only as well as the UI supported by the portal. + +To look up all users created in Keycloak under a specific realm or inside the central realm, click on Users in the left menu bar. + +![UsersView](/docs/static/users-view.png) + +To display the users; click on "View all users" or use the search box to find a specific user via full name, last name or email address. + + +### Create New User + +> **_NOTE:_** +> In general users and user connections should get viewed inside the portal db. + +To create an user click on Users in the left menu bar. +As soon as the page is reached, select the Add User on the top right of the user table. + +Required mandatory field is Username only. However in Catena-X we also set the first name, last name, email as well as some user attributes. +Details regarding the attributes can get found under the link [attribute details](./04.%20User%20Management.md) + +![CreateUser](/docs/static/create-user.png) + +Details regarding the attributes can get found under the link [attribute details](./04.%20User%20Management.md) + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/05. Authentication Configuration.md b/docs/technical documentation/05. Authentication Configuration.md new file mode 100644 index 00000000..0501356a --- /dev/null +++ b/docs/technical documentation/05. Authentication Configuration.md @@ -0,0 +1,11 @@ +## Authentication Configuration + +---- will get added ---- + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/06. Roles & Rights Concept.md b/docs/technical documentation/06. Roles & Rights Concept.md new file mode 100644 index 00000000..383faca4 --- /dev/null +++ b/docs/technical documentation/06. Roles & Rights Concept.md @@ -0,0 +1,190 @@ +## 1. General details + +### 1.1 Scope and binding force of the document + +The Roles & Rights concept is part of the System Implementation for Catena-X. It specifies the roles, authorizations and controls which must be implemented in Catena-X. +The Roles & Rights Concept aims at providing a high-level description with respect to the planning and implementation of roles and rights in the context of Catena-X. The Roles & Rights concept is supposed to define required functions, structures and basic principles. Therefore only an illustrative description of specific roles and associated rights is provided. This concept document is high level description of the implemented roles and rights. However, the included roles and rights give a sufficient representation of the relevant functions, structures and principles. + +### 1.2 Affected application + +Registration // Portal // Managed Wallet // DFT // BPDM + +### 1.3 Referenced documents + +n/a + +## 2. Authorization structure and role model + +This chapter explains the business, organizational, and technical principles of the role and authorization definition, thereby illustrating the relationship between business function and authorization structure. The objective is to make the actual authorizations and authorization assignments granted in the new Catena-X solution verifiable against the business, technical, and organizational specifications, specified in this document. + +### 2.1 Underlying business processes and roles: + +n/a + +### 2.2 Basic principles + +n/a + +### 2.3 Individual privileges and authorization framework + +n/a + +### 2.4 Role definition + +In the concept of the roles and rights management we are differentiating between roles and permissions. + +Permissions are the lowest level which a user can have. Several permissions are collected to a role. + +The assignment of rights to an actual user is happening on the role level itself. + +It is suggested to setup naming convention for roles and permissions to ensure that they can get clearly defined. + +On the CX Portal side the conventions are setup the following \*please note that this is not mandatorily needed to be followed by 3rd Party Providers + + Naming Convention: + + - Permissions + - always lowercase + - no spaces, only use underscore + - task/role needs to be clearly understandable + - don't use any "Umlaute" (special character) such as: ä, ü, ö + - a permission can get assigned to several roles, but one is the minimum role to which it need to be assigned + + + Roles: + + - capital letters to be used for 1st character + - spaces are allowed + - role should be identifiable + - don't use any "Umlaute" (special character) such as: ä, ü, ö + - a role needs as a minimum 1 permission assigned to it + +### 2.5 Role/Permission Matrix + +This role concept covers all roles related to + +- Registration/Onboarding Process Roles +- Portal Roles + +![RolePermissions](/docs/static/roles-permissions.png) + +#### 2.5.1 Technical User (portal internal) + +![TechnicalUser](/docs/static/technical-user-overview.png) + +#### 2.5.2 Registration Application + +![RegistrationApplication](/docs/static/registration-application-overview.png) + +#### 2.5.3 Portal Application + +![PortalApplication](/docs/static/portal-application-overview.png) + +#### 2.5.3b Technical User Accounts + +![TechnicalUserAccounts](/docs/static/technical-user-accounts-overview.png) + +#### 2.5.4 Managed Wallets + +![ManagedWallets](/docs/static/managed-wallets-overview.png) +*depending on the need, technical user will have a subset of the selected roles in the role table "Managed Wallets". + +For example: + +- SD Hub: view and update wallets +- Portal: view and add wallets +- EDC Extension: view and update wallet (technical user needs BPN as user attribute) + +#### 2.5.5 BPDM + +For the BPDM Pools READ rights are given to all CX members. + +WRITE into the POOL "add_company_data" is only allowed for the platform owner/ operator and (if integrated) possible service providers of BPDM cleanup services. + +![BPDM](/docs/static/bpdm-pool.png) +* Technical User is the corresponding bpdm data provider (operator or/and service provider; no platform customer) + +#### 2.5.6 BPDM Gate + +![BPDMGate](/docs/static/bpdm-gate-overview.png) + +#### 2.5.7 BPDMShare + +no roles +Note regarding the role setup in context of CPLP-121 - Registration App: Invite additional Registration Participants (FE/BE) CLOSED : + +- the inviting party needs to have the role "manage users" to be able to create users +- the invited party needs to have the role "view users" to be able to see the own roles in the upper right corner of the registration portal + Note regarding the role setup in context of CPLP-225 - Registration Service - Add Users: Roles to be fetched from Keycloak CLOSED : + +The user needs to have the role "view clients" to be able to see the available composite roles in the dropdown. Also, the user needs to have the role "view users" to be able to see the own composite roles in the upper right corner of the registration portal. + +Long term solution: a concept needs to be defined and implemented for technical identities (backend services which gather the composite roles should be executed with technical users, not require the user to have elevated rights). + +### 2.6 Segregation of duties + +Segregation of duties is the concept of having more than one person or role required to complete a task. Currently there is no such scenario inside the portal existing. + +## 3. Global subjects + +This chapter explains how the Catena-X Platform is embedded into the Business Partner application landscape and what infrastructure components are connected to it in terms of authorization management. Furthermore, technical restrictions, naming conventions, audit logging and the authentication mechanisms are outlined in more detail. + +### 3.1 Authorization management connections + +Authorization management is handled in CX central IdP. + +### 3.2 Used infrastructure components + +- + +### 3.3 Privileged and technical user accounts + +Technical users are used for backend to backend connections. Inside CX but also outbound between member companies and CX components. + +E.g. Central registry connection by a third party app. + +### 3.4 Technical restrictions + +For a detailed description of how the internal security system works please refer to Security Concept. In terms of the Catena-X Platform, this approach brings the following technical restrictions: + +A new login is required for user rights changes to take effect +The fact that the rights for a particular user are only read at user login and then cached for the session implicates, that changes to rights can only take effect after a new user login. + +### 3.5 Logging the use + +Logging actions that can lead to granting or revocation of authorizations must observe the legal privacy specifications. Access to the logs is restricted. This is allowed only if there is legitimate interest and if it is according to the legal regulations for privacy. + +For the Catena-X Platform, there are three types of logging the use: + +System internal audit history + +System external monitoring system + +System technical server logs + +Internal audit history, an on screen audit record is available for key screens. This functionality is restricted to particular roles (see section 2.5). The following information can be viewed tabular within the System: + +.. + +All internal audit and access logs are saved ???. The retention period for audit history is 7 years. After this period the audit history can be deleted, however this is not mandatory in legal terms. + +Finally, each infrastructure component and all surrounding systems have their own logging solutions in use. This includes the logging of grants and revoked of user access rights in the central BMW access management system. However, details on these technical logging solutions are out of scope for the Roles & Rights concept. + +## 4. Authorization procedure + +User permission / access withdrawal are possible via + +- Company IT Admin is able to withdraw user rights/permissions +- Company IT Admin can delete company users under the same org +- Company User can delete his/her own user account +- App provider can withdraw app usage for a company, but not for a single user + +## 5. Appendix + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/07. Password Policy.md b/docs/technical documentation/07. Password Policy.md new file mode 100644 index 00000000..144b321a --- /dev/null +++ b/docs/technical documentation/07. Password Policy.md @@ -0,0 +1,124 @@ +# Password Policy + +## Password Policy + +Password Policies are restrictions and/or requirements that a user must follow to ensure that their password is strong/secure. +In Keycloak, password policies are set per realm. + +Requirement + +- [ ] Default Password Policies are needed for every realm - the policies are set by Catena-X and identical for all realms +- [ ] Password refresh every 90 days +- [ ] Password length 15+ digits +- [ ] Password characters: letters + minimum 1 number is mandatory +- [ ] Password shouldn't be the same as the username or email +- [ ] If the Password is getting reset by the user and is not fitting the password policies, a error message with a detailed error code will get shown + + +#### How to configure Password Policies + +Open Keycloak admin page, go to "Authentication" and open the "Password Policy" tab. +Click on the Add policy … to see the list of available password policies. + +![PasswordPolicy](/docs/static/password-policy.png) + +Select the relevant policy and set the policy value by adding the relevant number. Important: only numbers are to be added, no letters. +After saving the policy, Keycloak login enforces the policy for new users. Existing users can still login with their old password, but as soon as a password change request is getting triggered the new policies will take affect. + +Blacklisting passwords is possible via UTF-8 file, for Catena-X no blacklisting is planned so far. + + +#### Implementation + +Password Policies are auto set (as per the definition mentioned above) for each company tenant. +With the new creation of an company tenant; the password policies are automatically configured for the respective realm inside the sharedIdP. + +##Password Reset + +If Password reset is enabled, users are able to reset their credentials if they forget their password or lose their OTP generator. + +Requirement + +- [ ] Forgot Password option should be available for all users using Shared IdP +- [ ] New Password needs to get validated against the configured Password Policies +- [ ] Config needs to get automatically set whenever a new realm is getting created + +#### How to configure Password Recovery + +Go to the Realm Settings left menu item, and click on the Login tab. Switch on the Forgot Password switch. + +![PasswordRecovery](/docs/static/password-recovery.png) + +The new password will get send via email. + +The email text is fully configurable. How: extend or edit the theme associated with it. + +When the user clicks on the email link, they will be asked to update their password, and, if they have an OTP generator set up, they will also be asked to reconfigure this as well. Depending on the security requirements of your organization you may not want users to be able to reset their OTP generator through email. You can change this behavior by going to the Authentication left menu item, clicking on the Flows tab, and selecting the Reset Credentials flow. + + +#### Implementation + +tbd + + +## 2-Factor-Auth + +Levels of Authentication + +- Level 0: Authentication by username and password only. No 2-factor-auth. +- Level 1: Authentication by username and password; plus additionally 2-factor-auth via Keycloak OTP +- Level 2: Authentication by username and password; plus additionally 2-factor-auth via configured webauth method + +![2factorAuth](/docs/static/2-factor-auth.png) + + +#### Setup for Catena-X + +Keycloak 2-Factor-Auth is suggested for all users/identities which are managed by Catena-X and not federated by any company identity management system. + + +##### Config for the Master Realm + +The Master realm, holding the admin accounts, is configured to + +- Each User needs to mandatorily configure OTP +- Each User needs to mandatorily update the password after the first login +- Password policies as per chapter PasswordPolicies need to get followed + + +##### Config for the Catena-X Realm + +tbd + +##### Config for the Company Spec. Realm + +The Shared Company realm, holding the user accounts for the company, is configured as following + +- Each User needs to mandatorily configure OTP +- Each User needs to mandatorily update the password after the first login +- Password policies as per chapter PasswordPolicies need to get followed + + +#### How to Setup - Yubikey as 2-Fact-Auth + +The IdP, where the user is stored/created (for SharedIdP Companies its the SharedIdP; for CX Operators its the CentralIdP as well as the SharedIdP) an authentication flow need to get configured. + +##### #1 Create New Auth Flow as shown below + +![NewFlow](/docs/static/new-flow.png) + +##### #2 Set the Auth Flow as browser flow + +![AuthFlow](/docs/static/auth-flow.png) + +##### #3 Update the Required Actions + +![RequiredAuthentication](/docs/static/required-authentication.png) + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/08. Email Configuration.md b/docs/technical documentation/08. Email Configuration.md new file mode 100644 index 00000000..d4d77925 --- /dev/null +++ b/docs/technical documentation/08. Email Configuration.md @@ -0,0 +1,72 @@ +# IdP Email Configuration + +## Requirement + +tbd - setup will be needed + + +## How to configuring email for a realm + +Keycloak can send emails to users for several different scenario + +- to verify the user email address +- to recreate a password in case it was forgotten +- or when an administrator needs to receive notifications about a server event + +To enable Keycloak to send emails, SMTP server settings need to get configured by following steps: + +- Login to the respective Keycloak instance and open the relevant realm +- Click Realm Settings in the menu. +- Click the Email tab. +- Fill in the fields and toggle the switches as needed. + +###### Host + +SMTP server hostname used for sending emails. + +###### Port + +SMTP server port. + +###### From + +Address used for the From SMTP-Header for the emails sent. + +###### From Display Name + +Allows to configure a user friendly email address aliases (optional). If not set the plain From email address will be displayed in email clients. + +###### Reply To + +Reply To denotes the address used for the Reply-To SMTP-Header for the mails sent (optional). If not set the plain From email address will be used. + +###### Reply To Display Name + +Reply To Display Name allows to configure a user friendly email address aliases (optional). If not set the plain Reply To email address will be displayed. + +###### Envelope From + +Envelope From denotes the Bounce Address used for the Return-Path SMTP-Header for the mails sent (optional).Enable SSL and Enable StartTSLToggle one of these switches to ON to support sending emails for recovering usernames and passwords, especially if the SMTP server is on an external network. You will most likely need to change the Port to 465, the default port for SSL/TLS. + +###### Enable Authentication + +Set this to ON if your SMTP server requires authentication. When prompted, supply the Username and Password. + +#### Catena-X Implementation + +smtp-host: smtp.office365.com +smtp-port: 587 +Enable StartTLS +Enable Authentication +visible in https://catenaxdev003akssrv.germanywestcentral.cloudapp.azure.com/iamcentralidp/auth/admin/master/console/#/realms/CX-Central/smtp-settings +it's mandatory the 'from' email-address and the smtp-username used to authenticate with the office365 mailing-service are identical. Therefor Notifications@catena-x.net is configured as email address. +This can get changed (if necessary) if a new login/account with the respective email is created. + + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/09. Event Logging.md b/docs/technical documentation/09. Event Logging.md new file mode 100644 index 00000000..ffac182c --- /dev/null +++ b/docs/technical documentation/09. Event Logging.md @@ -0,0 +1,153 @@ +# Event Logging + +## Requirement + +- [ ] Keycloak needs to log for each realm the login calls, logout, unsuccessful logins, changes of Keycloak configs +- [ ] Date and time should get logged as well as the user which did the change +- [ ] Logs should not show any passwords in clear text +- [ ] Usernames should not show up in clear text, but need to be traceable +- [ ] When a new realm gets created, the log configuration needs to get configured automatically as per the requirement +- [ ] Log retention period 90 days + +## Keycloak events + +Keycloak has two kinds of events: + +- login events and +- admin events + +Login events are emitted every time a user-related action around authentication is executed, e.g. login, logout, code-to-token exchanges, registrations, etc. Also errors of these actions are emitted as an event. The event itself then contains some useful information about the action and the corresponding user and/or client. Admin events are emitted on every change of a resource via the Admin-API, no matter if via the web console, REST api, CLI, etc. + +It is possible to enable the Keycloak db to store the events. However this is not recommended, since the login events DB table is hardly indexed, the admin events table besides the PK not at all and querying lots of entries will likely slow down the system. Also an important information regarding that: login event retention time can get configured; admin events retention time can't. + +Keycloak has a default events listener (called jboss-logging) in each realm configured. When there is e.g. an error during a login attempt, this error event will be logged with log level WARN. + +Successful events will be logged with level DEBUG and the root log level of the whole Keycloak server is set to INFO. With this setting, the SUCCESS-events won’t occur in the logs, only the ERROR-events will. + +## Configure Logging + +##### Keycloak Admin UI/DB + +Login events occur for things like when a user logs in successfully, when somebody enters in a bad password, or when a user account is updated. Every single event that happens to a user can be recorded and viewed. By default, no events are stored or viewed in the Admin Console. Only error events are logged to the console and the server’s log file. To start persisting you’ll need to enable storage. Go to the Events left menu item and select the Config tab. + +###### Event Configuration + +![EventConfiguration](/docs/static/event-config.png) + +To start storing events you’ll need to turn the Save Events switch to on under the Login Events Settings. + +###### Save Events + +![SaveEvents](/docs/static/save-events.png) + +The Saved Types field allows you to specify which event types you want to store in the event store. The Clear events button allows you to delete all the events in the database. The Expiration field allows you to specify how long you want to keep events stored. Once you’ve enabled storage of login events and decided on your settings, don’t forget to click the Save button on the bottom of this page. + +To view events, go to the Login Events tab. + +###### Login Events + +![LoginEvents](/docs/static/login-events.png) + +As you can see, there’s a lot of information stored and, if you are storing every event, there are a lot of events stored for each login action. The Filter button on this page allows you to filter which events you are actually interested in. + +###### Login Event Filter + +![LoginEventFilter](/docs/static/login-event-filter.png) + +In this screenshot, we’re filtering only Login events. Clicking the Update button runs the filter. + +###### Event Types + +Login events: + +- Login - A user has logged in. +- Register - A user has registered. +- Logout - A user has logged out. +- Code to Token - An application/client has exchanged a code for a token. +- Refresh Token - An application/client has refreshed a token. + +Account events: + +- Social Link - An account has been linked to a social provider. +- Remove Social Link - A social provider has been removed from an account. +- Update Email - The email address for an account has changed. +- Update Profile - The profile for an account has changed. +- Send Password Reset - A password reset email has been sent. +- Update Password - The password for an account has changed. +- Update TOTP - The TOTP settings for an account have changed. +- Remove TOTP - TOTP has been removed from an account. +- Send Verify Email - An email verification email has been sent. +- Verify Email - The email address for an account has been verified. + +For all events there is a corresponding error event. + + +##### Log Files + +Per default Keycloak logs are configured to only log on INFO level, to get a detailed logging, the log level need to get updated. + +2 options are available to adjust the logging level in the logs: + + Option1: Change the log level of the org.keycloak.events category logger + With this approach, you add an entry in the logging subsystem of the underlying Wildfly configuration. The new entry tells the logging subsystem to print all log messages from the package org.keycloak.events with DEBUG level and above to the log output: + + /subsystem=logging/logger=org.keycloak.events/:add(category=org.keycloak.events,level=DEBUG) + + + Option2: Configure the jboss-logging listener to log on other levels + As per default, there is no eventsListener SPI config in the Keycloak server configuration. The default behaviour for the jboss-logging events listener is the one which is implemented in the code. To be able to change the configuration of the jboss-logging listener, you’ll have to create the proper SPI node in the keycloak-server subsystem first, then add the desired log levels. + + /subsystem=keycloak-server/spi=eventsListener:add + /subsystem=keycloak-server/spi=eventsListener/provider=jboss-logging:add(enabled=true) + /subsystem=keycloak-server/spi=eventsListener/provider=jboss-logging:write-attribute(name=properties.success-level,value=info) + /subsystem=keycloak-server/spi=eventsListener/provider=jboss-logging:write-attribute(name=properties.error-level,value=warn) + Now the SUCCESS-events will occur in the log output with level INFO, as soon as they are emitted by Keycloak. + + +## Event Listener + +Event listeners listen for events and perform an action based on that event. There are two built-in listeners that come with Keycloak: Logging Event Listener and Email Event Listener. +The Logging Event Listener writes to a log file whenever an error event occurs and is enabled by default. Here’s an example log message: + +11:36:09,965 WARN [org.Keycloak.events] (default task-51) type=LOGIN_ERROR, realmId=master, +clientId=myapp, +userId=19aeb848-96fc-44f6-b0a3-59a17570d374, ipAddress=127.0.0.1, +error=invalid_user_credentials, auth_method=openid-connect, auth_type=code, +redirect_uri=http://localhost:8180/myapp, +code_id=b669da14-cdbb-41d0-b055-0810a0334607, username=admin + +This logging is very useful if you want to use a tool like Fail2Ban to detect if there is a hacker bot somewhere that is trying to guess user passwords. You can parse the log file for LOGIN_ERROR and pull out the IP Address. Then feed this information into Fail2Ban so that it can help prevent attacks. + +The Email Event Listener sends an email to the user’s account when an event occurs. The Email Event Listener only supports the following events at the moment: + +- Login Error +- Update Password +- Update TOTP +- Remove TOTP + + +To enable the Email Listener go to the Config tab and click on the Event Listeners field. This will show a drop down list box where you can select email. +You can exclude one or more events by editing the standalone.xml, standalone-ha.xml, or domain.xml that comes with your distribution and adding for example: + + + + + + + + + + + + + + + + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/10. Generic Security.md b/docs/technical documentation/10. Generic Security.md new file mode 100644 index 00000000..6b01dda2 --- /dev/null +++ b/docs/technical documentation/10. Generic Security.md @@ -0,0 +1,132 @@ +## Security Generic + +### Host + +Keycloak uses the public hostname in several ways, such as within token issuer fields and URLs in password reset emails. + +By default, the hostname derives from the request header. No validation exists to ensure a hostname is valid. Therefor its suggested to use a load balancer, or proxy, with Keycloak to prevent invalid host headers. + +The hostname’s Service Provider Interface (SPI) provides a way to configure the hostname for requests. You can use this built-in provider to set a fixed URL for frontend requests while allowing backend requests based on the request URI. If the built-in provider does not have the required capability, you can develop a customized provider. + + +### Bruce Force Detection + +A brute force attack happens when an attacker is trying to guess a user’s password multiple times. Keycloak has some limited brute force detection capabilities. If turned on, a user account will be temporarily disabled if a threshold of login failures is reached. To enable this feature go to the Realm Settings left menu item, click on the Security Defenses tab, then additional go to the Brute Force Detection sub-tab. + +When an attack is detected, permanent or temporary lockout can get configured. + +Permanent lockout disables a user account until an administrator re-enables it. Temporary lockout disables a user account for a specific period of time. The time period that the account is disabled increases as the attack continues. + +When a user is temporarily locked and attempts to log in, {project_name} displays the default Invalid username or password error message. This message is the same error message as the message displayed for an invalid username or invalid password to ensure the attacker is unaware the account is disabled. + +Details: https://www.keycloak.org/docs/latest/server_admin/index.html#password-guess-brute-force-attacks + + +Config: + +1. Click Realm Settings in the menu +2. Click the Security Defenses tab. +3. Click the Brute Force Detection tab. + +Brute force detection + +![BruteForce](/docs/static/brute-force.png) + + +Common Parameters + +![CommonParameters](/docs/static/common-parameters.png) + + +#### Catena-X configuration + +##### Preventing automated attacks + +- Lock after 10 subsequent login failures +- 1 second between failures (too quick for a human) +- Lock remains active for ~5 min + +##### Preventing manual attacks + +- Lock after 10 subsequent login failures +- Sliding window of 12 hours +- Lock remains active for ~ 45 min + + +### Clickjacking + +Clickjacking is a technique of tricking users into clicking on a user interface element different from what users perceive. A malicious site loads the target site in a transparent iFrame, overlaid on top of a set of dummy buttons placed directly under important buttons on the target site. When a user clicks a visible button, they are clicking a button on the hidden page. An attacker can steal a user’s authentication credentials and access their resources by using this method. + +By default, every response by {project_name} sets some specific browser headers that can prevent this from happening. Specifically, it sets X-FRAME_OPTIONS and Content-Security-Policy. You should take a look at the definition of both of these headers as there is a lot of fine-grain browser access you can control. +Procedure + +In the Admin Console, you can specify the values of the X-FRAME_OPTIONS and Content-Security-Policy headers. + +1. Click the Realm Settings menu item. +2. Click the Security Defenses tab. + Security Defenses + +By default, Keycloak sets up a same-origin policy for iframes. + + +### Open redirections + +An open redirector is an endpoint using a parameter to automatically redirect a user agent to the location specified by the parameter value without validation. An attacker can use the end-user authorization endpoint and the redirect URI parameter to use the authorization server as an open redirector, using a user’s trust in an authorization server to launch a phishing attack. + +Keycloak requires that all registered applications and clients register at least one redirection URI pattern. When a client requests that Keycloak performs a redirect, Keycloak checks the redirect URI against the list of valid registered URI patterns. Clients and applications must register as specific a URI pattern as possible to mitigate open redirector attacks. + + +### Compromised Authorization code + +For the OIDC Auth Code Flow, Keycloak generates a cryptographically strong random value for its authorization codes. An authorization code is used only once to obtain an access token. + +On the timeouts page in the Admin Console, you can specify the length of time an authorization code is valid. Its possible to configure the length of time for a client to request a token from the code. + +You can also defend against leaked authorization codes by applying Proof Key for Code Exchange (PKCE) to clients. + +-- not yet considered in CX -- + + +### Compromised access and refresh tokens + +Keycloak includes several actions to prevent malicious actors from stealing access tokens and refresh tokens. The crucial action is to enforce SSL/HTTPS communication between {project_name} and its clients and applications. {project_name} does not enable SSL by default. + +Another action to mitigate damage from leaked access tokens is to shorten the token’s lifespans. You can specify token lifespans within the Realm Setting → Token. Short lifespans for access tokens force clients and applications to refresh their access tokens after a short time. If an admin detects a leak, the admin can log out all user sessions to invalidate these refresh tokens or set up a revocation policy. + +In the current project phase, we will proceed with the default values for the token lifespans + +![Tokens](/docs/static/tokens.png) + + +### CSRF attack + +A Cross-site request forgery (CSRF) attack uses HTTP requests from users that websites have already authenticated. Any site using cookie-based authentication is vulnerable to CSRF attacks. You can mitigate these attacks by matching a state cookie against a posted form or query parameter. + +The OAuth 2.0 login specification requires that a state cookie matches against a transmitted state parameter. {project_name} fully implements this part of the specification, so all logins are protected. + +The {project_name} Admin Console is a JavaScript/HTML5 application that makes REST calls to the backend {project_name} admin REST API. These calls all require bearer token authentication and consist of JavaScript Ajax calls, so CSRF is impossible. You can configure the admin REST API to validate the CORS origins. + +The user account management section in {project_name} can be vulnerable to CSRF. To prevent CSRF attacks, {project_name} sets a state cookie and embeds the value of this cookie in hidden form fields or query parameters within action links. {project_name} checks the query/form parameter against the state cookie to verify that the user makes the call. + + +### Limiting Scope - Client Token + +By default, new client applications have unlimited role scope mappings. Every access token for that client contains all permissions that the user has. If an attacker compromises the client and obtains the client’s access tokens, each system that the user can access is compromised. + +Limit the roles of an access token by using the Scope menu for each client. Alternatively, you can set role scope mappings at the Client Scope level and assign Client Scopes to your client by using the Client Scope menu. + +For any clients in CX, the scope is limited to the client scope. + + +### Client Policies + +tbd + + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/11. FAQ.md b/docs/technical documentation/11. FAQ.md new file mode 100644 index 00000000..6f6032e0 --- /dev/null +++ b/docs/technical documentation/11. FAQ.md @@ -0,0 +1,192 @@ +# FAQ + +## How to crete new roles + +Before creating new roles, check once for which level/purpose the role is needed + +1. Company Role +2. Portal Role +3. App Role +4. Technical User Role + +### Company Role(s) + +To add a new company role, a couple of steps need to get followed. +Different to Portal/App/Technical User Roles, it is not needed to do any update inside the IdP. + +DB Table Changes: + +- add new company role inside the table company_roles +- if the new company role should be selectable for company registrations, set the role inside table company_role_registration_data to "true"; otherwise "false" +- add description of the new company role inside table company_role_descriptions +- create a new user role collection inside user_role_collections to define selectable user roles for the company role +- add description of the new collection inside table user_role_collection_descriptions +- map user roles to the new created collection via table user_role_assigned_collections +- connect the new company role with the new role collection via "company_role_assigned_role_collections" +- new or existing agreements to be linked to the new company role via table "agreement_assigned_company_roles" + +Additionally needed: + +- create migration +- update "version_upgrade" details [open the file](https://github.com/eclipse-tractusx/portal-assets/blob/v1.6.1/developer/Technical%20Documentation/Version%20Upgrade/portal-upgrade-details.md) +- update Roles&Rights Matrix + +### Portal Role(s) + +Portal roles can get added easily if following steps are considered/followed. + +1. Create the roles inside keycloak - central idp; realm: CX-Central inside the respective client + +- open the client via the left side menu **Clients** +- select the respective client (Cl2-CX-Portal or Cl1-CX-Registration) +- Open the tab **Roles** +- And click "Add" on the right hand side +- Enter the respective role name (keep in mind the role naming conversation) +- Click **"Save"** + +To transform the created "role" to an actual role, since currently its a single permission only; click on **Composite Roles** "ON". + + ![CompositeRoles](/docs/static/composite-roles.png) + + Afterwards select the respective permissions which should get collected under the new created role/composite role by selecting the client in which the relevant permissions are located. + Note: permissions of multiple clients can get assigned to one composite role without any troubles/issues. + + ![ClientRoles](/docs/static/client-roles.png) + +2. Create the same role inside the portal db (either via a delta migration job) or via sql. + + For the scenario of sql, the relevant sql can get found below: + + 1st create the role + + INSERT INTO portal.user_roles + (id, user_role, offer_id, last_editor_id) + VALUES ('{uuid}', '{user role name}', '{offer.id of portal or registration}', '{operator user uuid}'); + +2nd add role description in german and english + + INSERT INTO portal.user_role_descriptions + (user_role_id, language_short_name, description) + VALUES + ('(user_roles.id)', '{de}', '{description}'), + ('(user_roles.id)', '{en}', '{description}'); + +3rd connect role with company role collection + + INSERT INTO portal.user_role_assigned_collections + (user_role_id, user_role_collection_id) + VALUES ('{user_roles.id}', '{user_role_collections.id}'); + +3. Update keycloak base image + +...description needed by @evelyn + +4. Update documentation + +- [Roles&Rights Matrix](/docs/technical%20documentation/06.%20Roles%20&%20Rights%20Concept.md#253-portal-application) + +- Roles&Rights Matrix + https://github.com/eclipse-tractusx/portal-iam/docs/static/portal-application-overview.png; or + https://github.com/eclipse-tractusx/portal-iam/docs/static/registration-application-overview.png + +### App Role(s) + +App roles are managed by app provider by the portal user interface. It should be strictly forbidden to add / change any app roles in any other way. Reason: app roles are (beside that they are in the ownership of the app provider) impacting not only a Keycloak client and portal db; additionally apps have app clients registered in Keycloak and each client need to get enhanced with the new roles where human errors are very likely possible. + +### Technical User Role(s) + +Technical user roles are similar like portal user roles created/managed and enhanced by the platform owner. + +1. Create the roles inside Keycloak - central idp; realm: CX-Central inside the client "technical_role_management" + +- open the client via the left side menu **Clients** +- Open the tab **Roles** +- And click "Add" on the right hand side +- Enter the respective role name (keep in mind the role naming conversation) +- Click **"Save"** + +To transform the created "role" to an actual role, since currently its a single permission only; click on **Composite Roles** "ON". + + ![CompositeRoles](/docs/static/composite-roles.png) + + Afterwards select the respective permissions which should get collected under the new created role/composite role by selecting the client in which the relevant permissions are located. + Note: permissions of multiple clients can get assigned to one composite role without any troubles/issues. + + ![ClientRoles](/docs/static/client-roles.png) + +2. Create the same role inside the portal db (either via a delta migration job) or via sql. + +For the scenario of sql, the relevant sql can get found below: + + 1st create the role + + INSERT INTO portal.user_roles + (id, user_role, offer_id, last_editor_id) + VALUES ('{uuid}', '{user role name}', '{offer.id of technical_user_management}', '{operator user uuid}'); + +2nd add role description in german and english + + INSERT INTO portal.user_role_descriptions + (user_role_id, language_short_name, description) + VALUES + ('(user_roles.id)', '{de}', '{description}'), + ('(user_roles.id)', '{en}', '{description}'); + +3. Update keycloak base image + +...description needed by @evelyn + +4. Update documentation + +- [Roles&Rights Matrix](/docs/technical%20documentation/06.%20Roles%20&%20Rights%20Concept.md#253b-technical-user-accounts) + +- [Technical User Creation - End User documentation]([/docs/technical%20documentation/04%20User%20Management.md](https://github.com/eclipse-tractusx/portal-assets/blob/main/docs/03.%20User%20Management/03.%20Technical%20User/02.%20Create%20Technical%20User.md#available-technical-user-roles)) + +## What is the difference between roles & permission + +In the concept of the roles and rights management we are differentiating between roles and permissions. + +Permissions are the lowest level which a user can have. Several permissions are collected to a role. + +The assignment of rights to an actual user is happening on the role level itself. + +## How to setup technical user authentication + +Technical user/service accounts should get created as standalone client to clearly differentiate applications from technical users. +Each OIDC client has a built-in service account which allows it to obtain an access token. +This is covered in the OAuth 2.0 specification under Client Credentials Grant. To use this feature you must set the Access Type of your client to confidential. Make sure that you have configured your client credentials. + +In tab Service Account Roles you can configure the roles available to the service account retrieved on behalf of this client. + +https://github.com/keycloak/keycloak-documentation/blob/main/server_admin/topics/clients/oidc/service-accounts.adoc + +- Create the respective OIDC client, with respective setting + + - Access Type: confidential + - Standard Flow: disabled + - Direct Access Grant: disabled + - Service Accounts: enabled + - Add Mapper "BPN" to the user + + ![Bpn](/docs/static/bpn.png) + + - Add a bpn into the user account 8when using the existing api endpoints; the bon is added automatically based on the company bpn of the acting user + +After saving the config, the client gets automatically a service user account created which is used as "technical user" + +## Retrieve token for service account + + curl --location --request POST '{Keycloak URL}/auth/realms/{realm}/protocol/openid-connect/token' \ + --header 'Content-Type: application/x-www-form-urlencoded' \ + --data-urlencode 'client_secret={secret} \ + --data-urlencode 'grant_type=client_credentials' \ + --data-urlencode 'scope=openid' \ + --data-urlencode 'client_id={clientId}' + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/docs/technical documentation/12. Upgrade Details.md b/docs/technical documentation/12. Upgrade Details.md new file mode 100644 index 00000000..6380473d --- /dev/null +++ b/docs/technical documentation/12. Upgrade Details.md @@ -0,0 +1,139 @@ +- [Summary](#summary) + - [v1.7.0](#v170) + - [Role Concept changes - UPDATE](#role-concept-changes---update) +- [NOTICE](#notice) + +## Summary + +This document describes the keycloak database changes and its impact on transactional data. Depending on the impact, possible risks/impediments on upgrades as well as mitigation plans are described. +Each section includes the respective change details, impact on existing data and the respective release with which the change is getting active. + +### v1.7.0 + +#### Role Concept changes - UPDATE + +In the next Version the Roles 'App Tech User' & 'Connector User' in the client 'technical_user_management' will be removed. To assure that all Users which currently have one or both roles assigned have the correct roles in the future, the following script must be executed on the central idp database: + +```sql +WITH connector_users AS ( + SELECT user_id + FROM public.user_role_mapping AS urm + JOIN public.keycloak_role AS kr + ON urm.role_id = kr.id + WHERE kr.name = 'Connector User' +), +new_connector_roles_to_insert AS ( + SELECT DISTINCT atu.user_id, kr.id AS role_id + FROM connector_users AS atu + CROSS JOIN ( + SELECT id + FROM public.keycloak_role + WHERE name IN ('Semantic Model Management', 'Dataspace Discovery') + ) kr +) +INSERT INTO public.user_role_mapping (user_id, role_id) +SELECT rt.user_id, rt.role_id +FROM new_connector_roles_to_insert rt + LEFT JOIN public.user_role_mapping urm + ON rt.user_id = urm.user_id AND rt.role_id = urm.role_id +WHERE urm.user_id IS NULL; + +WITH app_tech_users AS ( + SELECT user_id + FROM public.user_role_mapping AS urm + JOIN public.keycloak_role AS kr + ON urm.role_id = kr.id + WHERE kr.name = 'App Tech User' +), +roles_to_insert AS ( + SELECT DISTINCT atu.user_id, kr.id AS role_id + FROM app_tech_users AS atu + CROSS JOIN ( + SELECT id + FROM public.keycloak_role + WHERE name IN ('Semantic Model Management', 'Dataspace Discovery', 'CX Membership Info') + ) kr +) +INSERT INTO public.user_role_mapping (user_id, role_id) +SELECT rt.user_id, rt.role_id +FROM roles_to_insert rt + LEFT JOIN public.user_role_mapping urm + ON rt.user_id = urm.user_id AND rt.role_id = urm.role_id +WHERE urm.user_id IS NULL; + +WITH service_management_users AS ( + SELECT user_id + FROM public.user_role_mapping AS urm + JOIN public.keycloak_role AS kr + ON urm.role_id = kr.id + WHERE kr.name = 'Service Management' +), +new_offer_management_roles_to_insert AS ( + SELECT DISTINCT atu.user_id, kr.id AS role_id + FROM service_management_users AS atu + CROSS JOIN ( + SELECT id + FROM public.keycloak_role + WHERE name = 'Offer Management' + ) kr +) +INSERT INTO public.user_role_mapping (user_id, role_id) +SELECT rt.user_id, rt.role_id +FROM new_offer_management_roles_to_insert rt + LEFT JOIN public.user_role_mapping urm + ON rt.user_id = urm.user_id AND rt.role_id = urm.role_id +WHERE urm.user_id IS NULL; + +``` + +To test if all user got the expected roles assigned please execute the following scripts after each other. All the scripts shouldn't return anything. If you see an userId returned from one of the scripts the above script needs to be executed again. + +```sql +SELECT DISTINCT u.user_id +FROM public.user_role_mapping u +JOIN public.keycloak_role r ON u.role_id = r.id +WHERE r.name = 'Connector User' +AND u.user_id NOT IN ( + SELECT user_id + FROM public.user_role_mapping + JOIN public.keycloak_role ON user_role_mapping.role_id = keycloak_role.id + WHERE keycloak_role.name IN ('Semantic Model Management', 'Dataspace Discovery') +); + +SELECT DISTINCT u.user_id +FROM public.user_role_mapping u +JOIN public.keycloak_role r ON u.role_id = r.id +WHERE r.name = 'App Tech User' +AND u.user_id NOT IN ( + SELECT user_id + FROM public.user_role_mapping + JOIN public.keycloak_role ON user_role_mapping.role_id = keycloak_role.id + WHERE keycloak_role.name IN ('Dataspace Discovery', 'Semantic Model Management', 'CX Membership Info') +); + +SELECT DISTINCT u.user_id +FROM public.user_role_mapping u +JOIN public.keycloak_role r ON u.role_id = r.id +WHERE r.name = 'Service Management' +AND u.user_id NOT IN ( + SELECT user_id + FROM public.user_role_mapping + JOIN public.keycloak_role ON user_role_mapping.role_id = keycloak_role.id + WHERE keycloak_role.name = 'Offer Management' +); + +``` + +Since Keycloak uses a caching mechanism its likely that you'll experience a strange behavior in admin console where you see only the old roles assigned to a user instead of the newly assigned ones. + +To fix that our recommendation is to restart the stateful set of the central idp. If you don't want to restart the stateful set you could disable the Central-CX realm and enable it directly afterwards. + +! Important ! the new roles: 'Semantic Model Management', 'Dataspace Discovery', 'CX Membership Info' and 'Offer Management' must be existing in the central idp database + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam diff --git a/scripts/add_notice_footer.sh b/scripts/add_notice_footer.sh new file mode 100755 index 00000000..d1f11715 --- /dev/null +++ b/scripts/add_notice_footer.sh @@ -0,0 +1,57 @@ +#!/bin/bash + +############################################################### +# Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License, Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0. +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# SPDX-License-Identifier: Apache-2.0 +############################################################### + +print-usage() { + cat << EOF +# +# Add license notice to all md files +# +# usage: +# source ./scripts/add_notice_footer.sh +# cd path/to/your/documentation +# add-notice +# +EOF +} + +add-notice() { + notice_text='''## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam''' + + # Find all .md files in the directory and its subdirectories, excluding directories from the search + find . -type f -name "*.md" -print0 | while IFS= read -r -d '' file; do + last_line=$(tail -n 7 "$file") + + # Check if the last line of the file matches the notice text + if [ "$last_line" != "$notice_text" ]; then + # Append the notice text if it's not already there + echo -e "\n$notice_text" >> "$file" + echo "Notice added to $file" + fi + done +} + +print-usage \ No newline at end of file diff --git a/scripts/license.sh b/scripts/license.sh new file mode 100755 index 00000000..0baa88ca --- /dev/null +++ b/scripts/license.sh @@ -0,0 +1,50 @@ +#!/bin/bash + +############################################################### +# Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License, Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0. +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# SPDX-License-Identifier: Apache-2.0 +############################################################### + +print-usage() { + cat << EOF +# +# Generate license files for all images in folder and subfolders +# +# usage: +# source ./scripts/license.sh +# cd path/to/your/images +# license-images +# +EOF +} + +license-images() { + for file in $(find . -type f \( -name '*.png' -o -name '*.jpg' -o -name '*.svg' \)); + do + echo $file + cat << EOF > $file.license +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets + +EOF + done +} + +print-usage