Use a TOTP authenticator

Before you begin

1. Create an Alibaba Cloud account, complete real-name verification, create a Secure Authentication instance, and then create an application for the instance.

2. Obtain an AccessKey pair of the Alibaba Cloud account.

3. Make sure that you select TOTP as the authentication method for your application. For more information, see Change the authentication method for an application.

4. Download the SDK and demo.

CreateAuthenticatorRegistration

Initializes TOTP authenticator registration. This operation returns a parameter object that is required to register a TOTP authenticator.

Request parameters

Parsing the RegistrationContext parameter

Returned Data

Examples

Request method: POST

https://idaas-doraemon.aliyuncs.com/?Action=CreateAuthenticatorRegistration
&Version=2021-05-20
&ApplicationExternalId=A0000001
&AuthenticatorType=TOTP
&UserId=user-test-1
&UserName=user-test-1
&UserDisplayName=user-test-1
&RegistrationContext=eyJhcHBJ...biI6IjEuMCJ9
&<Common request parameters>

Sample success response

{
  "Success": true,
  "Code": "Operation.Success",
  "Message": "Operation.Success",
  "RequestId": "337848D2-FF8A-4EDD-BD4D-1B9BC80E58B6",
  "Data": {
  "challengeBase64": "MGVhMGViYzYzNjc4YWZlYzMxYmIzODUxYTlhNzViMjFHdU5kMjIySjZtYw==",
    "options": "{\"algorithm\":\"HmacSHA1\",\"encodedSeed\":\"xxxxxx\",\"period\":30,\"seedEncodedFormat\":\"GOOGLE_QR\",\"user\":{\"displayName\":\"\",\"id\":\"2ue3bxdsbaofhns7x290bkn0u83whndincma\",\"name\":\"\"}}"
  }
}

Sample error response for a missing authentication method identity in request parameters

{
  "Success": false,
  "Code": "Params.Blank",
  "Message": "Params.Blank.APIInvokeParams.AuthenticatorType",
  "RequestId": "1C0EE50A-B3BB-42FD-AB59-E3FE88976982",
  "Data":null
}

TOTP Authenticator Registration and Authentication

Registers a TOTP authenticator. This operation verifies the validity of the authenticator and binds a user ID to the authenticator.

Scenarios:

A user has logged on to a PC client and enables TOTP authentication.

Request parameters

Parsing the RegistrationContext parameter

Return value

Examples

Request method: POST

https://idaas-doraemon.aliyuncs.com/?Action=RegisterAuthenticator
&Version=2021-05-20
&ApplicationExternalId=A0000001
&AuthenticatorType=TOTP
&UserId=user-test-1
&AuthenticatorName=user-test-1
&RequireChallengeBase64="MGVhMGViYzYzNjc4YWZlYzMxYmIzODUxYTlhNzViMjFHdU5kMjIySjZtYw=="
&RegistrationContext="{\"base64Challenge\":\"MGVhMGViYzYzNjc4YWZlYzMxYmIzODUxYTlhNzViMjFHdU5kMjIySjZtYw==\",\"otpCode\":\"123456\"}"
&UserSourceIp=1.1.X.X
&<Common request parameters>

Sample response for a successful TOTP authenticator registration

{
  "Success": true,
  "Code": "Operation.Success",
  "Message": "Operation.Success",
  "RequestId": "337848D2-FF8A-4EDD-BD4D-1B9BC80E58B6",
  "Data": {
  "authenticatorUuid": "1C0EE50AB3BB42FDAB59E3FE88976982"
  }
}

Example of an error response: The authentication method identifier is missing from the request parameters.

{
  "Success": false,
  "Code": "Params.Blank",
  "Message": "Params.Blank.APIInvokeParams.AuthenticatorType",
  "RequestId": "1C0EE50A-B3BB-42FD-AB59-E3FE88976982",
  "Data":null
}

TOTP authenticator - Authentication

Requests TOTP authentication for logon or sensitive operations.

Request parameters

Parsing the ServerExtendParamsJson parameter

Returned data

Request example

Request method: POST

https://idaas-doraemon.aliyuncs.com/?Action=ServiceInvoke
&Version=2021-05-20
&ApplicationExternalId=A0000001
&AuthenticatorType=TOTP
&UserId=user-test-1
&Action=VerifyOTP
&ServerExtendParamsJson=eyJwaG9uZU51bWJlciI6IjAwMDAwMDAwMDAwIn0=
&UserSourceIp=1.1.X.X

Successful response for TOTP authenticator registration

{
  "Success": true,
  "Code": "Operation.Success",
  "Message": "Operation.Success",
  "RequestId": "337848D2-FF8A-4EDD-BD4D-1B9BC80E58B6",
  "Data":"{\"state\":\"7d36722302b6b323ba28fc064e91d56aq88S6Zih4Bq\"}"
}

Example error response: Missing authentication method identity parameter

{
  "Success": false,
  "Code": "Params.Blank",
  "Message": "Params.Blank.APIInvokeParams.AuthenticatorType",
  "RequestId": "1C0EE50A-B3BB-42FD-AB59-E3FE88976982",
  "Data":null
}

Sample code in Java

To import the server-side SDK package into a Java Maven project, add the following coordinates.

  <dependency>
   <groupId>com.aliyun</groupId>
   <artifactId>aliyun-java-sdk-idaas-doraemon</artifactId>
   <version>1.2.4</version>
  </dependency>

