ad2image

ad2image provides an easy-to-use, minimalistic HTTP API to retrieve user photos from an Active Directory / Microsoft Exchange environment. It also provides fallback photos using avatar-generator if a user has no photo.

Behind the curtains, by default a 64x64 pixel thumbnail photo is retrieved from Active Directory (Attribute thumbnailPhoto). Higher resolution photos can also be used, those will be fetched internally by using the Exchange EWS REST API.

ad2image can be integrated in your Spring Boot application by using the provided starter ad2image-spring-boot-starter. If you want to deploy ad2image as a standalone application, you can use the provided container image or Helm chart.

ad2image was initially created as mucatar internally at it@M. It is used by many of our in-house projects to provide user photos for a richer user experience. For example, it can be very easily used as photo provider for Vuetify's Avatar component.

Built With

This project is built with technologies we use in our projects:

• Java
• Spring Boot

Set up

mvn clean install

For development, a Active Directory / Exchange environment is not needed. It is mocked by an embedded LDAP server and WireMock (for the EWS API).

Documentation

Using the API

GET /avatar?uid=john.doe[&m=identicon|404|fallbackIdenticon][&size=64]

Possible modes (m):

• 404: 404 Response, if the user has no photo stored in AD/Exchange
• identicon: default - renders an Identicon, if the user has no photo stored in AD/Exchange
• fallbackIdenticon: identical to identicon, but also responds with an Identicon if the user itself does not exist in AD/Exchange
• generic: renders an generic placeholder icon, if the user has no photo stored in AD/Exchange
• fallbackGeneric: identical to generic, but also responds with an generic placeholder icon if the user itself does not exist in AD/Exchange
• triangle: renders an randomly generated Avatar based on triangles, if the user has no photo stored in AD/Exchange
• fallbackTriangle: identical to triangle, but also responds correspondingly if the user itself does not exist in AD/Exchange
• square: renders an randomly generated Avatar based on squares, if the user has no photo stored in AD/Exchange
• fallbackSquare: identical to square, but also responds correspondingly if the user itself does not exist in AD/Exchange
• github: renders an randomly generated Avatar based Github avatar style, if the user has no photo stored in AD/Exchange
• fallbackGithub: identical to github, but also responds correspondingly if the user itself does not exist in AD/Exchange

Possible resolutions (size):

• 64 (default)
• 96
• 120
• 240
• 360
• 432
• 504
• 648

Running as a container (standalone)

You can use the provided official Docker image ghrc.io/it-at-m/ad2image to run ad2image as a standalone application.

docker run -d -p 8080:8080 --name ad2image ghrc.io/it-at-m/ad2image:1.0.7

To connect to your Exchange/EWS environment, some environment variables must be set, see Configuration for a full list.

By default, ad2image uses a server-side cache (see default_ehcache.xml). You can provide your own ehcache.xml if you want to change the cache configuration (e.g. decrease the TTL).

1. Create your custom ehcache.xml and mount it as a volume for the container, for example with Docker --mount:

docker run --mount type=bind,source=/home/user/my-ehcache.xml,target=/cacheconfig/my-ehcache.xml,readonly [...]

2. Set the container environment variable SPRING_CACHE_JCACHE_CONFIG to point to the custom ehcache.xml, for example:

SPRING_CACHE_JCACHE_CONFIG=file:/cacheconfig/my-ehcache.xml

Deploying on Kubernetes using a Helm chart

If you want to deploy ad2image on a Kubernetes cluster, you can use the provided Helm chart.

Integrating in a existing Spring Boot application

ad2image can be integrated in a existing Spring Boot application by adding the ad2image-spring-boot-starter dependency, e.g. for Maven:

<dependency>
  <groupId>de.muenchen.oss.ad2image</groupId>
  <artifactId>ad2image-spring-boot-starter</artifactId>
  <version>1.0.4</version>
</dependency>

To configure ad2image, add the corresponding de.muenchen.oss.ad2image.* properties to your application.properties/application.yml. For a full list of possible configuration properties see Configuration.

Configuration

ad2image can be configured via Spring environment abstraction.

Environment variable	System/Spring property	Description	Default value	Required
DE_MUENCHEN_OSS_AD2IMAGE_AD_URL	de.muenchen.oss.ad2image.ad.url	Connection URL for AD server, for example 'ldaps://ad.mydomain.com:636'.	-	yes
DE_MUENCHEN_OSS_AD2IMAGE_AD_USER_DN	de.muenchen.oss.ad2image.ad.user-dn	Bind User-DN for AD authentication	-	yes
DE_MUENCHEN_OSS_AD2IMAGE_AD_PASSWORD	de.muenchen.oss.ad2image.ad.password	Password for AD authentication	-	yes
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
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.	(&(objectClass=organizationalPerson)(cn={uid}))
DE_MUENCHEN_OSS_AD2IMAGE_EWS_EWS_SERVICE_URL	de.muenchen.oss.ad2image.ews.ews-service-url	EWS service URL, e.g. https://computer.domain.contoso.com/EWS/Exchange.asmx.	-	yes
DE_MUENCHEN_OSS_AD2IMAGE_EWS_USERNAME	de.muenchen.oss.ad2image.ews.username	Username for EWS NTLM authentication.	-	yes
DE_MUENCHEN_OSS_AD2IMAGE_EWS_PASSWORD	de.muenchen.oss.ad2image.ews.password	Password for EWS NTLM authentication.	-	yes
DE_MUENCHEN_OSS_AD2IMAGE_EWS_DOMAIN	de.muenchen.oss.ad2image.ews.domain	Exchange/EWS domain, e.g. 'domain.contoso.com'	-	yes

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If 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". Don't forget to give the project a star! Thanks again!

1. Open an issue with the tag "enhancement"
2. Fork the Project
3. Create your Feature Branch (git checkout -b feature/AmazingFeature)
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Push to the Branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

We use itm-java-codeformat, so please make sure to apply the correct code format for your contributions.

License

Distributed under the MIT License. See LICENSE file for more information.

Contact

it@M - opensource@muenchen.de