Customer Identity (CIAM)

SMS Login

# Documentation

This document explains how to integrate the SMS login functionality in the iOS client. SMS login involves sending an SMS verification code to the user's mobile phone number, and the user authenticates with the IDaaS server using their phone number and the SMS code.

In the SMS login scenario, the user enters their phone number and clicks the "Get SMS Verification Code" button, which triggers a slider verification. After successful verification, the IDaaS backend sends an SMS verification code to that phone number. The user then enters the verification code and clicks "Login". The IDaaS backend authenticates the credentials and returns a token. The final authentication result is returned to the App.

# Process Description

Integration Process Description

The user enters their phone number, and the App client checks if the phone number format is valid. The user clicks "Get Verification Code".
The App client calls the slider verification method. The IDaaS SDK requests slider verification initialization information from the IDaaS backend and displays the slider verification window on the page.
The user drags the slider to complete the verification. The IDaaS SDK collects the slider verification information and requests verification from the IDaaS server.
The IDaaS server successfully completes the slider verification and returns a token to the IDaaS SDK.
The IDaaS SDK uses the token to request the IDaaS server to send the SMS.
The user receives the SMS, enters the verification code, and clicks "Login".
The App client calls the IDaaS SDK's SMS login method with the phone number and verification code.
The IDaaS SDK requests SMS login. The IDaaS server initiates the authentication process. If authentication is successful, it returns a session_token and an id_token to the IDaaS SDK; if unsuccessful, it returns an error code and message to the IDaaS SDK.
The IDaaS SDK obtains the login result and returns it to the App client. The App client proceeds with its own logic based on the result.
The client can use the id_token to verify the login validity period and obtain basic user information.
The client can use the session_token to refresh the id_token.

# Environment Setup

# Obtaining the Application clientID

Log in to the IDaaS Enterprise Center platform, click "Resources -> Applications", select your relevant application, and click to view it.

# Adding Dependencies

No third-party SDK dependencies.

# Adding the Main Libraries

AuthnCenter_common_2C.framework	  
AuthnCenter_SMSLogin_2C.bundle
AuthnCenter_SMSLogin_2C.framework

1
2
3

Drag the IDaaSSDK into the project and import it as follows:

Also, add the Pod dependency.

pod 'JWT', '~> 3.0.0-beta.14'

# Targets Configuration

The minimum iOS version compatible with the IDaaS SMS Login SDK is iOS 10.
Add the following packages in "Frameworks, Libraries, and Embedded Content".
Add the main libraries and dependency packages in "Frameworks, Libraries, and Embedded Content", and add -ObjC to "Other Linker Flags".
In the menu bar, select TARGETS > Info > Custom iOS Target Properties > App Transport Security Settings > Allow Arbitrary Loads, as shown below.
Configure bitcode. As shown below, set bitcode to NO.

# Development Integration

Import the header file:

Import as follows in AppDelegate
#import <AuthnCenter_common_2C /BCIDACommonManager.h>

1
2

# SDK Initialization {/sdk-initialization/}

The IDaaS SDK provides an initialization method where you can fill in the tenant, clientID, and whether to enable log printing.

Example of the initialization method: Call the initialization method within the didFinishLaunchingWithOptions method in AppDelegate.

//1. Basic configuration initialization
[[[[[BCIDACommonManager sharedInstance] initWithDomain:@"https://your-backend-tenant.com"] initWithClientID:@"backend-tenant-clientID"] initWithSSLCerVerification:NO] setLogEnabled:YES] ;

1
2

Introduction to the main class BCIDACommonManager methods for basic configuration initialization:

/**
  * Function name: sharedInstance
   * @param None
   * @return Singleton object instance class
 */
+ (instancetype )sharedInstance ;

/**
  * Function name: initWithDomain
   * @param domain, starting with https:// and ending with .com.
   * @return Instance class
 */
-(BCIDACommonManager)initWithDomain:(NSString)domain

/**
  * Function name: initWithClientID
   * @param client id.
   * @return Instance class
 */