The following sample code provides an example on how to use a TOTP authenticator:

import com.alibaba.fastjson.JSONObject;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.idaas_doraemon.model.v20210520.*;
import com.aliyuncs.profile.DefaultProfile;

import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class IDaaSAuthSample {
    /**
     * Initializes the client using an AccessKey pair.
     *
     * @param accessKeyId
     * @param accessKeySecret
     * @return Client
     * @throws Exception
     */
    public static IAcsClient createClient(String accessKeyId, String accessKeySecret) throws Exception {
       // An Alibaba Cloud account AccessKey has full permissions on all APIs, which poses a high security risk. We strongly recommend that you create and use a RAM user for API access or daily O&M. Log on to the RAM console to create a RAM user.
        // This example shows how to store the AccessKey pair in environment variables. You can also store them in a configuration file as needed.
        // We strongly recommend that you do not hard-code the AccessKey pair in your code. This can lead to security risks.
      	String accessKeyId = System.getenv("ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ACCESS_KEY_SECRET");
        DefaultProfile profile = DefaultProfile.getProfile(
                "cn-hangzhou",
                accessKeyId,
                accessKeySecret);
        // addEndpoint
        DefaultProfile.addEndpoint("cn-hangzhou",
                "idaas-doraemon",
                "idaas-doraemon.aliyuncs.com");
        // The endpoint to access.
        return new DefaultAcsClient(profile);
    }

    public static void main(String[] args_) throws Exception {
        // Initialize TOTP authenticator registration.
        registerInit();
        // Register the TOTP authenticator.
        registerVerify();
        // Perform TOTP authentication.
        totpVerify();
    }

    public void registerInit() throws Exception {
        IAcsClient client = IDaaSAuthSample.createClient("Your AccessKey", "Your AccessSecret");
        //Initialize TOTP authenticator registration.
        CreateAuthenticatorRegistrationRequest request = new CreateAuthenticatorRegistrationRequest();
                request.setApplicationExternalId("testApplication");
                request.setAuthenticatorType("TOTP");
                request.setUserId("1232312312");
                request.setUserName("1232312312");
                request.setUserDisplayName("1232312312");
                request.setRegistrationContext("{\"algorithm\":\"HmacSHA1\",\"keySeedRespMode\":\"GOOGLE_QR\",\"qrCodeImgWidth\":200,\"qrCodeImgHeight\":200,\"issuer\":\"AliIDaaSSecurityAuth\"}");
        // Print the API response to view the result.
        try {
            CreateAuthenticatorRegistrationResponse response = client.getAcsResponse(request);
            System.out.println(response.getChallengeBase64());
        } catch (Exception e) {
            //Determine the cause of the exception from e.getCode().
            System.out.println(e);
        }

   }

    public void registerVerify() throws Exception {
         IAcsClient client = IDaaSAuthSample.createClient("Your AccessKey", "Your AccessSecret");
        //Verify TOTP authenticator registration.
        RegisterAuthenticatorRequest request = new RegisterAuthenticatorRequest();
                request.setApplicationExternalId("testApplication");
                request.setAuthenticatorType("TOTP");
                request.setUserId("1232312312");
                request.setAuthenticatorName("Test Authenticator");
                request.setRequireChallengeBase64("MjY1M2I3OTA1NWEwMDY2YmYxN2Y1YjA3NDdkZTM5NjdOSHVIU3c2czhPaQ==");
                request.setRegistrationContext("{\"base64Challenge\":\"MjY1M2I3OTA1NWEwMDY2YmYxN2Y1YjA3NDdkZTM5NjdOSHVIU3c2czhPaQ==\",\"otpCode\":\"304288\"}");
                request.setUserSourceIp("47.100.XX.XX");
        // Print the API response to view the result.
        try {
            RegisterAuthenticatorResponse response = client.getAcsResponse(request);
            System.out.println(response.getAuthenticatorUuid());
        } catch (Exception e) {
            //Determine the cause of the exception from e.getCode().
            System.out.println(e);
        }
    }

    public void totpVerify() throws Exception {
        IAcsClient client = IDaaSAuthSample.createClient("Your AccessKey", "Your AccessSecret");
        //Verify with the TOTP authenticator.
        ServiceInvokeRequest request = new ServiceInvokeRequest();
                request.setApplicationExternalId("testApplication");
                request.setServiceCode("TOTP");
                request.setDoraemonAction("VerifyOTP");
                request.setServerExtendParamsJson("eyJ1bmlxdWVJZCI6InVzZXJpZC10ZXN0LTEiLCJjb2RlIjoiMTIzNDU2IiwidW5pcXVlSWRUeXBlIjoiVVNFUl9JRCIsInZlcmlmeU1vZGUiOiJQTEFJTiJ9");
              // Print the API response to view the result.
        try {
            ServiceInvokeResponse response = client.getAcsResponse(request);
            System.out.println(response.getData());
        } catch (Exception e) {
            //Determine the cause of the exception from e.getCode().
            System.out.println(e);
        }
    }
}

Maven dependencies of the sample code

  <dependency>
   <groupId>com.aliyun</groupId>
   <artifactId>aliyun-java-sdk-idaas-doraemon</artifactId>
   <version>1.2.4</version>
  </dependency>
  <dependency>
   <groupId>com.aliyun</groupId>
   <artifactId>aliyun-java-sdk-core</artifactId>
   <optional>true</optional>
   <version>[4.4.9,5.0.0)</version>
  </dependency>