SMS Login

Document Description

This document describes how the iOS client can integrate SMS login. The SMS login feature sends an SMS verification code to the user's mobile number, and the user authenticates to the IDaaS server with the mobile number and SMS verification code.

In the SMS login usage scenario, the user enters a mobile number, taps the button to obtain an SMS verification code, the sliding verification is triggered, and after verification succeeds, the IDaaS back end sends an SMS verification code to this number. The user enters the verification code and taps Login, then the IDaaS back end authenticates and returns a ticket. The final authentication result is returned to the App.

Integration Flow Description

The user enters a mobile number. The App client checks whether the number conforms to the format rules. The user taps to obtain the verification code.
The App client calls the sliding verification method. The IDaaS SDK requests the IDaaS back-end sliding verification initialization information and displays the sliding verification window on the page.
The user drags the slider to complete the sliding verification. The IDaaS SDK completes collecting the sliding verification information and requests the IDaaS server to verify.
The IDaaS server completes the sliding verification successfully and returns a token to the IDaaS SDK.
The IDaaS SDK obtains the token and uses it to request the IDaaS server to send the SMS.
The user receives the SMS, enters the verification code, and taps Login.
The App client uses the mobile number and verification code to call the IDaaS SDK SMS login method.
The IDaaS SDK requests SMS login. The IDaaS server initiates the authentication flow. If authentication succeeds, it returns session_token and id_token to the IDaaS SDK; if authentication fails, 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, which then enters its own flow based on the result.
The client can use id_token to verify login validity and obtain basic user information.
The client can use session_token to refresh id_token.

Environment Setup

Obtain Application clientID

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

Import Dependency Packages

No third-party SDK dependencies.

Add Main Library

objective-c

AuthnCenter_common_2E.framework	  
AuthnCenter_SMSLogin_2E.bundle
AuthnCenter_SMSLogin_2E.framework

Drag the IDaaS SDK into the project. The import method is as follows:

And introduce the Pod dependency.

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

Target Settings

The IDaaS SMS login SDK is compatible with iOS 10 and above.
Introduce the following packages in Framework, Library, 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, and set bitcode to NO.

Development Integration

Import header:

In AppDelegate, import as follows
#import <AuthnCenter_common_2E /BCIDACommonManager.h>

SDK Initialization

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

Initialization example: call the initialization method in the didFinishLaunchingWithOptions method of AppDelegate.

objective-c

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

Basic configuration initialization main class BCIDACommonManager method overview:

objective-c

/**
  * Method name: sharedInstance
   * @param none
   * @return Singleton instance
 */
+ (instancetype )sharedInstance ;

/**
  * Method name: initWithDomain
   * @param domain, starts with https:// and ends with .com.
   * @return Instance
 */
-(BCIDACommonManager)initWithDomain:(NSString)domain

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

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

/**
  * Method name: initWithSSLCerVerification
   * @param Boolean whether to enable SSL certificate verification.
   * @return Instance
 */
-(BCIDACommonManager*)initWithSSLCerVerification:(bool)sslCerVerification;

Call Sequence

If international number support is enabled: Call the international area code API in advance for UI binding and display. For methods that require a mobile number, assemble the international area code (e.g., +86-13800000000) and pass it in. If not enabled, ignore this API.
Call sliding verification and send SMS (startSlidingVerifyCodePageWithMobileNumber), passing in the mobile number.
Call SMS login method (loginsBySMSWithMobile), passing in the mobile number and SMS verification code.

Send SMS Verification Code

The App client needs its own UI page containing the necessary components: mobile number input box, verification code input box, button (or event) to trigger obtaining the verification code, and button (or event) to log in.

After the user enters the mobile number and before tapping the event to send the verification code, the App client checks the mobile number format.
When the event to send the verification code is triggered, the App client calls the IDaaS SDK method to send the verification code, as shown below:

objective-c

// Import header
#import <AuthnCenter_SMSLogin_2E/BCSMSLoginSlideVerifyCodeManager.h>

// Trigger 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(@"Sliding verification result==%@==%@",code,data);
            
            });
        }];

BCSMSLoginSlideVerifyCodeManager object method overview:

objective-c

/**
* Method name: startSlidingVerifyCodePageWithMobileNumber
* @brief: Trigger sliding verification. After successful verification, an SMS is sent. If sliding verification fails, code = error code and data returns the error reason. SMS sent successfully: code = 0.
*@ param mobile Mobile number: with area code "+86-13800000000" or without area code "13800000000" are both acceptable.
*@param complete: Asynchronous result callback. code=0 indicates SMS sent successfully; other values indicate SMS sending failure or sliding verification failure. Refer to IDaaS error codes and returned data (string error description). code=105, data="User closed" means the close button of the sliding box was tapped.
**/
+(void)startSlidingVerifyCodePageWithMobileNumber:(NSString*)mobile andWithResultHandler:(BCSMSLoginSlideCodeHandlerBlock)resultHandler;