-(BCIDACommonManager)initWithClientID:(NSString)clientID;

/**
  * Function name: setLogEnabled
   * @param Boolean value indicating whether to enable log.
   * @return Instance class
 */
-(void)setLogEnabled:(BOOL)enable;

/**
  * Function name: initWithSSLCerVerification
   * @param Boolean value to set whether SSL certificate verification is enabled.
   * @return Instance class
 */
-(BCIDACommonManager*)initWithSSLCerVerification:(bool)sslCerVerification;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# Calling Sequence {/calling-sequence/}

If international number support is enabled, please first call the international dialing code retrieval interface yourself, bind and display it on the interface, and manually assemble the international dialing code (e.g., +86-13800000000) when passing a phone number to relevant methods; if support is not enabled, ignore this interface.
Call the slider verification and send SMS method (startSlidingVerifyCodePageWithMobileNumber) with the mobile number as the parameter.
Call the SMS login method (loginsBySMSWithMobile) with the mobile number and SMS verification code as parameters.

# Sending SMS Verification {/sending-sms-verification/}

The App client needs to have its own UI interface, which contains several necessary components: a mobile number input field, a verification code input field, a button (or event) to trigger obtaining the verification code, and a login button (or event).

After the user enters the mobile number and before clicking (triggering) the send verification code event, the App client should perform a mobile number format check.
When clicking (triggering) the send verification code event, the App client calls the IDaaS SDK's send verification code method, as shown in the example below:

//Import the request header
#import <AuthnCenter_SMSLogin_2C/BCSMSLoginSlideVerifyCodeManager.h>

//Click (trigger) the send verification code event
  [BCSMSLoginSlideVerifyCodeManager startSlidingVerifyCodePageWithMobileNumber:mobileNumber andWithResultHandler:^(NSString * _Nonnull code, id  _Nonnull data) {
            __strong __typeof(weakSelf)strongSelf = weakSelf;

            dispatch_async(dispatch_get_main_queue(), ^{
            NSLog(@"Slider verification result==%@==%@",code,data);
            
            });
        }];

1
2
3
4
5
6
7
8
9
10
11
12

Introduction to BCSMSLoginSlideVerifyCodeManager Object Methods:

/**
* Function name: startSlidingVerifyCodePageWithMobileNumber
* @brief: Click to initiate the sliding verification. If verification is successful, an SMS is sent. If sliding verification fails, returns code=error code, and data returns the error reason. SMS sending success returns code=0.
*@ param mobile phone number: With country code "+86-13800000000" or without country code "13800000000" are both acceptable.
*@param complete: Asynchronous result callback, code=0 indicates SMS sent successfully, code=other indicates SMS sending failure or sliding verification failure. Please refer to IDaaS error codes and the returned data (string error description). code=105 data="user canceled" indicates the close button of the sliding verification box was clicked, and the sliding verification box was closed.
**/
+(void)startSlidingVerifyCodePageWithMobileNumber:(NSString*)mobile andWithResultHandler:(BCSMSLoginSlideCodeHandlerBlock)resultHandler;

1
2
3
4
5
6
7

After completing the previous verification code sending, the user receives the SMS verification code, enters it into the verification code field, and triggers the login event. At this point, the App client initiates the SMS login process. Example code is as follows:

[[BCLoginSMSManager sharedInstance] loginsBySMSWithMobile:phone number andWithVerifyCode:verification code andWithCompletionHandler:^(NSString * _Nonnull code, id  _Nonnull data) {
        __strong __typeof(weakSelf)strongSelf = weakSelf;

        dispatch_async(dispatch_get_main_queue(), ^{
   //Login success or failure, proceed with redirection
        });
  }];

1
2
3
4
5
6
7

Introduction to the main class BCLoginSMSManager methods:

/**
* Function name: loginsBySMSWithMobile
* @brief: SMS login method
* @param mobile Phone number
*@param verifyCode SMS verification code
* @param BCLoginSMSCompleteHandler () Login result callback function
**/
-(void) loginsBySMSWithMobile:(NSString*)mobile andWithVerifyCode:(NSString*)verifyCode andWithCompletionHandler:(BCLoginSMSCompleteHandler)completeHandler;

