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 itatm/ad2image to run ad2image as a standalone application.

docker run -d -p 8080:8080 --name ad2image itatm/ad2image:1.0.4

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).

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 [...]

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!

Open an issue with the tag "enhancement"
Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
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

it-at-m/ad2image