After the previous verification code is sent, the user receives the SMS verification code, fills it in the verification code box, and triggers the login event. At this time, the App client initiates the SMS login flow. Example code:

objective-c

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

        dispatch_async(dispatch_get_main_queue(), ^{
   // Login success or failure navigation
        });
  }];

BCLoginSMSManager method overview:

objective-c

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

BCLoginSMSCompleteHandler callback return codes:

code	Description
code=0	Login succeeded. At this time, data returns an NSDictionary: `data=@{@"session_token":sessionTokenContent,@"id_token":idTokenContent}`;
code=1	Login failed. data returns a string describing the error

International Mobile Area Code

If international number support is enabled, call the international area code API in advance. The API returns the configured list of international area codes with regular expressions for phone numbers. The figure below shows how to configure the international area code list and preferred area code.

The IDaaS SDK provides an API to obtain international area codes:

Example code for obtaining the international area code list:

objective-c

#import <AuthnCenter_common_2E/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 whether the phone number matches the regular expression 
 BOOL flag=  [strongSelf parseDictionary:dic andWithMoile:mobile];
            
        });
    }];

Main class method introduction:

objective-c

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

Success example code=0, data value:

JSON

{
	"phoneAreaCodeDefinitions": [
		{
			"areaCode": "86",
			"displayMapping": {
				"zh-TW": "Mainland China",
				"en": "China",
				"zh-CN": "Mainland China"
			},
			"countryCode": "CN",
			"mobileRegex": "^(\\+86){0,1}\\-?1\\d{10}$",
			"areaCodeSuffixes": []
		},
		{
			"areaCode": "852",
			"displayMapping": {
				"zh-TW": "Hong Kong",
				"en": "Hong Kong",
				"zh-CN": "Hong Kong"
			},
			"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": "Taiwan",
				"en": "Taiwan",
				"zh-CN": "Taiwan"
			},
			"countryCode": "TW",
			"mobileRegex": "^(\\+886){1}\\-?[6,7,9](?:\\d{7}|\\d{8})$",
			"areaCodeSuffixes": []
		},
		{
			"areaCode": "853",
			"displayMapping": {
				"zh-TW": "Macau",
				"en": "Macau",
				"zh-CN": "Macau"
			},
			"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": "Afghanistan",
				"en": "Afghanistan",
				"zh-CN": "Afghanistan"
			},
			"countryCode": "AF",
			"mobileRegex": "^(\\+93){1}\\-\\d{6,11}",
			"areaCodeSuffixes": []
		}
	],
	"preferredAreaCode": "CN"
}

Response parameters:

Parameter Name	Description
preferredAreaCode	Preferred international area code configured in the Enterprise Center
countryCode	Country/region code
areaCode	International dialing code
areaCodeSuffixes	International dialing code suffixes
mobileRegex	Mobile number format regular expression
displayMapping	Multi-language display name mapping

IDToken Verification and User Information

After login succeeds, session_token and id_token are returned. id_token can be used to obtain user information and verify login validity.

Verify idToken.
Obtain user information from idToken (this method can be called directly without verification).

Verify id_token

Call example:

objective-c

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

BCIDAIDTokenManager introduction:

objective-c

/**
   * Method name: sharedInstance
   * @param no input
   * @return Returns the singleton instance
*/
+ (instancetype )sharedInstance;

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

Return values:

code(NSString)	data	Data Type and Description
0	success	[NSString] Signature verification succeeded
1	Error description	[NSString] Input parameter is empty; SDK initialization parameters domain and clientID are not set
106	Expired	[NSString] Expired idToken
107	clientID mismatch	[NSString] Possibly used clientID of another application
103	Signature verification failed	[NSString] Signature verification process failed
102	Failed to obtain public key	[NSString] Error during signature verification
See error code collection at the end	See error code collection at the end	May also return error codes at the end

Parse User Information from idToken

Call example:

objective-c

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

BCIDAIDTokenManager introduction:

objective-c

/**
   * Method name: sharedInstance
   * @param no input
   * @return Returns the singleton instance
*/
+ (instancetype )sharedInstance;

/**
* Method name: getUserInfoFromIdTokenWithIdToken
* @brief: Parse user information from idToken
* @param idToken returned during login
* @param BCIDAIdTokenGetInfoHandlerBlock callback:
NSString code
id       data

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

User information parameter description:

Parameter Name	Description
iss	Token issuer
aud	Token recipient, application clientId
exp	Token expiration time
jti	Token ID
iat	Token issue time
sub	Fixed as subject
name	User name
mobile	User mobile number
id	User ID
userName	Username
email	User email

Callback return value:

json

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"
}

Refresh IDToken

Call example:

objective-c

[[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"];
                  }];

BCIDAIDTokenManager introduction:

objective-c

/**
   * Method name: sharedInstance
   * @param no input
   * @return Returns the singleton instance
*/
+ (instancetype )sharedInstance;