1
2
3
4
5
6
7
8

BCLoginSMSCompleteHandler callback function return codes:

code	Description
code=0	Login successful. At this point, data returns an NSDictionary: data=@{@"session_token":sessionToken content,@"id_token":idToken content};
code=1	Login failed. data returns a string describing the error.

# Mobile International Dialing Code Acquisition

If international number support is enabled, please first call the international dialing code acquisition interface. The international dialing code acquisition interface returns the configured list of international dialing codes, along with regular expressions for phone numbers. The following image shows how to configure the international dialing code list and the preferred dialing code.

The IDaaS SDK provides an API for obtaining international dialing codes:

Example code for retrieving the international area code list:

#import <AuthnCenter_common_2C/BCIDAInternationalPhoneCodeManager.h>


[BCIDAInternationalPhoneCodeManager getInternaltionalAreaCodeWithCompletionHandler:^(NSString * _Nonnull code, id  _Nonnull data) {
        __strong __typeof(weakSelf)strongSelf = weakSelf;
        dispatch_async(dispatch_get_main_queue(), ^{
            NSDictionary* dic=(NSDictionary*)data;
        //Check if the phone number matches the regular expression
 BOOL flag=  [strongSelf parseDictionary:dic andWithMoile:mobile];
            
        });
    }];

1
2
3
4
5
6
7
8
9
10
11
12

Main class method introduction:

/**
* Function name: getInternaltionalAreaCodeWithCompletionHandler
* @brief: Method to retrieve international area codes
* @param
*@param
* @param BCSMSGetInternationalAreaCodeHandlerBlock () Result callback function code=0, data returns NSDictionary result
**/
+(void)getInternaltionalAreaCodeWithCompletionHandler:(BCSMSGetInternationalAreaCodeHandlerBlock)resultHander;

1
2
3
4
5
6
7
8

Successful example code=0, data value:

