Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 37 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ For rate limiting information, please confer to the [API Rate Limits](#api-rate-

### OTP Authentication

Send a user a one-time password (OTP) using your preferred delivery method (_email / SMS / Voice call / WhatsApp_). An email address or phone number must be provided accordingly.
Send a user a one-time password (OTP) using your preferred delivery method (_email / SMS / Voice call / WhatsApp / instant message_). An email address or phone number must be provided accordingly.

The user can either `sign up`, `sign in` or `sign up or in`

Expand All @@ -130,6 +130,26 @@ try {
}
```

Sign-up can also take login options and a messaging provider or template. Sign-in and sign-up-or-in take the same
provider and template, plus an SSO app and recovery flag:

```java
String maskedPhone = otps.signUp(DeliveryMethod.IM, "+12125551234",
User.builder().phone("+12125551234").recoveryEmail("desmond@descope.com").build(),
SignUpOptions.builder().tenantId("tenant-ID").locale("en").build(),
OTPSignUpOptions.builder().providerId("provider-ID").templateId("template-ID").build());

OTPSignInOptions signInOptions = OTPSignInOptions.builder()
.providerId("provider-ID")
.templateId("template-ID")
.ssoAppId("sso-app-ID")
.useRecovery(false)
.build();
String maskedAddress = otps.signIn(DeliveryMethod.EMAIL, loginId,
LoginOptions.builder().tenantId("tenant-ID").build(), null, signInOptions);
maskedAddress = otps.signUpOrIn(DeliveryMethod.EMAIL, loginId, null, signInOptions);
```

The user will receive a code using the selected delivery method. Verify that code using:

```java
Expand All @@ -143,6 +163,22 @@ try {

The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on [session validation](#session-validation)

`AuthenticationInfo` also carries the cookie settings (`getCookieName()`, `getCookieDomain()`, `getCookiePath()`, `getCookieMaxAge()`, `getCookieExpiration()`) and the other values of the verify response, such as `getTenantSSOID()` and `getTrustedDeviceJwt()`.

To update a logged-in user's email or phone with an OTP, pass the user's refresh token. The update options can set the messaging provider, template, locale, conflict handling and MFA:

```java
UpdateOptions updateOptions = UpdateOptions.builder()
.providerId("provider-ID")
.templateId("template-ID")
.locale("en")
.failOnConflict(true)
.mfa(true) // keep the refresh token's auth methods and add the verified address to them
.build();
String maskedEmail = otps.updateUserEmail(loginId, "new@descope.com", refreshToken, updateOptions);
String maskedPhone = otps.updateUserPhone(DeliveryMethod.SMS, loginId, "+12125551234", refreshToken, updateOptions);
```

### Magic Link

Send a user a Magic Link using your preferred delivery method (_email / SMS / WhatsApp_).
Expand Down
4 changes: 3 additions & 1 deletion src/main/java/com/descope/enums/DeliveryMethod.java
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ public enum DeliveryMethod {
EMAIL("email"),
SMS("sms"),
VOICE("voice"),
WHATSAPP("whatsapp");
WHATSAPP("whatsapp"),
/** Instant message, supported by OTP only. */
IM("im");

@Getter
private final String value;
Expand Down
13 changes: 13 additions & 0 deletions src/main/java/com/descope/model/auth/AssociatedTenant.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package com.descope.model.auth;

import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
import lombok.AllArgsConstructor;
import lombok.Builder;
Expand All @@ -14,4 +15,16 @@ public class AssociatedTenant {
private String tenantId;
private String tenantName;
private List<String> roleNames;
// Response only: never sent back when a loaded tenant is reused in a request
@JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
private List<String> permissions;
/** Role IDs, not in the same order as roleNames. */
@JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
private List<String> roleIds;

public AssociatedTenant(String tenantId, String tenantName, List<String> roleNames) {
this.tenantId = tenantId;
this.tenantName = tenantName;
this.roleNames = roleNames;
}
}
54 changes: 54 additions & 0 deletions src/main/java/com/descope/model/auth/AuthenticationInfo.java
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
package com.descope.model.auth;

import com.descope.model.jwt.Token;
import com.descope.model.jwt.response.JWTResponse;
import com.descope.model.user.response.UserResponse;
import java.util.Map;
import lombok.AllArgsConstructor;
import lombok.Data;

Expand All @@ -13,8 +15,60 @@ public class AuthenticationInfo {
private UserResponse user;
private Boolean firstSeen;
private IDPResponse idpResponse;
private String cookieDomain;
private String cookiePath;
private Integer cookieMaxAge;
/** Cookie expiration in unix seconds. */
private Integer cookieExpiration;
private Integer sessionExpiration;
private String externalToken;
private Map<String, Object> claims;
private String tenantSSOID;
private String trustedDeviceJwt;
private Integer nextRefreshSeconds;
private String cookieName;
private String sessionCookieName;
private String sessionCookieDomain;
private Boolean unsavedSSO;
private String knownDeviceJwt;
/** Set when an authentication-only SSO verified the person without creating or signing in a user. */
private Boolean ssoAuthenticationOnly;
private Boolean userCreationDeferred;

public AuthenticationInfo(Token token, Token refreshToken, UserResponse user, Boolean firstSeen) {
this(token, refreshToken, user, firstSeen, null);
}

public AuthenticationInfo(Token token, Token refreshToken, UserResponse user, Boolean firstSeen,
IDPResponse idpResponse) {
this.token = token;
this.refreshToken = refreshToken;
this.user = user;
this.firstSeen = firstSeen;
this.idpResponse = idpResponse;
}

/** Builds the authentication info from a JWT response and its already validated tokens. */
public static AuthenticationInfo from(JWTResponse jwtResponse, Token token, Token refreshToken) {
AuthenticationInfo authenticationInfo = new AuthenticationInfo(
token, refreshToken, jwtResponse.getUser(), jwtResponse.getFirstSeen(), jwtResponse.getIdpResponse());
authenticationInfo.setCookieDomain(jwtResponse.getCookieDomain());
authenticationInfo.setCookiePath(jwtResponse.getCookiePath());
authenticationInfo.setCookieMaxAge(jwtResponse.getCookieMaxAge());
authenticationInfo.setCookieExpiration(jwtResponse.getCookieExpiration());
authenticationInfo.setSessionExpiration(jwtResponse.getSessionExpiration());
authenticationInfo.setExternalToken(jwtResponse.getExternalToken());
authenticationInfo.setClaims(jwtResponse.getClaims());
authenticationInfo.setTenantSSOID(jwtResponse.getTenantSSOID());
authenticationInfo.setTrustedDeviceJwt(jwtResponse.getTrustedDeviceJwt());
authenticationInfo.setNextRefreshSeconds(jwtResponse.getNextRefreshSeconds());
authenticationInfo.setCookieName(jwtResponse.getCookieName());
authenticationInfo.setSessionCookieName(jwtResponse.getSessionCookieName());
authenticationInfo.setSessionCookieDomain(jwtResponse.getSessionCookieDomain());
authenticationInfo.setUnsavedSSO(jwtResponse.getUnsavedSSO());
authenticationInfo.setKnownDeviceJwt(jwtResponse.getKnownDeviceJwt());
authenticationInfo.setSsoAuthenticationOnly(jwtResponse.getSsoAuthenticationOnly());
authenticationInfo.setUserCreationDeferred(jwtResponse.getUserCreationDeferred());
return authenticationInfo;
}
}
13 changes: 13 additions & 0 deletions src/main/java/com/descope/model/auth/IDPResponse.java
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,17 @@ public class IDPResponse {
private List<String> idpGroups;
private Map<String, Object> idpSAMLAttributes;
private Map<String, Object> idpOIDCClaims;
private String samlResponse;
private String samlGeneratedUser;
private String samlGeneratedRoles;
private String oidcResponse;
private String oidcGeneratedUser;
private String oidcGeneratedRoles;

public IDPResponse(List<String> idpGroups, Map<String, Object> idpSAMLAttributes,
Map<String, Object> idpOIDCClaims) {
this.idpGroups = idpGroups;
this.idpSAMLAttributes = idpSAMLAttributes;
this.idpOIDCClaims = idpOIDCClaims;
}
}
12 changes: 12 additions & 0 deletions src/main/java/com/descope/model/auth/UpdateOptions.java
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,16 @@
public class UpdateOptions {
private boolean addToLoginIds;
private boolean onMergeUseExisting;
// Fields below are sent by OTP updates only
private String providerId;
private String templateId;
private String locale;
private Boolean failOnConflict;
/** Keep the refresh token's auth methods and add the verified address to them; needs a valid refresh token. */
private Boolean mfa;

public UpdateOptions(boolean addToLoginIds, boolean onMergeUseExisting) {
this.addToLoginIds = addToLoginIds;
this.onMergeUseExisting = onMergeUseExisting;
}
}
28 changes: 28 additions & 0 deletions src/main/java/com/descope/model/jwt/response/JWTResponse.java
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

import com.descope.model.auth.IDPResponse;
import com.descope.model.user.response.UserResponse;
import java.util.Map;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
Expand All @@ -19,10 +20,37 @@ public class JWTResponse {
private UserResponse user;
private Boolean firstSeen;
private IDPResponse idpResponse;
private Integer sessionExpiration;
private String externalToken;
private Map<String, Object> claims;
private String tenantSSOID;
private String trustedDeviceJwt;
private Integer nextRefreshSeconds;
private String cookieName;
private String sessionCookieName;
private String sessionCookieDomain;
private Boolean unsavedSSO;
private String knownDeviceJwt;
/** Set when an authentication-only SSO verified the person without creating or signing in a user. */
private Boolean ssoAuthenticationOnly;
private Boolean userCreationDeferred;

public JWTResponse(String sessionJwt, String refreshJwt, String cookieDomain, String cookiePath,
Integer cookieMaxAge, Integer cookieExpiration, UserResponse user, Boolean firstSeen) {
this(sessionJwt, refreshJwt, cookieDomain, cookiePath, cookieMaxAge, cookieExpiration, user,
firstSeen, null);
}

public JWTResponse(String sessionJwt, String refreshJwt, String cookieDomain, String cookiePath,
Integer cookieMaxAge, Integer cookieExpiration, UserResponse user, Boolean firstSeen, IDPResponse idpResponse) {
this.sessionJwt = sessionJwt;
this.refreshJwt = refreshJwt;
this.cookieDomain = cookieDomain;
this.cookiePath = cookiePath;
this.cookieMaxAge = cookieMaxAge;
this.cookieExpiration = cookieExpiration;
this.user = user;
this.firstSeen = firstSeen;
this.idpResponse = idpResponse;
}
}
12 changes: 12 additions & 0 deletions src/main/java/com/descope/model/magiclink/LoginOptions.java
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ public class LoginOptions {
private String jwt;
private String locale;
private String templateId;
private String ssoAppId;
/** Base64-encoded PKCE challenge, used by enchanted links only. */
private String pkceChallenge;
private String tenantId;

public LoginOptions(boolean stepup, boolean mfa, Map<String, Object> customClaims,
Map<String, String> templateOptions) {
Expand All @@ -41,6 +45,14 @@ public LoginOptions(boolean stepup, boolean mfa, Map<String, Object> customClaim
this.jwt = jwt;
}

public LoginOptions(boolean stepup, boolean mfa, Map<String, Object> customClaims,
Map<String, String> templateOptions, boolean revokeOtherSessions,
String[] revokeOtherSessionsTypes, String jwt, String locale, String templateId) {
this(stepup, mfa, customClaims, templateOptions, revokeOtherSessions, revokeOtherSessionsTypes, jwt);
this.locale = locale;
this.templateId = templateId;
}

public boolean isJWTRequired() {
return this.isStepup() || this.isMfa();
}
Expand Down
10 changes: 10 additions & 0 deletions src/main/java/com/descope/model/magiclink/SignUpOptions.java
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,14 @@
public class SignUpOptions {
private Map<String, Object> customClaims;
private Map<String, String> templateOptions;
private String locale;
/** Base64-encoded PKCE challenge, used by enchanted links only. */
private String pkceChallenge;
private String templateId;
private String tenantId;

public SignUpOptions(Map<String, Object> customClaims, Map<String, String> templateOptions) {
this.customClaims = customClaims;
this.templateOptions = templateOptions;
}
}
18 changes: 18 additions & 0 deletions src/main/java/com/descope/model/otp/OTPSignInOptions.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
package com.descope.model.otp;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

/** Request options for OTP sign-in and sign-up-or-in, sent next to the login options. */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class OTPSignInOptions {
private String providerId;
private String templateId;
private String ssoAppId;
private Boolean useRecovery;
}
16 changes: 16 additions & 0 deletions src/main/java/com/descope/model/otp/OTPSignUpOptions.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
package com.descope.model.otp;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

/** Request options for OTP sign-up, sent next to the sign-up login options. */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class OTPSignUpOptions {
private String providerId;
private String templateId;
}
9 changes: 9 additions & 0 deletions src/main/java/com/descope/model/otp/SignInRequest.java
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,13 @@ public class SignInRequest {

private String loginId;
private LoginOptions loginOptions;
private String providerId;
private String templateId;
private String ssoAppId;
private Boolean useRecovery;

public SignInRequest(String loginId, LoginOptions loginOptions) {
this.loginId = loginId;
this.loginOptions = loginOptions;
}
}
12 changes: 12 additions & 0 deletions src/main/java/com/descope/model/otp/SignUpRequest.java
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,16 @@ public class SignUpRequest {
private String loginId;
private User user;
private SignUpOptions loginOptions;
private String providerId;
private String templateId;

public SignUpRequest(String whatsApp, String phone, String email, String loginId, User user,
SignUpOptions loginOptions) {
this.whatsApp = whatsApp;
this.phone = phone;
this.email = email;
this.loginId = loginId;
this.user = user;
this.loginOptions = loginOptions;
}
}
14 changes: 14 additions & 0 deletions src/main/java/com/descope/model/otp/UpdateEmailRequestBody.java
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,18 @@ public class UpdateEmailRequestBody {
private boolean addToLoginIds;
private boolean onMergeUseExisting;
private Map<String, String> templateOptions;
private String providerId;
private String templateId;
private String locale;
private Boolean failOnConflict;
private Boolean mfa;

public UpdateEmailRequestBody(String email, String loginId, boolean addToLoginIds, boolean onMergeUseExisting,
Map<String, String> templateOptions) {
this.email = email;
this.loginId = loginId;
this.addToLoginIds = addToLoginIds;
this.onMergeUseExisting = onMergeUseExisting;
this.templateOptions = templateOptions;
}
}
14 changes: 14 additions & 0 deletions src/main/java/com/descope/model/otp/UpdatePhoneRequestBody.java
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,18 @@ public class UpdatePhoneRequestBody {
private boolean addToLoginIds;
private boolean onMergeUseExisting;
private Map<String, String> templateOptions;
private String providerId;
private String templateId;
private String locale;
private Boolean failOnConflict;
private Boolean mfa;

public UpdatePhoneRequestBody(String phone, String loginId, boolean addToLoginIds, boolean onMergeUseExisting,
Map<String, String> templateOptions) {
this.phone = phone;
this.loginId = loginId;
this.addToLoginIds = addToLoginIds;
this.onMergeUseExisting = onMergeUseExisting;
this.templateOptions = templateOptions;
}
}
Loading
Loading