Skip to content

Commit 7306f8a

Browse files
nikolaseunikolaseu
authored
Enrollment for TOTP & SMS (#1)
Enrollment for TOTP & SMS
1 parent d86b67f commit 7306f8a

39 files changed

+3038
-0
lines changed

‎CHANGELOG.md

Whitespace-only changes.

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2017 Auth0, Inc. <support@auth0.com> (http://auth0.com)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,111 @@ or Gradle:
2626
compile 'com.auth0:guardian:0.0.1'
2727
```
2828

29+
## Usage
30+
31+
Create an instance of `Guardian` using you Guardian URL:
32+
33+
```java
34+
Guardian guardian = new Guardian("https://<tenant>.guardian.auth0.com");
35+
```
36+
37+
Obtain an enrollment ticket from API2:
38+
39+
```java
40+
String enrollmentTicket = "Ag1qX7vZVBvyTKhFwrkzaCH2M8vn5b6c";
41+
```
42+
43+
### Enrollment
44+
45+
#### TOTP
46+
47+
Use the ticket and `EnrollmentType.TOTP()` to request an TOTP enrollment.
48+
For TOTP you must ask for the TOTP URI to show to the user in the QR code.
49+
50+
```java
51+
Transaction enrollmentTransaction;
52+
try {
53+
enrollmentTransaction = guardian
54+
.requestEnroll(enrollmentTicket, EnrollmentType.TOTP());
55+
56+
// Only for TOTP: use the TOTP URI to create a QR and scan with an app
57+
String totpURI = enrollmentTransaction.totpURI("Username", "Issuer");
58+
System.out.println(totpURI);
59+
60+
} catch (IOException e) {
61+
// connection issue, might be internet (or invalid certificates for example)
62+
} catch (GuardianException e) {
63+
if (e.isAlreadyEnrolled()) {
64+
// the user was already enrolled
65+
} else if (e.isInvalidToken()) {
66+
// the ticket is not valid anymore, or was already used
67+
} else {
68+
// some other guardian error, check the message
69+
}
70+
}
71+
```
72+
73+
#### SMS
74+
75+
For SMS use `EnrollmentType.SMS()` and the phone number instead:
76+
77+
```java
78+
Transaction enrollmentTransaction;
79+
try {
80+
enrollmentTransaction = guardian
81+
.requestEnroll(enrollmentTicket, EnrollmentType.SMS("+5493424217158"));
82+
83+
} catch (IOException e) {
84+
// connection issue, might be internet (or invalid certificates for example)
85+
} catch (GuardianException e) {
86+
if (e.isAlreadyEnrolled()) {
87+
// the user was already enrolled
88+
} else if (e.isInvalidToken()) {
89+
// the ticket is not valid anymore, or was already used
90+
} else {
91+
// some other guardian error, check the message
92+
}
93+
}
94+
```
95+
96+
### Transaction storage
97+
98+
`Transaction` implements `java.io.Serializable` interface so you can save and restore it easily.
99+
100+
> The transaction contains sensitive information like the transaction token and the recovery code. Keep in mind this
101+
> when considering possible storage options.
102+
103+
### Confirm enrollment
104+
105+
Restore the enrollment transaction from wherever you saved it, and use it together with the OTP that the user inputs to
106+
confirm the enrollment, whether it's TOTP or SMS.
107+
108+
If the OTP was valid, the enrollment is confirmed and you get an object that contains the recovery code.
109+
110+
```java
111+
// get the OTP from SMS or TOTP app
112+
String code = "123456";
113+
114+
try {
115+
Enrollment enrollment = guardian.confirmEnroll(enrollmentTransaction, code);
116+
117+
// Get the recovery code and show to the user
118+
String recoveryCode = enrollment.getRecoveryCode();
119+
System.out.println(recoveryCode);
120+
121+
} catch (IOException e) {
122+
// connection issue, might be internet (or invalid certificates for example)
123+
} catch (GuardianException e) {
124+
if (e.isInvalidToken()) {
125+
// the transaction is not valid anymore
126+
} else if (e.isInvalidOTP()) {
127+
// the OTP is not valid
128+
} else {
129+
// some other guardian error, check the message
130+
}
131+
}
132+
```
133+
29134
## Documentation
30135

31136
For more information about [auth0](http://auth0.com) check our [documentation page](http://docs.auth0.com/).

‎build.gradle

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
group = 'com.auth0'
2+
3+
apply plugin: 'com.auth0.gradle.oss-library.java'
4+
apply plugin: 'jacoco'
5+
6+
logger.lifecycle("Using version ${version} for ${name}")
7+
8+
oss {
9+
name 'guardian'
10+
repository 'guardian-java'
11+
organization 'auth0'
12+
description 'Java library for Auth0\'s Guardian platform.'
13+
14+
developers {
15+
auth0 {
16+
displayName = 'Auth0'
17+
email = 'oss@auth0.com'
18+
}
19+
nikolaseu {
20+
displayName = 'Nicolas Ulrich'
21+
email = 'nicolas.ulrich@auth0.com'
22+
}
23+
}
24+
}
25+
26+
jacocoTestReport {
27+
reports {
28+
xml.enabled = true
29+
html.enabled = true
30+
}
31+
}
32+
33+
compileJava {
34+
sourceCompatibility '1.7'
35+
targetCompatibility '1.7'
36+
}
37+
38+
buildscript {
39+
repositories {
40+
maven {
41+
url "https://plugins.gradle.org/m2/"
42+
}
43+
}
44+
dependencies {
45+
classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.7'
46+
classpath "gradle.plugin.com.auth0.gradle:oss-library:0.6.0"
47+
}
48+
}
49+
50+
repositories {
51+
mavenCentral()
52+
}
53+
54+
test {
55+
testLogging {
56+
events "skipped", "failed"
57+
exceptionFormat "short"
58+
}
59+
}
60+
61+
dependencies {
62+
compile 'com.squareup.okhttp3:okhttp:3.6.0'
63+
compile 'com.squareup.okhttp3:logging-interceptor:3.6.0'
64+
compile 'com.fasterxml.jackson.core:jackson-databind:2.8.7'
65+
66+
testCompile 'org.mockito:mockito-core:2.5.4'
67+
testCompile 'com.squareup.okhttp3:mockwebserver:3.6.0'
68+
testCompile 'org.hamcrest:java-hamcrest:2.0.0.0'
69+
testCompile 'junit:junit:4.11'
70+
}

‎gradle/wrapper/gradle-wrapper.jar

52.3 KB
Binary file not shown.

‎gradle/wrapper/gradle-wrapper.properties

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#Tue Jan 03 13:42:16 ART 2017
2+
distributionBase=GRADLE_USER_HOME
3+
distributionPath=wrapper/dists
4+
zipStoreBase=GRADLE_USER_HOME
5+
zipStorePath=wrapper/dists
6+
distributionUrl=https\://services.gradle.org/distributions/gradle-2.13-all.zip

‎gradlew

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
#!/usr/bin/env bash
2+
3+
##############################################################################
4+
##
5+
## Gradle start up script for UN*X
6+
##
7+
##############################################################################
8+
9+
# Attempt to set APP_HOME
10+
# Resolve links: $0 may be a link
11+
PRG="$0"
12+
# Need this for relative symlinks.
13+
while [ -h "$PRG" ] ; do
14+
ls=`ls -ld "$PRG"`
15+
link=`expr "$ls" : '.*-> \(.*\)$'`
16+
if expr "$link" : '/.*' > /dev/null; then
17+
PRG="$link"
18+
else
19+
PRG=`dirname "$PRG"`"/$link"
20+
fi
21+
done
22+
SAVED="`pwd`"
23+
cd "`dirname \"$PRG\"`/" >/dev/null
24+
APP_HOME="`pwd -P`"
25+
cd "$SAVED" >/dev/null
26+
27+
APP_NAME="Gradle"
28+
APP_BASE_NAME=`basename "$0"`
29+
30+
# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
31+
DEFAULT_JVM_OPTS=""
32+
33+
# Use the maximum available, or set MAX_FD != -1 to use that value.
34+
MAX_FD="maximum"
35+
36+
warn ( ) {
37+
echo "$*"
38+
}
39+
40+
die ( ) {
41+
echo
42+
echo "$*"
43+
echo
44+
exit 1
45+
}
46+
47+
# OS specific support (must be 'true' or 'false').
48+
cygwin=false
49+
msys=false
50+
darwin=false
51+
nonstop=false
52+
case "`uname`" in
53+
CYGWIN* )
54+
cygwin=true
55+
;;
56+
Darwin* )
57+
darwin=true
58+
;;
59+
MINGW* )
60+
msys=true
61+
;;
62+
NONSTOP* )
63+
nonstop=true
64+
;;
65+
esac
66+
67+
CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
68+
69+
# Determine the Java command to use to start the JVM.
70+
if [ -n "$JAVA_HOME" ] ; then
71+
if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
72+
# IBM's JDK on AIX uses strange locations for the executables
73+
JAVACMD="$JAVA_HOME/jre/sh/java"
74+
else
75+
JAVACMD="$JAVA_HOME/bin/java"
76+
fi
77+
if [ ! -x "$JAVACMD" ] ; then
78+
die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
79+
80+
Please set the JAVA_HOME variable in your environment to match the
81+
location of your Java installation."
82+
fi
83+
else
84+
JAVACMD="java"
85+
which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
86+
87+
Please set the JAVA_HOME variable in your environment to match the
88+
location of your Java installation."
89+
fi
90+
91+
# Increase the maximum file descriptors if we can.
92+
if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then
93+
MAX_FD_LIMIT=`ulimit -H -n`
94+
if [ $? -eq 0 ] ; then
95+
if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
96+
MAX_FD="$MAX_FD_LIMIT"
97+
fi
98+
ulimit -n $MAX_FD
99+
if [ $? -ne 0 ] ; then
100+
warn "Could not set maximum file descriptor limit: $MAX_FD"
101+
fi
102+
else
103+
warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
104+
fi
105+
fi
106+
107+
# For Darwin, add options to specify how the application appears in the dock
108+
if $darwin; then
109+
GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
110+
fi
111+
112+
# For Cygwin, switch paths to Windows format before running java
113+
if $cygwin ; then
114+
APP_HOME=`cygpath --path --mixed "$APP_HOME"`
115+
CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
116+
JAVACMD=`cygpath --unix "$JAVACMD"`
117+
118+
# We build the pattern for arguments to be converted via cygpath
119+
ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
120+
SEP=""
121+
for dir in $ROOTDIRSRAW ; do
122+
ROOTDIRS="$ROOTDIRS$SEP$dir"
123+
SEP="|"
124+
done
125+
OURCYGPATTERN="(^($ROOTDIRS))"
126+
# Add a user-defined pattern to the cygpath arguments
127+
if [ "$GRADLE_CYGPATTERN" != "" ] ; then
128+
OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
129+
fi
130+
# Now convert the arguments - kludge to limit ourselves to /bin/sh
131+
i=0
132+
for arg in "$@" ; do
133+
CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
134+
CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option
135+
136+
if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition
137+
eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
138+
else
139+
eval `echo args$i`="\"$arg\""
140+
fi
141+
i=$((i+1))
142+
done
143+
case $i in
144+
(0) set -- ;;
145+
(1) set -- "$args0" ;;
146+
(2) set -- "$args0" "$args1" ;;
147+
(3) set -- "$args0" "$args1" "$args2" ;;
148+
(4) set -- "$args0" "$args1" "$args2" "$args3" ;;
149+
(5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
150+
(6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
151+
(7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
152+
(8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
153+
(9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
154+
esac
155+
fi
156+
157+
# Split up the JVM_OPTS And GRADLE_OPTS values into an array, following the shell quoting and substitution rules
158+
function splitJvmOpts() {
159+
JVM_OPTS=("$@")
160+
}
161+
eval splitJvmOpts $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS
162+
JVM_OPTS[${#JVM_OPTS[*]}]="-Dorg.gradle.appname=$APP_BASE_NAME"
163+
164+
exec "$JAVACMD" "${JVM_OPTS[@]}" -classpath "$CLASSPATH" org.gradle.wrapper.GradleWrapperMain "$@"

0 commit comments

Comments
 (0)