@@ -26,6 +26,111 @@ or Gradle:
2626compile '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
31136For more information about [ auth0] ( http://auth0.com ) check our [ documentation page] ( http://docs.auth0.com/ ) .
0 commit comments