Skip to content

Commit 0edb99c

Browse files
Avery-DunnAvery-Dunn
authored
Merge pull request #807 from AzureAD/avdunn/add-persistence-package
Update extensions package and add to main repo
2 parents 15eee53 + f3c3896 commit 0edb99c

36 files changed

+2597
-2
lines changed

‎msal4j-persistence-extension/.gitignore‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Compiled class file
2+
*.class
3+
4+
# Log file
5+
*.log
6+
7+
# BlueJ files
8+
*.ctxt
9+
10+
# Mobile Tools for Java (J2ME)
11+
.mtj.tmp/
12+
13+
# Package Files #
14+
*.jar
15+
*.war
16+
*.nar
17+
*.ear
18+
*.zip
19+
*.tar.gz
20+
*.rar
21+
22+
# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
23+
hs_err_pid*

‎msal4j-persistence-extension/README.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Microsoft Authentication Extensions for Java
2+
3+
The Microsoft Authentication Extensions for Java offers secure mechanisms for client applications to perform cross-platform token cache serialization and persistence. It gives additional support to the [Microsoft Authentication Library for Java (MSAL)](https://github.com/AzureAD/microsoft-authentication-library-for-java).
4+
5+
MSAL Java supports an in-memory cache by default and provides the `ITokenCacheAccessAspect` interface to perform cache serialization. You can read more about this in the MSAL Java [documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-java-token-cache-serialization). Developers are required to implement their own cache persistance across multiple platforms and Microsoft Authentication Extensions makes this simpler.
6+
The extensions library supports persistence of the cache to disk in encrypted form where the platform supports this.
7+
8+
This is available for Windows, Mac and Linux.
9+
- Windows - [DPAPI](https://docs.microsoft.com/en-us/dotnet/standard/security/how-to-use-data-protection) is used for encryption.
10+
- MAC - The MAC KeyChain is used and encryption is built in.
11+
- Linux - [LibSecret](https://wiki.gnome.org/Projects/Libsecret) is used for encryption. Any place where libsecret is not available encryption is not supported.
12+
13+
> Note: It is recommended to use this library for cache persistance support for Public client applications such as Desktop apps only. In web applications, this may lead to scale and performance issues. Web applications are recommended to persist the cache in session. Take a look at this [webapp sample](https://github.com/Azure-Samples/ms-identity-java-webapp).
14+
15+
## Installation
16+
17+
You can find the latest pacakge in the [Maven repository](https://mvnrepository.com/artifact/com.microsoft.azure/msal4j-persistence-extension).
18+
19+
Add the dependecy to the pom file.
20+
21+
```
22+
<dependency>
23+
<groupId>com.microsoft.azure</groupId>
24+
<artifactId>msal4j-persistence-extension</artifactId>
25+
<version>1.2.0</version>
26+
</dependency>
27+
```
28+
29+
## Versions
30+
31+
This library follows [Semantic Versioning](http://semver.org/).
32+
33+
## Usage
34+
35+
[![javadoc](https://javadoc.io/badge2/com.microsoft.azure/msal4j-persistence-extension/javadoc.svg)](https://javadoc.io/doc/com.microsoft.azure/msal4j-persistence-extension)
36+
37+
The Microsoft Authentication Extensions library provides the `PersistenceTokenCacheAccessAspect` which is an implementation of the `ITokenCacheAccessAspect` interface defined in MSAL Java. After configuring this token cache, it can then be used to instantiate the client application in MSAL Java.
38+
39+
The token cache includes a file lock, and auto-reload behavior under the hood.
40+
41+
Here is the usage pattern for multiple platforms:
42+
43+
1. Configure the `PersistenceSettings`.
44+
45+
```java
46+
private PersistenceSettings createPersistenceSettings() throws IOException {
47+
48+
Path path = Paths.get(System.getProperty("user.home"), "MSAL", "testCache");
49+
50+
return PersistenceSettings.builder("testCacheFile", path)
51+
.setMacKeychain("MsalTestService", "MsalTestAccount")
52+
.setLinuxKeyring(null,
53+
"MsalTestSchema",
54+
"MsalTestSecretLabel",
55+
"MsalTestAttribute1Key",
56+
"MsalTestAttribute1Value",
57+
"MsalTestAttribute2Key",
58+
"MsalTestAttribute2Value")
59+
.setLockRetry(1000, 50)
60+
.build();
61+
}
62+
```
63+
64+
1. Create the `PersistenceTokenCacheAccessAspect`.
65+
66+
```java
67+
private ITokenCacheAccessAspect createPersistenceAspect() throws IOException {
68+
return new PersistenceTokenCacheAccessAspect(createPersistenceSettings());
69+
}
70+
```
71+
1. Now you can use `PersistenceTokenCacheAccessAspect` to configure Msal client application:
72+
73+
```java
74+
return PublicClientApplication.builder(PUBLIC_CLIENT_ID)
75+
.authority(AUTHORITY)
76+
.setTokenCacheAccessAspect(createPersistenceAspect())
77+
.build();
78+
```
79+
80+
## Community Help and Support
81+
82+
We leverage Stack Overflow to work with the community on supporting Azure Active Directory and its SDKs, including this one!
83+
We highly recommend you ask your questions on Stack Overflow (we're all on there!).
84+
Also browse existing issues to see if someone has had your question before.
85+
86+
We recommend you use the "msal" tag so we can see it!
87+
Here is the latest Q&A on Stack Overflow for MSAL:
88+
[http://stackoverflow.com/questions/tagged/msal](http://stackoverflow.com/questions/tagged/msal)
89+
90+
91+
## Contributing
92+
93+
All code is licensed under the MIT license and we triage actively on GitHub.
94+
95+
This project welcomes contributions and suggestions. Most contributions require you to agree to a
96+
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
97+
the rights to use your contribution. For details, visit https://cla.microsoft.com.
98+
99+
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
100+
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
101+
provided by the bot. You will only need to do this once across all repos using our CLA.
102+
103+
104+
## We value and adhere to the Microsoft Open Source Code of Conduct
105+
106+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

‎msal4j-persistence-extension/pom.xml‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
<groupId>com.microsoft.azure</groupId>
7+
<artifactId>msal4j-persistence-extension</artifactId>
8+
<version>1.3.0</version>
9+
<packaging>jar</packaging>
10+
<name>msal4j-persistence-extension</name>
11+
<description>
12+
Implementation of ITokenCacheAccessAspect interface defined in Java MSAL SDK (artifactId - msal4j)
13+
for persistence of token cache in platform specific secret storage:
14+
* Win - file encrypted with DPAPI
15+
* Mac - key chain
16+
* Linux - key ring
17+
</description>
18+
<url>https://github.com/AzureAD/microsoft-authentication-library-for-java</url>
19+
<licenses>
20+
<license>
21+
<name>MIT License</name>
22+
</license>
23+
</licenses>
24+
<scm>
25+
<url>https://github.com/AzureAD/microsoft-authentication-library-for-java</url>
26+
</scm>
27+
<developers>
28+
<developer>
29+
<id>ms</id>
30+
<name>Microsoft Corporation</name>
31+
</developer>
32+
</developers>
33+
<properties>
34+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
35+
</properties>
36+
37+
<dependencies>
38+
<dependency>
39+
<groupId>com.microsoft.azure</groupId>
40+
<artifactId>msal4j</artifactId>
41+
<version>1.15.0</version>
42+
</dependency>
43+
44+
<dependency>
45+
<groupId>net.java.dev.jna</groupId>
46+
<artifactId>jna</artifactId>
47+
<version>5.13.0</version>
48+
</dependency>
49+
50+
<dependency>
51+
<groupId>net.java.dev.jna</groupId>
52+
<artifactId>jna-platform</artifactId>
53+
<version>5.13.0</version>
54+
</dependency>
55+
56+
<dependency>
57+
<groupId>org.slf4j</groupId>
58+
<artifactId>slf4j-api</artifactId>
59+
<version>1.7.7</version>
60+
</dependency>
61+
62+
<dependency>
63+
<groupId>junit</groupId>
64+
<artifactId>junit</artifactId>
65+
<version>4.13.1</version>
66+
<scope>test</scope>
67+
</dependency>
68+
</dependencies>
69+
70+
<build>
71+
<plugins>
72+
<plugin>
73+
<groupId>org.apache.maven.plugins</groupId>
74+
<artifactId>maven-compiler-plugin</artifactId>
75+
<version>3.7.0</version>
76+
<configuration>
77+
<source>8</source>
78+
<target>8</target>
79+
</configuration>
80+
</plugin>
81+
82+
<plugin>
83+
<groupId>org.apache.maven.plugins</groupId>
84+
<artifactId>maven-jar-plugin</artifactId>
85+
<version>2.5</version>
86+
<configuration>
87+
<archive>
88+
<manifest>
89+
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
90+
<addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
91+
</manifest>
92+
</archive>
93+
</configuration>
94+
</plugin>
95+
96+
<plugin>
97+
<groupId>org.apache.maven.plugins</groupId>
98+
<artifactId>maven-surefire-plugin</artifactId>
99+
<version>2.10</version>
100+
<configuration>
101+
<argLine>-noverify</argLine>
102+
</configuration>
103+
</plugin>
104+
105+
<plugin>
106+
<groupId>org.apache.maven.plugins</groupId>
107+
<artifactId>maven-javadoc-plugin</artifactId>
108+
<version>3.1.0</version>
109+
<executions>
110+
<execution>
111+
<id>attach-javadocs</id>
112+
<goals>
113+
<goal>jar</goal>
114+
</goals>
115+
</execution>
116+
</executions>
117+
</plugin>
118+
119+
<plugin>
120+
<groupId>org.apache.maven.plugins</groupId>
121+
<artifactId>maven-source-plugin</artifactId>
122+
<version>2.2.1</version>
123+
<executions>
124+
<execution>
125+
<id>attach-sources</id>
126+
<goals>
127+
<goal>jar</goal>
128+
</goals>
129+
</execution>
130+
</executions>
131+
</plugin>
132+
133+
<plugin>
134+
<groupId>com.github.spotbugs</groupId>
135+
<artifactId>spotbugs-maven-plugin</artifactId>
136+
<version>3.1.11</version>
137+
</plugin>
138+
</plugins>
139+
</build>
140+
</project>

‎msal4j-persistence-extension/src/main/java/com/microsoft/aad/msal4jextensions/CacheFileLockAcquisitionException.java‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
2+
// Licensed under the MIT License.
3+
4+
package com.microsoft.aad.msal4jextensions;
5+
6+
/**
7+
* Exception represents failure/error of acquiring cross process cacheFile lock
8+
* */
9+
public class CacheFileLockAcquisitionException extends RuntimeException {
10+
/**
11+
* Constructor
12+
* @param message Exception details
13+
*/
14+
public CacheFileLockAcquisitionException(String message) {
15+
super(message);
16+
}
17+
}

0 commit comments

Comments
 (0)