diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 67bf42f2..d10b351d 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -28,7 +28,7 @@ It is recommended to start using device-link authentication flows from Smart-ID 3. Replace showing verification code with showing device link or QR-code. Recommended to use device link for same device and QR-code for cross-device authentication. - [Create device link or QR-code](README.md#generating-qr-code-or-device-link) from values in session response and display it to the user. QR-code should be recreated after every second. 4. Querying session status can be done in parallel while displaying device content. Check out [session status poller](README.md#example-of-using-session-status-poller-to-query-final-sessions-status). `ee.sk.smartid.SmartIdClient` provides method `getSessionsStatusPoller()` to get version specific session status poller. -5. When session status state is `COMPLETE` polling will be stopped and [response should be checked](README.md#example-of-validating-the-authentication-sessions-response) with `AuthenticationResponseValidator`. It will validate required fields, certificate and signature value in sessions status, and it will also handler errors. +5. When session status state is `COMPLETE` polling will be stopped and [response should be checked](README.md#example-of-validating-the-authentication-sessions-response) with `DeviceLinkAuthenticationResponseValidator` or `NotificationAuthenticationResponseValidator` (depending on the flow). They will validate required fields, certificate and signature value in sessions status, and they will also handle errors. 6. If everything is ok `AuthenticationIdentity` will be returned. AuthenticationIdentity is same as used for V2. ## Migrating signing diff --git a/README.md b/README.md index 80a7df8a..9fadd696 100644 --- a/README.md +++ b/README.md @@ -230,8 +230,8 @@ Anonymous authentication is a new feature in Smart-ID API v3.1. It allows to aut RP can learn the user's identity only after the user has authenticated themselves. ```java -// For security reasons a new hash value must be created for each new authentication request -String rpChallenge = RpChallengeGenerator.generate(); +// For security reasons a new RP challenge must be created for each new authentication request +RpChallenge rpChallenge = RpChallengeGenerator.generate(); // Store generated rpChallenge only on backend side. Do not expose it to the client side. // Used for validating authentication sessions status OK response @@ -239,7 +239,7 @@ String rpChallenge = RpChallengeGenerator.generate(); DeviceLinkAuthenticationSessionRequestBuilder builder = smartIdClient .createDeviceLinkAuthentication() // to use anonymous authentication, do not set semantics identifier or document number - .withRpChallenge(rpChallenge) + .withRpChallenge(rpChallenge.toBase64EncodedValue()) .withInteractions(Collections.singletonList( DeviceLinkInteraction.displayTextAndPin("Logging into ") // Display text should be concise and specific. )); @@ -794,7 +794,8 @@ if ("RUNNING".equalsIgnoreCase(sessionStatus.getState())) { ### Validating session status response It's important to validate the session status response to ensure that the returned signature or authentication result is valid. -For validating authentication session status response, use the `AuthenticationResponseValidator`. +For validating authentication session status response, use `DeviceLinkAuthenticationResponseValidator` for device link flows +and `NotificationAuthenticationResponseValidator` for notification-based flows. For validating signature session status response, use the `SignatureResponseValidator`. NB! Integrators must validate signature value against expected signature value. @@ -802,7 +803,7 @@ NB! Integrators must validate signature value against expected signature value. CertificateValidator will check if the certificate is not expired and is trusted by constructing certificate chain with trust anchors and intermediate CA certificates provided in the TrustedCACertStore. -Will be used by AuthenticationResponseValidator and SignatureResponseValidator. +Will be used by DeviceLinkAuthenticationResponseValidator, NotificationAuthenticationResponseValidator, CertificateChoiceResponseValidator and SignatureResponseValidator. ```java // Set up TrustedCACertStore @@ -837,11 +838,12 @@ CertificateValidator certificateValidator = new CertificateValidatorImpl(trusted DeviceLinkAuthenticationResponseValidator depends on CertificateValidator. Checkout [setting up CertificateValidator](#set-up-certificatevalidator) ```java -// Set up AuthenticationResponseValidator with the CertificateValidator -DeviceLinkAuthenticationResponseValidator deviceLinkAuthenticationResponseValidator = new AuthenticationResponseValidator(certificateValidator); +// Set up DeviceLinkAuthenticationResponseValidator with the CertificateValidator +DeviceLinkAuthenticationResponseValidator deviceLinkAuthenticationResponseValidator = + DeviceLinkAuthenticationResponseValidator.defaultSetupWithCertificateValidator(certificateValidator); // Create authentication request builder -DeviceLinkAuthenticationSessionRequestBuilder authenticationRequestBuilder = smartIdClient.createDeviceLinkAuthentication()...; +DeviceLinkAuthenticationSessionRequestBuilder authenticationRequestBuilder = smartIdClient.createDeviceLinkAuthentication()...; // Initialize session DeviceLinkSessionResponse sessionResponse = authenticationRequestBuilder.initAuthenticationSession(); // Get request used for starting the authentication session and use it later to validate sessions status response @@ -852,9 +854,13 @@ SessionStatusPoller poller = smartIdClient.getSessionStatusPoller(); SessionStatus sessionStatus = poller.fetchFinalSessionStatus(sessionResponse.sessionID()); // validate sessions state is completed -if("COMPLETE".equals(sessionStatus.getState())){ +if ("COMPLETE".equals(sessionStatus.getState())) { + // For same-device flows (Web2App/App2App), get userChallengeVerifier from callback URL + String userChallengeVerifier = ""; + // validate the session status response with authentication session request and return authentication identity - AuthenticationIdentity authenticationIdentity = deviceLinkAuthenticationResponseValidator.validate(sessionStatus, authenticationSessionRequest, "smart-id-demo"); + AuthenticationIdentity authenticationIdentity = + deviceLinkAuthenticationResponseValidator.validate(sessionStatus, authenticationSessionRequest, userChallengeVerifier, "smart-id-demo"); } ``` @@ -863,11 +869,12 @@ if("COMPLETE".equals(sessionStatus.getState())){ NotificationAuthenticationResponseValidator depends on CertificateValidator. Checkout [setting up CertificateValidator](#set-up-certificatevalidator) ```java -// Set up AuthenticationResponseValidator with the CertificateValidator -NotificationAuthenticationResponseValidator notificationAuthenticationResponseValidator = new AuthenticationResponseValidator(certificateValidator); +// Set up NotificationAuthenticationResponseValidator with the CertificateValidator +NotificationAuthenticationResponseValidator notificationAuthenticationResponseValidator = + NotificationAuthenticationResponseValidator.defaultSetupWithCertificateValidator(certificateValidator); // Create authentication request builder -NotificationAuthenticationSessionRequestBuilder authenticationRequestBuilder = smartIdClient.createDeviceLinkAuthentication()...; +NotificationAuthenticationSessionRequestBuilder authenticationRequestBuilder = smartIdClient.createNotificationAuthentication()...; // Initialize session NotificationAuthenticationSessionResponse sessionResponse = authenticationRequestBuilder.initAuthenticationSession(); // Get request used for starting the authentication session and use it later to validate sessions status response @@ -878,9 +885,10 @@ SessionStatusPoller poller = smartIdClient.getSessionStatusPoller(); SessionStatus sessionStatus = poller.fetchFinalSessionStatus(sessionResponse.sessionID()); // validate sessions state is completed -if("COMPLETE".equals(sessionStatus.getState())){ +if ("COMPLETE".equals(sessionStatus.getState())) { // validate the session status response with authentication session request and return authentication identity - AuthenticationIdentity authenticationIdentity = notificationAuthenticationResponseValidator.validate(sessionStatus, authenticationSessionRequest, "smart-id-demo"); + AuthenticationIdentity authenticationIdentity = + notificationAuthenticationResponseValidator.validate(sessionStatus, authenticationSessionRequest, "smart-id-demo"); } ```