{"id":20655941,"url":"https://github.com/it-at-m/ad2image","last_synced_at":"2026-03-09T11:06:20.693Z","repository":{"id":65461232,"uuid":"581541178","full_name":"it-at-m/ad2image","owner":"it-at-m","description":"easy avatars powered by AD / Exchange \u0026 Identicons","archived":false,"fork":false,"pushed_at":"2026-03-04T11:33:47.000Z","size":348,"stargazers_count":8,"open_issues_count":4,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-04T13:50:16.411Z","etag":null,"topics":["active-directory","exchange-server","java","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-12-23T13:47:17.000Z","updated_at":"2026-03-04T08:01:17.000Z","dependencies_parsed_at":"2023-12-13T17:56:12.330Z","dependency_job_id":"bfedf25a-d998-4624-a0dd-49c64ff51d6d","html_url":"https://github.com/it-at-m/ad2image","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/it-at-m/ad2image","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/it-at-m%2Fad2image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/it-at-m%2Fad2image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/it-at-m%2Fad2image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/it-at-m%2Fad2image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/it-at-m","download_url":"https://codeload.github.com/it-at-m/ad2image/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/it-at-m%2Fad2image/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30291857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["active-directory","exchange-server","java","spring-boot"],"created_at":"2024-11-16T18:13:09.986Z","updated_at":"2026-03-09T11:06:20.656Z","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# ad2image\n\n**ad2image** provides an easy-to-use, minimalistic HTTP API to retrieve user photos from an Active Directory / Microsoft\nExchange environment. It also provides fallback photos\nusing [avatar-generator](https://gitlab.talanlabs.com/gabriel-allaigre/avatar-generator-parent) if a user has no photo\nstored.\n\nBehind the curtains, by default a 64x64 pixel thumbnail photo is retrieved from Active Directory (Attribute\n`thumbnailPhoto`). Higher resolution photos can also be requested, those will be fetched by using\nthe [Exchange EWS REST API](https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-get-user-photos-by-using-ews-in-exchange#get-a-mailbox-user-photo-by-using-rest).\n\n**ad2image** can be integrated in your Spring Boot application by using the provided starter\n`ad2image-spring-boot-starter`.\nIf you want to deploy **ad2image** as a standalone application, you can use\nthe [provided container image](#running-as-a-container-standalone) or [Helm chart][helm-chart-github].\n\n**ad2image** was initially created as **mucatar** internally at it@M. It is used by many of our in-house projects to\nprovide user photos for a richer user experience. For example, it can be very easily used as photo provider\nfor [Vuetify's Avatar component](https://vuetifyjs.com/en/components/avatars/).\n\n## Built With\n\nThis project is built with technologies we use in our projects:\n\n- Java\n- Spring Boot\n\n## Set up\n\n```bash\nmvn clean install\n```\n\nFor development, an Active Directory / Exchange environment is not needed. It is mocked by an embedded LDAP server and\nWireMock (for the EWS API).\n\n## Documentation\n\nOpenAPI v3 documentation is provided and can be retrieved via Swagger UI (`\u003cyour-instance\u003e/swagger-ui/index.html`).\n\n### Using the API\n\n`GET /avatar?uid=john.doe[\u0026m=identicon|404|fallbackIdenticon|...][\u0026size=64]`\n\nPossible modes (`m`):\n\n- `404`: 404 Response, if the user has no photo stored in AD/Exchange\n- `identicon`: renders an [Identicon](https://en.wikipedia.org/wiki/Identicon), if the user has no photo stored in\n AD/Exchange\n- `fallbackIdenticon`: identical to `identicon`, but also responds with an Identicon if the user itself does not exist\n in AD/Exchange\n- `generic`: renders an [generic placeholder icon](ad2image-spring-boot-starter/src/main/resources/account_64.png), if\n the user has no photo stored in AD/Exchange\n- `fallbackGeneric`: **default** - identical to `generic`, but also responds with an generic placeholder icon if the\n user itself does not exist in AD/Exchange\n- `genericDark`: renders a [generic placeholder icon with white foreground](ad2image-spring-boot-starter/src/main/resources/account_dark.png) (for dark mode applications), if\n the user has no photo stored in AD/Exchange\n- `fallbackGenericDark`: identical to `genericDark`, but also responds with a generic placeholder icon with white foreground if the\n user itself does not exist in AD/Exchange\n- `triangle`: renders\n an [randomly generated Avatar based on triangles](https://raw.githubusercontent.com/gabrie-allaigre/avatar-generator/master/doc/triangle1.png),\n if the user has no photo stored in AD/Exchange\n- `fallbackTriangle`: identical to `triangle`, but also responds correspondingly if the user itself does not exist in\n AD/Exchange\n- `square`: renders\n an [randomly generated Avatar based on squares](https://raw.githubusercontent.com/gabrie-allaigre/avatar-generator/master/doc/square1.png),\n if the user has no photo stored in AD/Exchange\n- `fallbackSquare`: identical to `square`, but also responds correspondingly if the user itself does not exist in\n AD/Exchange\n- `github`: renders\n an [randomly generated Avatar based Github avatar style](https://raw.githubusercontent.com/gabrie-allaigre/avatar-generator/master/doc/github2.png),\n if the user has no photo stored in AD/Exchange\n- `fallbackGithub`: identical to `github`, but also responds correspondingly if the user itself does not exist in\n AD/Exchange\n- `initials`: renders a colored square avatar with the user's initials (first letter of given name + first letter of surname), derived from the user's AD `givenName` and `sn` attributes. The background color is deterministically derived from the user's uid. If no name is stored, a plain colored rectangle is rendered. Returns 404 if the user does not exist in AD.\n The background colors in `initials` mode (implemented in [InitialsAvatarGenerator.java](ad2image-spring-boot-starter/src/main/java/de/muenchen/oss/ad2image/starter/core/InitialsAvatarGenerator.java)) are chosen using an HSL strategy (60% saturation and ~45% lightness) to provide sufficient contrast with the white initials text for accessibility.\n\nPossible resolutions (`size`): between 1 and 2048 pixels\n\n### Gravatar compatability API endpoint\n\nad2image provides an API endpoint that mimics the [Gravatar API](https://docs.gravatar.com/sdk/images/) but\ninternally resolves the user photos from your Active Directory / Exchange environment:\n\n`GET /gravatar/\u003csha256-hex-hash-of-lowercase-trimmed-mail-address\u003e?[d=identicon/404]\u0026s=200`\n\nWhen the Gravatar compatability endpoint is activated, ad2image retrieves all users from Active Directory on startup to\ncompute an in-memory lookup table that contains the SHA256-hashed mail addresses. ad2image also can periodically update\nthis lookup table during runtime.\nSee [Configuration](#configuration) for more details on how to configure this endpoint for your environment.\n\nThis endpoint also only supports a subset of the Gravatar API features:\n\n- Default image (`d` query param): `identicon`, `404`, `mp` (mystery person), and `initials` are supported; other values fall back to the configured gravatar default mode\n- Size: can be requested between 1 and 2048px\n- Force Default (`f`): not supported, will be ignored\n- Rating (`r`): not supported, will be ignored\n\n### Running as a container (standalone)\n\nYou can use the provided official Docker\nimage [ghcr.io/it-at-m/ad2image](https://github.com/it-at-m/ad2image/pkgs/container/ad2image) to run **ad2image** as a\nstandalone application.\n\n```sh\ndocker run -d -p 8080:8080 --name ad2image ghcr.io/it-at-m/ad2image:1.1.1\n```\n\nTo connect to your Exchange/EWS environment, some environment variables must be set, see [Configuration](#configuration)\nfor a full list.\n\nBy default, ad2image uses a server-side cache (\nsee [default_ehcache.xml](ad2image-app/src/main/resources/default_ehcache.xml)). You can provide your own `ehcache.xml`\nif you want to change the cache configuration (e.g. decrease the TTL).\n\n1. Create your custom `ehcache.xml` and mount it as a volume for the container, for example with Docker `--mount`:\n\n```\ndocker run --mount type=bind,source=/home/user/my-ehcache.xml,target=/cacheconfig/my-ehcache.xml,readonly [...]\n```\n\n2. Set the container environment variable `SPRING_CACHE_JCACHE_CONFIG` to point to the custom `ehcache.xml`, for\n example:\n\n```\nSPRING_CACHE_JCACHE_CONFIG=file:/cacheconfig/my-ehcache.xml\n```\n\n### Deploying on Kubernetes using a Helm chart\n\nIf you want to deploy ad2image on a Kubernetes cluster, you can use the [provided Helm chart][helm-chart-github].\n\n### Integrating in a existing Spring Boot application\n\nad2image can be integrated in a existing Spring Boot application by adding the `ad2image-spring-boot-starter`\ndependency, e.g. for Maven:\n\n```xml\n\n\u003cdependency\u003e\n\t\u003cgroupId\u003ede.muenchen.oss.ad2image\u003c/groupId\u003e\n\t\u003cartifactId\u003ead2image-spring-boot-starter\u003c/artifactId\u003e\n\t\u003cversion\u003e1.1.1\u003c/version\u003e\u003c!-- see GitHub Release for latest version --\u003e\n\u003c/dependency\u003e\n```\n\nTo configure ad2image, add the corresponding `de.muenchen.oss.ad2image.*` properties to your `application.properties`/\n`application.yml`. For a full list of possible configuration properties see [Configuration](#configuration).\n\n### Configuration\n\nad2image can be configured via Spring environment abstraction.\n\n| Environment variable | System/Spring property | Description | Default value | Required |\n| ----------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -------- |\n| `DE_MUENCHEN_OSS_AD2IMAGE_ENABLED` | `de.muenchen.oss.ad2image.enabled` | can be used to disable ad2image auto configuration (if integrated in your own application) | - | no |\n| `DE_MUENCHEN_OSS_AD2IMAGE_DEFAULT_MODE` | `de.muenchen.oss.ad2image.default-mode` | Default mode (`m`) if user provides none. | `\"M_FALLBACK_GENERIC\"` (`fallbackGeneric`) | yes |\n| `DE_MUENCHEN_OSS_AD2IMAGE_AD_URL` | `de.muenchen.oss.ad2image.ad.url` | Connection URL for AD server, for example 'ldaps://example.com:636'. | - | yes |\n| `DE_MUENCHEN_OSS_AD2IMAGE_AD_USER_DN` | `de.muenchen.oss.ad2image.ad.user-dn` | Bind User-DN for AD authentication | - | yes |\n| `DE_MUENCHEN_OSS_AD2IMAGE_AD_PASSWORD` | `de.muenchen.oss.ad2image.ad.password` | Password for AD authentication | - | yes |\n| `DE_MUENCHEN_OSS_AD2IMAGE_AD_USER_SEARCH_BASE` | `de.muenchen.oss.ad2image.ad.user-search-base` | User Search Base for user lookup, for example 'OU=Users,DC=mycompany,DC=com'. | - | yes |\n| `DE_MUENCHEN_OSS_AD2IMAGE_AD_USER_SEARCH_FILTER` | `de.muenchen.oss.ad2image.ad.user-search-filter` | User Search filter, `{uid}` will be replaced with the requested user uid. | `(\u0026(objectClass=organizationalPerson)(cn={uid}))` | yes |\n| `DE_MUENCHEN_OSS_AD2IMAGE_AD_SN_ATTRIBUTE` | `de.muenchen.oss.ad2image.ad.sn-attribute` | LDAP attribute name for the user's surname, used to build initials avatars. | `sn` | no |\n| `DE_MUENCHEN_OSS_AD2IMAGE_AD_GIVEN_NAME_ATTRIBUTE` | `de.muenchen.oss.ad2image.ad.given-name-attribute` | LDAP attribute name for the user's given name, used to build initials avatars. | `givenName` | no |\n| `DE_MUENCHEN_OSS_AD2IMAGE_EWS_EWS_SERVICE_URL` | `de.muenchen.oss.ad2image.ews.ews-service-url` | [EWS service URL](https://learn.microsoft.com/en-US/exchange/client-developer/exchange-web-services/how-to-set-the-ews-service-url-by-using-the-ews-managed-api), e.g. `https://example.com/ews/Exchange.asmx`. | - | yes |\n| `DE_MUENCHEN_OSS_AD2IMAGE_EWS_USERNAME` | `de.muenchen.oss.ad2image.ews.username` | Username for EWS [Basic Authentication](https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/authentication-and-ews-in-exchange#basic-authentication). | - | yes |\n| `DE_MUENCHEN_OSS_AD2IMAGE_EWS_PASSWORD` | `de.muenchen.oss.ad2image.ews.password` | Password for EWS [Basic Authentication](https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/authentication-and-ews-in-exchange#basic-authentication). | - | yes |\n| `DE_MUENCHEN_OSS_AD2IMAGE_GRAVATAR_ENABLED` | `de.muenchen.oss.ad2image.gravatar.enabled` | Enables/disables the Gravatar compatability endpoint. | `false` | no |\n| `DE_MUENCHEN_OSS_AD2IMAGE_GRAVATAR_HASH_CACHE_REFRESH_CRON` | `de.muenchen.oss.ad2image.gravatar.hash-cache-refresh-cron` | Spring \"cron\" expression for periodic refresh of the SHA256 email address hashes, '-' to disable. | `-` | no |\n| `DE_MUENCHEN_OSS_AD2IMAGE_GRAVATAR_MAP_POPULATION_FILTER` | `de.muenchen.oss.ad2image.gravatar.map-population-filter` | LDAP search filter for users which should be included in generation of SHA256-hashed email addresses. | `(\u0026(objectClass=organizationalPerson)(mail=*))` | no |\n| `DE_MUENCHEN_OSS_AD2IMAGE_GRAVATAR_PAGE_SIZE` | `de.muenchen.oss.ad2image.gravatar.page-size` | page size for retrieval of users during map population. | `500` | no |\n| `DE_MUENCHEN_OSS_AD2IMAGE_GRAVATAR_DEFAULT_MODE` | `de.muenchen.oss.ad2image.gravatar.default-mode` | Default mode for Gravatar API when the requested `d=` parameter is unsupported or missing. Independent from the main avatar API's default mode setting. | `M_FALLBACK_GENERIC` | no |\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any\ncontributions 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\ncreate 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\ncode 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/ad2image.svg?style=for-the-badge\n[contributors-url]: https://github.com/it-at-m/ad2image/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/it-at-m/ad2image.svg?style=for-the-badge\n[forks-url]: https://github.com/it-at-m/ad2image/network/members\n[stars-shield]: https://img.shields.io/github/stars/it-at-m/ad2image.svg?style=for-the-badge\n[stars-url]: https://github.com/it-at-m/ad2image/stargazers\n[issues-shield]: https://img.shields.io/github/issues/it-at-m/ad2image.svg?style=for-the-badge\n[issues-url]: https://github.com/it-at-m/ad2image/issues\n[license-shield]: https://img.shields.io/github/license/it-at-m/ad2image.svg?style=for-the-badge\n[license-url]: https://github.com/it-at-m/ad2image/blob/main/LICENSE\n[github-workflow-status]: https://img.shields.io/github/actions/workflow/status/it-at-m/ad2image/build.yaml?style=for-the-badge\n[github-workflow-status-url]: https://github.com/it-at-m/ad2image/actions/workflows/build.yaml\n[release-shield]: https://img.shields.io/github/v/release/it-at-m/ad2image?sort=semver\u0026style=for-the-badge\n[release-url]: https://github.com/it-at-m/ad2image/releases\n[helm-chart-github]: https://artifacthub.io/packages/helm/it-at-m/ad2image\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fit-at-m%2Fad2image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fit-at-m%2Fad2image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fit-at-m%2Fad2image/lists"}