{"id":20655926,"url":"https://github.com/it-at-m/appswitcher-server","last_synced_at":"2025-04-19T12:15:44.791Z","repository":{"id":103252713,"uuid":"591375588","full_name":"it-at-m/appswitcher-server","owner":"it-at-m","description":"Server component for a Google-like app switching experience.","archived":false,"fork":false,"pushed_at":"2024-10-17T06:35:20.000Z","size":260,"stargazers_count":6,"open_issues_count":3,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-10-19T09:12:32.310Z","etag":null,"topics":["java","keycloak","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/it-at-m.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-20T15:52:13.000Z","updated_at":"2024-10-17T06:45:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"dbd950b0-14ad-4f7b-bb77-4c332898b395","html_url":"https://github.com/it-at-m/appswitcher-server","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/it-at-m%2Fappswitcher-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/it-at-m%2Fappswitcher-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/it-at-m%2Fappswitcher-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/it-at-m%2Fappswitcher-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/it-at-m","download_url":"https://codeload.github.com/it-at-m/appswitcher-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224951645,"owners_count":17397425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","keycloak","spring-boot"],"created_at":"2024-11-16T18:13:05.679Z","updated_at":"2024-11-16T18:13:06.290Z","avatar_url":"https://github.com/it-at-m.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- PROJECT SHIELDS --\u003e\n\n[![Contributors][contributors-shield]][contributors-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n[![GitHub Workflow Status][github-workflow-status]][github-workflow-status-url]\n[![GitHub release (latest SemVer)][release-shield]][release-url]\n\n# appswitcher-server\n\n**appswitcher-server** renders a simple web page containing icon-based hyperlinks to common web applications used in your (corporate) environment.\nThe static page is designed to be embedded (e.g. using an `iframe`) into your web applications to provide your users with **a quick way to switch between these applications**.\n\nappswitcher-server was **heavily inspired by** [Google's App Bar](https://support.google.com/accounts/answer/1714464?hl=en#zippy=%2Cswitch-between-apps), which provides a quick way to switch between Google Apps.\n\nAt [it@M](https://github.com/it-at-m) we use appswitcher-server internally to offer our customers a quick way to switch between internal or external web applications like the social intranet \"WiLMA\", the phone book and many other web applications:\n\n![Screenshot of an example of appswitcher-server's webpage](docs/with_default_tags.png)\n\nThe web page of appswitcher-server will be embedded (mostly by using an `iframe`) into the app bar of our web applications (= `client applications`):\n\n![Screenshot of appswitcher-servers webpage embedded in a web application's app bar](docs/embedded_in_applications.png)\n\nIf you are using Vue.js/Vuetify or Vaadin Flow to build your frontends, there are already pre-built components which allow integrating the `iframe` very quickly:\n\n- \u003chttps://github.com/it-at-m/appswitcher-vue\u003e\n- \u003chttps://github.com/it-at-m/appswitcher-vaadin\u003e\n\n## Features\n\n### Custom applications\n\nApplications can be freely configured by adding them to the `apps` map in [`application.yml`](src/main/resources/application.yml), for example:\n\n```yml\nappswitcher.apps:\n  github: # unique key\n    display-name: GitHub\n    url: https://github.com/it-at-m\n    image-url: https://avatars.githubusercontent.com/u/58515289?s=144\u0026v=4\n    sort-order: 10\n```\n\n| Property       | Description                                                                                                                                            |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `display-name` | Name of the application                                                                                                                                |\n| `url`          | URL of the application, will be used for the hyperlink                                                                                                 |\n| `image-url`    | URL for the applications image/icon. The image should be quadratic, size should be between `48x48` and `144x144` pixels.                               |\n| `sort-order`   | _optional_: Number used for ordering the application in the application listing in ascending order. Applications without an order will be placed last. |\n\n### Tags\n\nApplications can be assigned (multiple) tags. For example, you could use tags to distinguish applications by their application domain like `finance`, `development`, `customer-relations` and so on.\n\n```yml\nappswitcher.apps:\n  github:\n    display-name: GitHub\n    url: https://github.com/it-at-m\n    image-url: https://avatars.githubusercontent.com/u/58515289?s=144\u0026v=4\n    tags:\n      - development\n```\n\nClient applications (= applications that embed the appswitcher server web page) can request specific tags by using the query parameter `tags`. For example, if you embed the appswitcher in a development centric web application, the client application could request only apps tagged with `development` by using the following url as IFrame `src`:\n\n    https://appswitcher.mycompany.org?tags=development\n\nClient applications can also request multiple tags (e.g. `?tags=development,finance`). This way, an application will be included if it has any of the requested tags.\n\nIf a client application does not specify any tags, **by default** only applications tagged as `global` will be included.\n\n### Keycloak integration\n\nIf you are using [Keycloak](https://www.keycloak.org/) with OpenID for access management and single sign-on in your environment, you can also add (multiple) client ID(s) to applications that use Keycloak/OpenID for access management.\n\n```yml\nappswitcher.apps:\n  finance:\n    display-name: Finance Reports\n    url: https://finance.mycompany.com\n    image-url: https://avatars.githubusercontent.com/u/58515289?s=144\u0026v=4\n    client-id:\n      - finance\n```\n\nWith this configuration, an icon-based hyperlink to the \"Finance Reports\" web application will only be included if the current user's access token claim `audience` contains the client id (and [the tags match](#tags) the requested tags). This is based on the [Audience Support](https://www.keycloak.org/docs/latest/server_admin/#audience-support) in Keycloak.\n\nWhen using the Keycloak integration you can only include web applications that the current user has a permission to access.\n\nKeycloak integration is disabled by default. When enabled, appswitcher-server acts as an OpenID client application to retrieve a user's access token.\n\nThis integration works best if your user's operating system propagates a session to the browser and therefore Keycloak, for example Kerberos on Windows.\n\nFor the Keycloak integration to work properly, there are a few caveats (IFrame and cookies, X-Frame-Options) to be aware of. See the [wiki page](https://github.com/it-at-m/appswitcher-server/wiki/IFrame-caveats) for more details.\n\n## Configuration\n\nappswitcher-server is a Spring Boot application and can therefore be configured using the [Spring environment abstraction](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config).\n\n| Environment variable   | System/Spring property   | Description                                                           | Default value |\n| ---------------------- | ------------------------ | --------------------------------------------------------------------- | ------------- |\n| SPRING_PROFILES_ACTIVE | `spring.profiles.active` | Comma seperated list of Spring profiles to activate (e.g. `keycloak`) |               |\n| APPSWITCHER_APPS       | `appswitcher.apps`       | Map with applications (see [Features](#features))                     |               |\n\n### Keycloak integration\n\nKeycloak integration can be enabled by enabling the Spring profile `keycloak` (see `SPRING_PROFILES_ACTIVE` in [Configuration](#configuration)).\n\n| Environment variable                   | System/Spring property                 | Description                                                                                          | Default value |\n| -------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------- |\n| `APPSWITCHER_KEYCLOAK_CLIENT_ID`       | `appswitcher.keycloak.clientId`        | Client ID of the appswitcher itself.                                                                 |               |\n| `APPSWITCHER_KEYCLOAK_CLIENT_SECRET`   | `appswitcher.keycloak.client-secret`   | Client secret.                                                                                       |               |\n| `APPSWITCHER_KEYCLOAK_ISSUER_URI`      | `appswitcher.keycloak.issuer-uri`      | Issuer uri (e.g. 'https://keycloak.mycompany.org/auth/realms/myrealm')                               |               |\n| `APPSWITCHER_KEYCLOAK_JWK_SET_URI`     | `appswitcher.keycloak.jwk-set-uri`     | JWK set uri (e.g. 'https://keycloak.mycompany.org/auth/realms/myrealm/protocol/openid-connect/certs' |               |\n| `APPSWITCHER_KEYCLOAK_SCOPES`          | `appswitcher.keycloak.scopes`          | Comma-seperated list of requested scopes (e.g. 'openid,roles').                                      |               |\n| `APPSWITCHER_KEYCLOAK_SSO_SESSION_MAX` | `appswitcher.keycloak.sso-session-max` | Maximum time in seconds before keycloak expires the sso sessions (e.g. '36000' for 10 hours).        |               |\n\n## Using\n\n### Docker\n\nYou can use the official container image [ghrc.io/it-at-m/appswitcher-server](https://github.com/it-at-m/appswitcher-server/pkgs/container/appswitcher-server). To provide your [custom Applications](#custom-applications) create a custom `application.yml` containing your applications under the key `appswitcher.apps.*` and mount the file as a volume at `/workspace/config/application.yml`.\n\n### Kubernetes\n\nIf you want to deploy appswitcher-server on a Kubernetes cluster, you can use the [official Helm chart][helm-chart-github].\n\n## Build \u0026 Development\n\nThis project is built with technologies we use in our projects:\n\n- Java\n- Maven\n- Spring Boot\n\nBuild:\n\n```\nmvn clean install\n```\n\nRun:\n\n```\nmvn spring-boot:run -Dspring-boot.run.profiles=demo\n```\n\nVisit \u003chttp://localhost:8080\u003e to see the generated application link list with the `demo` applications.\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please open an issue with the tag \"enhancement\", fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\nDon't forget to give the project a star! Thanks again!\n\n1. Open an issue with the tag \"enhancement\"\n2. Fork the Project\n3. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n4. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n5. Push to the Branch (`git push origin feature/AmazingFeature`)\n6. Open a Pull Request\n\nWe use [itm-java-codeformat](https://github.com/it-at-m/itm-java-codeformat), so please make sure to apply the correct code format for your contributions.\n\n## License\n\nDistributed under the MIT License. See [LICENSE](LICENSE) file for more information.\n\n## Contact\n\nit@M - opensource@muenchen.de\n\n[contributors-shield]: https://img.shields.io/github/contributors/it-at-m/appswitcher-server.svg?style=for-the-badge\n[contributors-url]: https://github.com/it-at-m/appswitcher-server/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/it-at-m/appswitcher-server.svg?style=for-the-badge\n[forks-url]: https://github.com/it-at-m/appswitcher-server/network/members\n[stars-shield]: https://img.shields.io/github/stars/it-at-m/appswitcher-server.svg?style=for-the-badge\n[stars-url]: https://github.com/it-at-m/appswitcher-server/stargazers\n[issues-shield]: https://img.shields.io/github/issues/it-at-m/appswitcher-server.svg?style=for-the-badge\n[issues-url]: https://github.com/it-at-m/appswitcher-server/issues\n[license-shield]: https://img.shields.io/github/license/it-at-m/appswitcher-server.svg?style=for-the-badge\n[license-url]: https://github.com/it-at-m/appswitcher-server/blob/main/LICENSE\n[github-workflow-status]: https://img.shields.io/github/actions/workflow/status/it-at-m/appswitcher-server/build.yaml?style=for-the-badge\n[github-workflow-status-url]: https://github.com/it-at-m/appswitcher-server/actions/workflows/build.yaml\n[release-shield]: https://img.shields.io/github/v/release/it-at-m/appswitcher-server?sort=semver\u0026style=for-the-badge\n[release-url]: https://github.com/it-at-m/appswitcher-server/releases\n[helm-chart-github]: https://artifacthub.io/packages/helm/it-at-m/appswitcher-server\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fit-at-m%2Fappswitcher-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fit-at-m%2Fappswitcher-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fit-at-m%2Fappswitcher-server/lists"}