SMS Login
# Documentation Description
This document explains how to integrate the SMS login functionality into an 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 verification 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.
# Login Process
Integration Process Description
The user enters their phone number, and the App client checks if the phone number conforms to the format rules. 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 finishes collecting the slider verification information and requests the IDaaS server to perform the verification.
The IDaaS server completes the slider 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 clicks login.
The App client uses the phone number and verification code to call the IDaaS SDK's SMS login method.
The IDaaS SDK requests SMS login. The IDaaS server initiates the authentication process. Upon successful authentication, it returns a 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. The App client proceeds with its own flow 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
# Obtain Application clientID
Log in to the IDaaS Enterprise Center platform, click "Resources --> Applications," select the relevant application, and click to view it.
# Introduce Dependency Packages
No third-party SDK dependencies.
# Add Main Libraries
AuthnCenter_common_2E.framework
AuthnCenter_SMSLogin_2E.bundle
AuthnCenter_SMSLogin_2E.framework
2
3
Drag the IDaaSSDK into the project and introduce it as follows:
And introduce the Pod dependency package.
pod 'JWT', '~> 3.0.0-beta.14'
# Targets Settings
The minimum compatible version for the IDaaS SMS Login SDK is iOS 10.
In Framework, Library, and Embedded Content, introduce the following packages.
Add the main libraries and dependency packages in Framework, Libraries, and Embedded Content, and add -ObjC in 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:
In the appdelegate, reference as follows:
#import <AuthnCenter_common_2E /BCIDACommonManager.h>
2
# SDK Initialization
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: Initialize the method in the didFinishLaunchingWithOptions method within appdelegate.
//1. Basic configuration initialization
[[[[[BCIDACommonManager sharedInstance] initWithDomain:@"https://your-backend-tenant.com"] initWithClientID:@"backend-tenant-clientID"] initWithSSLCerVerification:NO] setLogEnabled:YES] ;
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, starts with https:// and ends 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 setting whether to enable SSL certificate verification.
* @return Instance class
*/
-(BCIDACommonManager*)initWithSSLCerVerification:(bool)sslCerVerification;
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
# Call Sequence
If international number support is enabled: Please first call the international area code acquisition interface yourself, bind and display it on the interface, and when a method requiring a phone number is needed, assemble the international area code yourself (e.g., +86-13800000000) and pass it in. If support is not enabled, ignore this interface.
Call the slider verification and send SMS (
startSlidingVerifyCodePageWithMobileNumber) Input parameter: mobile numberCall the SMS login method (
loginsBySMSWithMobile) Input parameters: mobile number, SMS verification code
# Sending SMS Verification
The App client needs to have its own UI interface, which includes several necessary components: a phone 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 performs mobile number format validation.
Click (trigger) the send verification code event, the App client calls the IDaaS SDK's send verification code method, example as follows:
//Import the request header
#import <AuthnCenter_SMSLogin_2E/BCSMSLoginSlideVerifyCodeManager.h>
//Click (trigger) the send verification code event
[BCSMSLoginSlideVerifyCodeManager startSlidingVerifyCodePageWithMobileNumber:mobile-number andWithResultHandler:^(NSString * _Nonnull code, id _Nonnull data) {
__strong __typeof(weakSelf)strongSelf = weakSelf;
dispatch_async(dispatch_get_main_queue(), ^{
NSLog(@"Slider verification result==%@==%@",code,data);
});
}];
2
3
4
5
6
7
8
9
10
11
12
Introduction to the BCSMSLoginSlideVerifyCodeManager object methods:
/**
* Function Name: startSlidingVerifyCodePageWithMobileNumber
* @brief: Click to launch 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: Can be with area code "+86-13800000000" or without area code "13800000000".
* @param complete: Asynchronous result callback. code=0 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 closed" indicates the close button on the sliding verification box was clicked, and the sliding verification box was closed.
**/
+(void)startSlidingVerifyCodePageWithMobileNumber:(NSString*)mobile andWithResultHandler:(BCSMSLoginSlideCodeHandlerBlock)resultHandler;
2
3
4
5
6
7
# Mobile Number and SMS Verification Code Login
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:mobileNumber andWithVerifyCode:verificationCode andWithCompletionHandler:^(NSString * _Nonnull code, id _Nonnull data) {
__strong __typeof(weakSelf)strongSelf = weakSelf;
dispatch_async(dispatch_get_main_queue(), ^{
//Login success/failure, redirect
});
}];
2
3
4
5
6
7
Introduction to the main class BCLoginSMSManager method:
/**
* 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;
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 Area Code Retrieval
If international number support is enabled, please first call the international area code retrieval interface. The international area code retrieval interface returns a configured list of international area codes, along with regular expressions for phone numbers. The following image shows how to configure the international area code list and the preferred area code.
IDaaS SDK provides an API for retrieving international area codes:
Example code for retrieving the international area code list:
#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 if the phone number matches the regular expression
BOOL flag= [strongSelf parseDictionary:dic andWithMoile:mobile];
});
}];
2
3
4
5
6
7
8
9
10
11
12
Main class method introduction:
/**
* Function name: getInternaltionalAreaCodeWithCompletionHandler
* @brief: Method to get international area codes
* @param
*@param
* @param BCSMSGetInternationalAreaCodeHandlerBlock () Result callback function code=0, data returns NSDictionary result
**/
+(void)getInternaltionalAreaCodeWithCompletionHandler:(BCSMSGetInternationalAreaCodeHandlerBlock)resultHander;
2
3
4
5
6
7
8
Success 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"
}
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 Dialing Code | String | The preferred international dialing code configured for the current enterprise center |
| countryCode | Country/Region Code | String | Country/Region Code |
| areaCode | International Telephone Code | String | International Telephone Code |
| areaCodeSuffixes | International Telephone Code Suffix | String | International Telephone Code Suffix |
| mobileRegex | Mobile Number Format Regex | String | Mobile Number Format Regex |
| displayMapping | Multi-language Display Name Mapping | String | Multi-language Display Name Mapping |
# ID Token Verification and User Information Retrieval
Upon successful login, a session_token and an id_token are returned. The id_token can be used to retrieve user information and verify the login validity period.
Verify the idToken.
Retrieve user information from the idtoken (This method can be called directly without verification)
# Verify id_token
Call Example:
[[BCIDAIDTokenManager sharedInstance] verifySignWithIdToken:idToken andWithCallBack:^(NSString * _Nonnull code, id _Nonnull data) {
}];
2
Main Class BCIDAIDTokenManager Introduction:
/**
* Function name: sharedInstance
* @param No input parameters
* @return Returns the singleton instance of the object
*/
+ (instancetype )sharedInstance;
/**
* Function name: verifySignWithIdToken
* @brief: Method to verify if 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;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Return Values:
| code(NSString) | data | data Type and Description |
|---|---|---|
| 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 mismatch | [NSString] Possibly used clientID from another application |
| 103 | Signature verification failed | [NSString] Signature verification process failed |
| 102 | Public key obtained is empty | [NSString] Error during the signature verification process |
| See the error code collection at the end | See the error code collection at the end | May also return error codes listed at the end |
# Parsing User Information from idToken
Calling Example:
[[BCIDAIDTokenManager sharedInstance] getUserInfoFromIdTokenWithIdToken:idToken andWithCallBack:^(NSString * _Nonnull code, id _Nonnull data) {
}];
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 The idToken returned from login
* @param BCIDAIdTokenGetInfoHandlerBlock Callback function:
NSString code
id data
**/
-(void)getUserInfoFromIdTokenWithIdToken:(NSString*)idToken andWithCallBack:(BCIDAIdTokenGetInfoHandlerBlock)callback;
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 Recipient, the application's clientId |
| exp | Token Expiration Time |
| jti | Token ID |
| iat | Token Issuance Time |
| sub | Fixed as subject |
| name | User's Full Name |
| mobile | User's Mobile Number |
| id | User's ID |
| userName | Username |
| 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"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Refreshing 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"];
}];
2
3
4
5
6
7
8
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;
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
2
3
4
5
6
7
8
9
10
11
# Return Codes
| Status Code | Error Code (error_code) | Error Description (error_msg) | Handling Measures |
|---|---|---|---|
| 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 is 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 | |
| The system is 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 the 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 verification error | |||
| 400 | IDAAS.SDK.SMS.1005 | SMS verification code verification is incorrect | |
| SMS verification code verification error | |||
| 400 | IDAAS.SDK.SMS.1006 | The email verification code is incorrect | |
| Email verification code verification 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 is 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 too low | |||
| 400 | IDAAS.SDK.PWD.1004 | The password is weak | |
| The 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 reverse order of the username | |||
| 400 | IDAAS.SDK.PWD.1007 | The number of repeated password characters exceeded the upper limit | |
| Number of repeated password characters exceeds the 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 | |
| Phone 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 understand. Please provide the Markdown content you need translated, and I will follow all the specified rules.