{
	"phoneAreaCodeDefinitions": [
		{
			"areaCode": "86",
			"displayMapping": {
				"zh-TW": "中國大陸",
				"en": "China",
				"zh-CN": "中国大陆"
			},
			"countryCode": "CN",
			"mobileRegex": "^(\\+86){0,1}\\-?1\\d{10}$",
			"areaCodeSuffixes": []
		},
		{
			"areaCode": "852",
			"displayMapping": {
				"zh-TW": "中國香港",
				"en": "Hong Kong",
				"zh-CN": "中国香港"
			},
			"countryCode": "HK",
			"mobileRegex": "^(\\+852){1}\\-?0{0,1}[1,4,5,6,7,8,9](?:\\d{7}|\\d{8}|\\d{12})$",
			"areaCodeSuffixes": []
		},
		{
			"areaCode": "886",
			"displayMapping": {
				"zh-TW": "中國臺灣",
				"en": "Taiwan",
				"zh-CN": "中国台湾"
			},
			"countryCode": "TW",
			"mobileRegex": "^(\\+886){1}\\-?[6,7,9](?:\\d{7}|\\d{8})$",
			"areaCodeSuffixes": []
		},
		{
			"areaCode": "853",
			"displayMapping": {
				"zh-TW": "中國澳門",
				"en": "Macau",
				"zh-CN": "中国澳门"
			},
			"countryCode": "MO",
			"mobileRegex": "^(\\+853){1}\\-?0{0,1}[1,4,5,6,7,8,9](?:\\d{7}|\\d{8}|\\d{12})$",
			"areaCodeSuffixes": []
		},
		{
			"areaCode": "93",
			"displayMapping": {
				"zh-TW": "阿富汗",
				"en": "Afghanistan",
				"zh-CN": "阿富汗"
			},
			"countryCode": "AF",
			"mobileRegex": "^(\\+93){1}\\-\\d{6,11}",
			"areaCodeSuffixes": []
		}
	],
	"preferredAreaCode": "CN"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

Return Parameters:

Parameter Name	Chinese Name	Type	Description
preferredAreaCode	Preferred International Area Code	String	The preferred international area code configured for the current enterprise center.
countryCode	Country/Region Code	String	Country/Region Code
areaCode	International Telephone Area Code	String	International Telephone Area Code
areaCodeSuffixes	International Telephone Area Code Suffix	String	International Telephone Area Code Suffix
mobileRegex	Mobile Number Format Regular Expression	String	Mobile Number Format Regular Expression
displayMapping	Multi-language Display Name Mapping	String	Multi-language Display Name Mapping

# IDToken Verification and User Information Retrieval

Upon successful login, a session_token and an id_token will be returned. The id_token can be used to retrieve user information and verify login validity.

Verify the idToken
Retrieve user information from the idtoken (This method can be called directly without verification)

# Verify id_token {/examples/}

Call Example:

  [[BCIDAIDTokenManager sharedInstance] verifySignWithIdToken:idToken andWithCallBack:^(NSString * _Nonnull code, id  _Nonnull data) {
          }];

1
2

Introduction to the main class BCIDAIDTokenManager:

/**
   * Function name: sharedInstance
   * @param No input parameters
   * @return Returns the singleton instance of the object
*/
+ (instancetype )sharedInstance;

/**
* Function name: verifySignWithIdToken
* @brief: Method to verify whether the idtoken is within the login validity period and matches the application
* @param idToken returned during login
* @param BCIDAIdTokenVerifyHandlerBlock callback function:
NSString code
id       data
**/
-(void)verifySignWithIdToken:(NSString*)idToken andWithCallBack:(BCIDAIdTokenVerifyHandlerBlock)callback;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Return Values:

code(NSString)	data	Data Type and Description of data
0	success	[NSString] Signature verification successful
1	Error description	[NSString] Input parameter is empty, SDK initialization parameters domain and clientID are not set
106	Time expired	[NSString] Expired idtoken
107	clientID does not match	[NSString] Possibly used the clientID of another application
103	Signature verification failed	[NSString] Failure during the signature verification process
102	Public key obtained is empty	[NSString] Error during the signature verification process
See the error code collection at the end of the document	See the error code collection at the end of the document	May also return error codes listed at the end

# Parsing User Information from idToken

Call example:

[[BCIDAIDTokenManager sharedInstance] getUserInfoFromIdTokenWithIdToken:idToken andWithCallBack:^(NSString * _Nonnull code, id  _Nonnull data) {
            
}];

1
2
3

Introduction to the main class BCIDAIDTokenManager:

/**
   * Function name: sharedInstance
   * @param No input parameters
   * @return Returns the singleton instance of the object
*/
+ (instancetype )sharedInstance;

/**
* Function name: getUserInfoFromIdTokenWithIdToken
* @brief: Parse user information from idToken
* @param idToken Returned from login
* @param BCIDAIdTokenGetInfoHandlerBlock Callback function:
NSString code
id       data

**/
-(void)getUserInfoFromIdTokenWithIdToken:(NSString*)idToken andWithCallBack:(BCIDAIdTokenGetInfoHandlerBlock)callback;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

User information parameter description:

Parameter Name	Description
iss	Token Issuer
aud	Token Audience, the application's clientId
exp	Token Expiration Time
jti	Token ID
iat	Token Issued At Time
sub	Fixed as subject
name	User's Name
mobile	User's Mobile Number
id	User's ID
userName	Username
email	User's Email

Callback Function Return Value:

Success Example:
code=0
data=
{
	"id": "20220729174957176-2C7F-A2C54C293",
	"exp": 1659407592,
	"nbf": 1659407172,
	"mobile": "+86-13808603636",
	"jti": "7iwCYPo8EYcmLAD18x-CAw",
	"iss": "https:\/\/sdk2c.idaas-test-alpha.bccastle.com\/api\/v1\/oauth2",
	"userName": "zhangrui1",
	"sub": "20220729174957176-2C7F-A2C54C293",
	"aud": "S1ScicdIVR1QUbNs8TBz6BYVd2Zt8Adc",
	"iat": 1659407292,
	"email": "",
	"name": "zhangrui1"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Refresh IDToken

Call Example:

[[BCIDAIDTokenRefreshManager sharedInstance] refreshIdTokenWithSessionToken:sessionToken andWithCallBack:^(NSString * _Nonnull code, id  _Nonnull data) {
            NSString* jsonS=(NSString*)data;
         NSDictionary* dict=  [self dictionaryWithJsonString:jsonS];//Parse jsonStr to NSDictionary
          NSString* idTok= [dict objectForKey:@"id_token"];
            NSString* session_tok=[dict objectForKey:@"session_token"];
            NSString* expr=[dict objectForKey:@"expire"];
                  }];

1
2
3
4
5
6
7

Introduction to Main Class BCIDAIDTokenManager:

/**
   * Function name: sharedInstance
   * @param No input parameters
   * @return Returns the singleton instance of the object
*/
+ (instancetype )sharedInstance;

/**
* Function name: refreshIdTokenWithSessionToken
* @brief: Refresh idToken
* @param sessionToken returned from login
* @param BCIDAIdTokenRefreshIDTokenHandlerBlock callback function:
NSString code
id       data

**/
-(void)refreshIdTokenWithSessionToken:(NSString*)sessionToken andWithCallBack:(BCIDAIdTokenRefreshIDTokenHandlerBlock)callBack;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Callback Function Return Value:

Success Example:
code=0
data=
{
  "id_token" : "eyJraWQiOiJhODJkzJjLmlkYWFzLXRllKp6w",
  "session_token" : "apcOKuyry7kASh9h6mtf2G2GbettkyiU",
  "expire" : 7200
}

Failure Example (Failed to retrieve data)
code=1

1
2
3
4
5
6
7
8
9
10
11

# Return Codes

Status Code	Error Code (error_code)	Error Description (error_msg)
400	IDAAS.SDK.COMMON.1001	Parameter {0} cannot be left blank
		Parameter {0} cannot be empty
400	IDAAS.SDK.COMMON.1002	The {0} parameter format is incorrect
		Parameter {0} format error
400	IDAAS.SDK.COMMON.1003	Device information is incomplete
		Device information incomplete
400	IDAAS.SDK.COMMON.1004	Signature decryption error
		Signature decryption error
400	IDAAS.SDK.COMMON.1005	The {0} has failed
		{0} has expired
400	IDAAS.SDK.COMMON.1006	The {0} parameter error
		{0} parameter error
400	IDAAS.SDK.COMMON.1007	The {0} parameter type error
		{0} parameter type error
500	IDAAS.SDK.COMMON.1008	The system is busy. Try again later
		System busy. Please try again later
400	IDAAS.SDK.COMMON.1009	Unknown authentication configuration
		Unknown authentication configuration
400	IDAAS.SDK.COMMON.1010	Failed to obtain the enterprise center global configuration
		Failed to obtain enterprise center global configuration
400	IDAAS.SDK.COMMON.1011	Failed to obtain the international area code configuration
		Failed to obtain international area code configuration
400	IDAAS.SDK.COMMON.1012	The x-client-ID is incorrect and the corresponding application cannot be found
		X-client-id error, cannot find corresponding application
400	IDAAS.SDK.COMMON.1013	The corresponding user is not found
		Corresponding user not found
400	IDAAS.SDK.COMMON.1014	Application private key not found
		Application private key not found
400	IDAAS.SDK.LOGIN.1001	Error calling interface {0}
		Error calling interface {0}
400	IDAAS.SDK.LOGIN.1002	User not bound
		User not bound
400	IDAAS.SDK.LOGIN.1003	The user has been locked due to too many unsuccessful login attempts. It will be unlocked in {0} minutes and {1} seconds
		The user has been locked due to too many unsuccessful login attempts. It will be unlocked in {0} minutes and {1} seconds
400	IDAAS.SDK.LOGIN.1004	Failed to obtain the password policy
		Failed to obtain password policy
400	IDAAS.SDK.LOGIN.1005	Invalid username or password. Remaining login attempts: {0}
		Invalid username or password. Remaining login attempts: {0}
400	IDAAS.SDK.LOGIN.1006	Configuration error, unable to find wechat authentication source
		Configuration error, unable to find WeChat authentication source
400	IDAAS.SDK.LOGIN.1007	Configuration error, unable to find alipay authentication source
		Configuration error, unable to find Alipay authentication source
400	IDAAS.SDK.LOGIN.1008	The configuration is incorrect. The one-click login authentication source cannot be found
		Configuration error, unable to find one-click login authentication source
400	IDAAS.SDK.SMS.1001	{0} slide base map is not initialized successfully, please check the path
		{0} slide base map not initialized successfully, please check the path
400	IDAAS.SDK.SMS.1002	{0} verification code coordinate resolution failed
		{0} verification code coordinate resolution failed
400	IDAAS.SDK.SMS.1003	{0} verification code coordinate verification fails
		{0} verification code coordinate verification failed
400	IDAAS.SDK.SMS.1004	The graphic verification code is incorrect
		Graphic verification code validation error
400	IDAAS.SDK.SMS.1005	SMS verification code verification is incorrect
		SMS verification code validation error
400	IDAAS.SDK.SMS.1006	The email verification code is incorrect
		Email verification code validation error
400	IDAAS.SDK.SMS.1007	Sending scenario does not exist
		Sending scenario does not exist
400	IDAAS.SDK.SMS.1008	Failed to send the verification code
		Failed to send verification code
400	IDAAS.SDK.SOCIAL.1001	The social account is unbound incorrectly
		Social account unbinding error
400	IDAAS.SDK.SOCIAL.1002	The social account has been bound, please unbind it first
		Social account already bound, please unbind first
400	IDAAS.SDK.PWD.1001	The password length is incorrect
		Password length error
400	IDAAS.SDK.PWD.1002	The password cannot be the username
		Password cannot be the username
400	IDAAS.SDK.PWD.1003	Your password complexity is low
		Your password complexity is low
400	IDAAS.SDK.PWD.1004	The password is weak
		Password is weak
400	IDAAS.SDK.PWD.1005	The password is used before, cannot be used again
		This password has been used before and cannot be used again
400	IDAAS.SDK.PWD.1006	Password cannot username in reverse order
		Password cannot be the username in reverse order
400	IDAAS.SDK.PWD.1007	The number of repeated password characters exceeded the upper limit
		Number of repeated password characters exceeds limit
400	IDAAS.SDK.PWD.1008	Password cannot contain :username, phone number, email prefix, name in PinYing
		Password cannot contain: username, phone number, email prefix, name in Pinyin
400	IDAAS.SDK.MFA.1001	The mobile doesn't match the user
		Mobile number does not match the user
400	IDAAS.SDK.MFA.1002	The access control policy is incorrect
		Access control policy configuration error
400	IDAAS.SDK.MFA.1003	Access control authentication source type conversion error
		Access control authentication source type conversion error

I am ready to proceed. Please provide the Markdown content you need translated.

Password Login Mobile One-click Login

竹云IDaaS•开放平台

SMS Login

SMS Login

# Documentation

# Process Description

# Login Process

# Environment Setup

# Obtaining the Application clientID

# Adding Dependencies

# Adding the Main Libraries

# Targets Configuration

# Development Integration

# SDK Initialization {/sdk-initialization/}

# Calling Sequence {/calling-sequence/}

# Sending SMS Verification {/sending-sms-verification/}

# Mobile Number and SMS Verification Code Login

# Mobile International Dialing Code Acquisition

# IDToken Verification and User Information Retrieval

# Verify id_token {/examples/}

# Parsing User Information from idToken

# Refresh IDToken

# Return Codes