/**
* Method name: refreshIdTokenWithSessionToken
* @brief: Refresh idToken
* @param sessionToken returned during login
* @param BCIDAIdTokenRefreshIDTokenHandlerBlock callback:
NSString code
id       data

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

Callback return value:

json

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

Failure example (data unavailable)
code=1

Error Codes

HTTP Status	Error Code (error_code)	Error Message (error_msg)
400	IDAAS.SDK.COMMON.1001	Parameter {0} cannot be left blank
400	IDAAS.SDK.COMMON.1002	The {0} parameter format is incorrect
400	IDAAS.SDK.COMMON.1003	Device information is incomplete
400	IDAAS.SDK.COMMON.1004	Signature decryption error
400	IDAAS.SDK.COMMON.1005	The {0} has failed
400	IDAAS.SDK.COMMON.1006	The {0} parameter error
400	IDAAS.SDK.COMMON.1007	The {0} parameter type error
500	IDAAS.SDK.COMMON.1008	The system is busy. Try again later
400	IDAAS.SDK.COMMON.1009	Unknown authentication configuration
400	IDAAS.SDK.COMMON.1010	Failed to obtain the enterprise center global configuration
400	IDAAS.SDK.COMMON.1011	Failed to obtain the international area code configuration
400	IDAAS.SDK.COMMON.1012	The x-client-ID is incorrect and the corresponding application cannot be found
400	IDAAS.SDK.COMMON.1013	The corresponding user is not found
400	IDAAS.SDK.COMMON.1014	Application private key not found
400	IDAAS.SDK.LOGIN.1001	Error calling interface
400	IDAAS.SDK.LOGIN.1002	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
400	IDAAS.SDK.LOGIN.1004	Failed to obtain the password policy
400	IDAAS.SDK.LOGIN.1005	Invalid username or password. Remaining login attempts:
400	IDAAS.SDK.LOGIN.1006	Configuration error, unable to find wechat authentication source
400	IDAAS.SDK.LOGIN.1007	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
400	IDAAS.SDK.SMS.1001	{0} slide base map is not initialized successfully, please check the path
400	IDAAS.SDK.SMS.1002	{0} verification code coordinate resolution failed
400	IDAAS.SDK.SMS.1003	{0} verification code coordinate verification fails
400	IDAAS.SDK.SMS.1004	The graphic verification code is incorrect
400	IDAAS.SDK.SMS.1005	SMS verification code verification is incorrect
400	IDAAS.SDK.SMS.1006	The email verification code is incorrect
400	IDAAS.SDK.SMS.1007	Sending scenario does not exist
400	IDAAS.SDK.SMS.1008	Failed to send the verification code
400	IDAAS.SDK.SOCIAL.1001	The social account is unbound incorrectly
400	IDAAS.SDK.SOCIAL.1002	The social account has been bound, please unbind it first
400	IDAAS.SDK.PWD.1001	The password length is incorrect
400	IDAAS.SDK.PWD.1002	The password cannot be the username
400	IDAAS.SDK.PWD.1003	Your password complexity is low
400	IDAAS.SDK.PWD.1004	The password is weak
400	IDAAS.SDK.PWD.1005	The password is used before, cannot be used again
400	IDAAS.SDK.PWD.1006	Password cannot username in reverse order
400	IDAAS.SDK.PWD.1007	The number of repeated password characters exceeded the upper limit
400	IDAAS.SDK.PWD.1008	Password cannot contain :username, phone number, email prefix, name in PinYing
400	IDAAS.SDK.MFA.1001	The mobile doesn't match the user
400	IDAAS.SDK.MFA.1002	The access control policy is incorrect
400	IDAAS.SDK.MFA.1003	Access control authentication source type conversion error

Organization Sync

User Sync

SMS Login ​

Document Description ​

Login Flow ​

Environment Setup ​

Obtain Application clientID ​

Import Dependency Packages ​

Add Main Library ​

Target Settings ​

Development Integration ​

SDK Initialization ​

Call Sequence ​

Send SMS Verification Code ​

Mobile Number and SMS Verification Code Login ​

International Mobile Area Code ​

IDToken Verification and User Information ​

Verify id_token ​

Parse User Information from idToken ​

Refresh IDToken ​

Error Codes ​

Document Description

Login Flow

Environment Setup

Obtain Application clientID

Import Dependency Packages

Add Main Library

Target Settings

Development Integration

SDK Initialization

Call Sequence

Send SMS Verification Code

Mobile Number and SMS Verification Code Login

International Mobile Area Code

IDToken Verification and User Information

Verify id_token

Parse User Information from idToken

Refresh IDToken

Error Codes