Hướng dẫn tích hợp API chữ ký số vào ứng dụng thông qua webservice viettel

Thông số kĩ thuật

Hướng dẫn tích hợp API chữ ký số vào ứng dụng thông qua webservice viettel tích hợp chữ ký số vào website phần mềm tích hợp chữ ký số của kbnn giải pháp tích hợp chữ ký số tích hợp chữ ký số vào phần mềm

Tài liệu tich hợp API

INTRODUCTION

This doument describes in details the API of Remote Signing. In this version, API is now including 8 functions:

info
auth/login
auth/revoke
credentials/list
credentials/info
credentials/sendOTP
credentials/authorize
credentials/extendTransaction
signature/signHash
owner/list
owner/assign

Target

Banks, Finance/Insurance companies who wants to apply digital signature for loan approval.

Abbreviation

Word	Description
CA	Certification Authority
PKI	Public Key Infrastructure
M	Mandatory
O	Optional
RD	Required Conditional
AP	Application Provider
RP	Relying Party
SCAL1	Sole Control Assurance Level 1
SCAL2	Sole Control Assurance Level 2
RS	Remote Signing
SAD	Signature Activation Data

API SPECIFICATION
- info

This method returns the information of Remote Signing such as: the version of remote signing service, the methods which are supported by the service. This method doesn’t need client authentication.

Sample Request:

POST /rssp/v1/info HTTP/1.1

HOST: rssp.mobile-id.vn

Content-Type: application/json

{}

Sample Response:

{

"version": "1.0.0"

"name": "Remote Signing Services",

"description": "An efficient remote signature service",

"logo": "https://rssp.mobile-id.vn/images/logo.png",

" languages": [

"VN", "EN"

" authTypes": [

"PASSCODE","OTPSMS","OTPEMAIL"

"methods": [

"auth/login","auth/revoke",

"credentials/list","credentials/info",

"credentials/sendOTP","credentials/authorize"

"credentials/extendTransaction","signature/signHash",

"owner/list","owner/assign"

]

}

Attributes description:

Request Attributes
No	Name	Type	Require	Description

Response Attributes
No	Name	Type	Require	Description
1	version	String	M	The current version of Remote Signing
2	name	String	M	The name of the service
3	description	String	O	The description of the service
4	logo	String	O	The logo image URL of the service
5	languages	String []	M	The languages are supported by the service
6	authTypes	String []	M	Authorization methods are supported by the service. These values RSSP support: - Basic: authorization by user and password. - SSL2: authorization by pkcs7 signature. - OAUTH2: RSSP support oauth2.
7	oauth2	String	RC	The base URI of the OAuth 2.0 authorization server endpoint supported by the remote service for service authorization and/or credential authorization. The parameter SHALL be present in any of the following cases: • The authType parameter contains “oauth2code” or “oauth2client”; • The remote service supports the value “oauth2code” for the authMode parameter returned by credentials/info.
8	methods	String []	M	Functions are supported by the service

auth/login

In this function, client should provide the credential information issued by service provider for the first authentication. Server checks client information and returns an access token to client to use for the subsequent API requests within the same session. For the further API once login succeed, client must provide this access token in the request.

These authentication factors SHALL be passed directly in the HTTP header with name Authorization, it MAY have multi authentication factors separated by comma. RSSP accept two value as follow:

SSL2 <credential>, Basic <credential>

The SSL2 credential is authentication factor to authenticate RP server. It is constructed in following format:

BASE64-encode(username:password:signature:timestamp:pkcs1Signature)

username, password, signature is provided by service provider
pkcs1Signature is calculated based on username, password, signature and timestamp.
timestamp is the current client date-time. It could be in yyyyddmmHHMMss format or Unix epoch time likes 1570182293561.

Example:

username: MOBILE_ID
password: 12345678
signature:
pkcs1Signature:
timestamp:
MOBILE_ID:12345678:signature:timestamp:pkcs1Signature
Credential: TU9CSUxFX0lEOjEyMzQ1Njc4OnNpZ25hdHVyZTpwa2NzMVNpZ25hdHVyZTp0aW1lc3RhbXA=
Basic credential is authentication factor to authenticate end-user, this is OPTIONAL using for RPs not manage end-user. It is constructed in following format:

BASE64-encode(usertype:username:password)

usertype is one in three values:
- 1 – USERNAME: if username is username.
- 2 – PERSONAL-ID: if username is people’s identity card.
- 3 – PASSPORT-ID: if username is passport identity card.
- 4 – CITIZEN-IDENTITY-CARD: if username is citizen identity card.
- 5 – BUDGET-CODE: if username is budget code.
- 6 – TAX-CODE: if username is tax code.
username is value issued by RSSP (in registration progress) or user’s identify card or tax code.
password is secret value memorized by end-user.

Example:

usertype: USERNAME
username: user
password: 123456
Credential: VVNFUk5BTUU6dXNlcjoxMjM0NTY=

The alternative way to re-authenticate the user after an access token has expired is using the refresh token. At this time, the authorization header should be in format:

Bearer <refresh token>

Sample Request:

POST /rssp/v1/auth/login HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: SSL2 dXNlcm5hbWU6cGFzc3dvcmQ6c2lnbmF0dXJlOnBrY3MxU2lnbmF0dXJlOnRpbWVzdGFtcA==, Basic VVNFUk5BTUU6dXNlcjoxMjM0NTY=

Content-Type: application/json

{

"relyingParty": "MOBILE-ID",

"relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

"rememberMe": true,

"language": "EN"

}

Sample Response:

{

"responseCode": 0,

"responseMessage": "Successfully",

"billCode": "MOBILE-ID-190611194921-3-559951",

"accessToken": "VGhpcyBpcyBhY2Nlc3NUb2tlbg==",

"refreshToken": "cmVmcmVzaFRva2VuIGlzIG1lLg==",

"expiresIn": 60,

"username": "user"

}

Attributes description:

Request Attributes
No	Name	Type	Require	Description
1	relyingParty	String	M	In case of many services are running on Remote Signing. Relying Party is used to determine which client is calling to.
2	relyingPartyBillCode	String	O	Relying Party’s billcode.
3	billCode	String	O	Request’s bill code.
4	rememberMe	Boolean	O	A Boolean value typically corresponding to an option that the user may activate during the authentication phase to "stay signed in" and maintain a valid authentication across multiple sessions: § "true": if the remote service supports user re-authentication, a refreshToken will be returned and the signature application may use it on a subsequent call to this method instead of passing an Authorization header. § "false": a refreshToken will not be returned. If the parameter is omitted, it will default to "false".
5	clientInfo/iccid	String	O	Client machine information. RS will use this one to manage working session binding with a replyingParty or owner.
6	clientInfo/imei	String	O	Client machine information. RS will use this one to manage working session binding with a replyingParty or owner.
7	clientInfo/macAddr	String	O	Client machine information. RS will use this one to manage working session binding with a replyingParty or owner.
8	language	String	O	Possible value: VN, EN

Response Attributes
No	Name			Type		Require		Description
1	responseCode			int		M		Code describes the result. Expected: 0
2	responseMessage			String		M		Message describes the result in detail.
3	billCode			String		M		Receipt for each transaction
4	accessToken			String		M		The short-lived service access token used to authenticate the subsequent API requests within the same session. When receiving an API call with an expired token, the remote service will return an error and require a new auth/login request.
5	refreshToken			String		RC		The long-lived refresh token used to re-authenticate the user on the subsequent session. The value is returned if the rememberMe parameter in the request is "true" and the remote service supports user re-authentication.
6	expiresIn			int		O		The lifetime in seconds of the service access token. If omitted, the default expiration time is 3600 seconds.
7	remainingCounter			int		RC		Number of remaining attempts of login, only return if basic available in header Authorization and password of owner is wrong.
8	temporaryLockTime			Int		RC		Owner lockout time, only try again when the time is up. In seconds.
9	ownerInfo/fullName			String		RC		Full name of account.
10	ownerInfo/phone			String		O		Phone of account.
11	ownerInfo/email			String		O		Email of account.
12	ownerInfo/oauth2			String		O		OAUTH2 account information.
Credential information
No		Name	Type		Require		Description
1		username	String		M		Username of relyingParty provided by Remote Signing
2		password	String		M		Password of relyingParty provided by Remote Signing
3		signature	String		M		Signature of relyingParty provided by Remote Signing
4		pkcs1Signature	String		M		Value is signed from client private key. Key is generated and provided by Remote Signing Value=username + password + signature + timestamp
5		timestamp	String		M		Current timestamp, format in yyyyddmmHHMMss format or Unix epoch time likes 1570182293561.

auth/revoke

This function will revoke the token for request authentication. If the token type is 1 (one), the RS will not validate the refresh token and all access tokens based on the same authorization grant. If the token type us 0 (zero), the RS will not validate the access token but it will not revoke any existing refresh token based on the same authorization grant.

Note 01: Authorization info in the header of the request is presented in following format:

KEY=Authorization, VALUE=Bearer <access token or refresh token>

(Access token or refresh token is obtained from login function which is defined in session 2.2).

Sample Request:

POST /rssp/v1/auth/revoke HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

"relyingParty": "MOBILE-ID",

"relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

"tokenType": 0,

"token": "VGhpcyBpcyBhY2Nlc3NUb2tlbg==",

"language": "EN"

}

Sample Response:

{

"responseCode": 0,

"responseMessage": "Successfully",

"billCode": "MOBILE-ID-190611194921-3-559951"

}

Attributes description:

Request Attributes
No	Name	Type	Require	Description
1	relyingPartyBillCode	String	O	Relying Party’s billcode
2	billCode	String	O	Request’s bill code.
3	tokenType	int	O	The type of token submitted for revocation. The possible values are: 0: access token 1: refresh token 2: SAD token If token type is omitted. RS understands the token received is access token.
4	token	String	M	The token will be revoked
5	language	String	O	Possible value: VN, EN
6	agreementUUID	String	RS	Contract identifier, this value is required when tokenType is 2 (to revoke SAD token) and access_token in Authorization header is retrieved from login with SSL2 Only.
7	thumbprint	String	RC	Thumbprint of certificate, this value is required when tokenType is 2 (to revoke SAD token).

Response Attributes
No	Name	Type	Require	Description
1	responseCode	int	M	Code describes the result. Expected: 0
2	responseMessage	String	M	Message describes the result in detail.
3	billCode	String	M	Receipt for each transaction

credentials/list

This function will return the brief information of certificates which are belonged to an owner. The certificate information doesn’t have full BASE64 certificate encoded. There is enough information for client to identify the certificate.

Note 01: Authorization info in the header of the request is presented in following format:

KEY=Authorization, VALUE=Bearer <access token or refresh token>

(Access token or refresh token is obtained from login function which is defined in session 2.2).

Sample Request:

POST /rssp/v1/credentials/list HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

"relyingParty": "MOBILE-ID",

"relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

"agreementUUID": FEC#201910281308,

"language": "EN"

}

Sample Response:

{

"responseCode": 0,

"responseMessage": "Successfully",

"billCode": "MOBILE-ID-190611194921-3-559951"

"certificates": [

{

"certificateID": 84902,

"issuerDN": "<X.500_issuer_DN_printable_string>",

"serialNumber": "5AAC41CD8FA22B953640",

"thumbprint": "86f7e437faa5a7fce15d1ddcb9eaeaea377667b8",

"subjectDN": "<X.500_subject_DN_printable_string>",

"validFrom": "20180101100000Z",

"validTo": "20190101095959Z",

{

"certificateID": 84899,

"issuerDN": "<X.500_issuer_DN_printable_string>",

"serialNumber": "5AAC41CD8FA22B953640",

"thumbprint": "86f7e437faa5a7fce15d1ddcb9eaeaea377667b8",

"subjectDN": "<X.500_subject_DN_printable_string>",

"validFrom": "20180101100000Z",

"validTo": "20190101095959Z",

}

]

}

Attributes description:

Request Attributes
No	Name	Type	Require	Description
1	relyingPartyBillCode	String	O	Relying Party’s billcode
2	billCode	String	O	Request’s bill code.
3	agreementUUID	String	RC	The uuid of agreement, this value was returned from the agreement registration (SOAP API). This param require when access_token is retrieved from login with SSL2 Only.
4	searchConditions/certificateStatus	String	O	State of certificate. The possible values are: · “ALL”, · “GOOD”, · “REVOKED”. Default value is “ALL”.
5	searchConditions/cetificatePurpose	String	O	Purpose usage of certificate. The possible values are: · “ALL”, · “SIGNATURE”, · “ENCRYPTION”. Default value is “ALL”
6	certificateInfo	Boolean	O	Returns the details of certificate information. This is useful in case the signature application wants to retrieve some details of the certificate without having to decode it first. The default value is “false”, so if the parameter is omitted then the information will not be returned.
7	language	String	O	Possible value: VN, EN

Response Attributes
No	Name	Type	Require	Description
1	responseCode	int	M	Code describes the result. Expected: 1007
2	responseMessage	String	M	Message describes the result in detail.
3	billCode	String	M	Receipt for each transaction
4	certificates/issuerDN	String	RC	The Issuer Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string. This value will be returned when certificateInfo is “true”.
5	certificates/serialNumber	String	RC	The Serial Number from the X.509v3 end entity certificate represented as hex-encoded string format. This value will be returned when certificateInfo is “true”.
6	certificates/thumbprint	String	M	The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.
7	certificates/subjectDN	String	RC	The Subject Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string. This value will be returned when certificateInfo is “true”.
8	certificates/validFrom	String	RC	The validity start date from the X.509v3 end entity certificate as character string. This value will be returned when certificateInfo is “true”.
9	certificates/validTo	String	RC	The validity end date from the X.509v3 end entity certificate as character string. This value will be returned when certificateInfo is “true”.
10	certificate/certificateProfile/name	String	RC	Name of certificate’s profile. This value will be returned when certificateInfo is “true”.
11	certificate/certificateProfile/description	String	RC	Description of certificate’s profile. This value will be returned when certificateInfo is “true”.
12	certificates/purpose	String	RC	Purpose usage of certificate. This value will be returned when certificateInfo is “true”.
13	certificates/numSignatures	int	RC	A number equal or higher to 1 representing the maximum number of signatures that can be created with this credential with a single authorization request. This value will be returned when certificateInfo is “true”.
14	certificates/remainingSigningCounter	int	M	Remaining signing counter of this certificate. § -1: unlimited. § 0: out of signing.
15	certificates/version	int	M	The certificate version, the third application must rely on this value to decide perform credentials/info for update the certificate info.

credentials/info

This function will return the credential, identity information and the public key certificate or the certificate chain associated to the client. It also provides which authentication method of client supported.

Note 01: Authorization info in the header of the request is presented in following format:

KEY=Authorization, VALUE=Bearer <access token or refresh token>

(Access token or refresh token is obtained from login function which is defined in session 2.2).

Sample Request:

POST /rssp/v1/credentials/info HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

"relyingParty": "MOBILE-ID",

"relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

"certificateID": 5,

"certificates": "chain",

"certificateInfo": true,

"authenticationInfo": true,

"language": "EN"

}

Sample Response:

{

"responseCode": 0,

"responseMessage": "Successfully",

"billCode": "MOBILE-ID-190611194921-3-559951",

"certificate": {

"status": "valid",

"certificates": [

"<Base64-encoded_X.509_end_entity_certificate>",

"<Base64-encoded_X.509_intermediate_CA_certificate>",

"<Base64-encoded_X.509_root_CA_certificate>"

"issuerDN": "<X.500_issuer_DN_printable_string>",

"serialNumber": "5AAC41CD8FA22B953640",

"thumbprint": "86f7e437faa5a7fce15d1ddcb9eaeaea377667b8",

"subjectDN": "<X.500_subject_DN_printable_string>",

"validFrom": "20180101100000Z",

"validTo": "20190101095959Z",

"sharedMode": 1,

"createdRP": "MOBILE-ID"

"authorizeMethod": [

"numSignatures": 5,

"authMode": "explicit",

"SCAL": 2,

"language": "EN"

}

Attributes description:

Request Attributes
No	Name	Type	Require	Description
1	relyingPartyBillCode	String	O	Relying Party’s billcode
2	billCode	String	O	Request’s bill code.
3	agreementUUID	String	RC	The uuid of agreement, this value was returned from the agreement registration (SOAP API). This param require when access_token is retrieved from login with SSL2 Only.
4	thumbprint	String	M	The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.
5	certificates	String	O	Specifies which certificates from the certificate chain will be return in the response. § “none”: No certificate will be returned. § “single”: Only signer certificate will be returned. § “chain”: The full certificate chain will be returned. If this attribute is omitted, the the default is “single” will be treated.
6	certificateInfo	Boolean	O	Returns the details of certificate information. This is useful in case the signature application wants to retrieve some details of the certificate without having to decode it first. The default value is “false”, so if the parameter is omitted then the information will not be returned.
7	authenticationInfo	Boolean	O	Returns the authentication method which is supported for a client. The default value is “false”, so if the parameter is omitted then the information will not be returned.
8	language	String	O	Possible value: VN, EN

Response Attributes
No	Name	Type	Require	Description
1	responseCode	int	M	Code describes the result. Expected: 1007
2	responseMessage	String	M	Message describes the result in detail.
3	billCode	String	M	Receipt for each transaction
4	certificate/status	String	O	The status of signer certificate which is binding with the client. Some examples responses: § “not enrolled” § “valid” § “unknown” § “revoked” § “expired”
5	certificate/certificates	String[]	RC	One or more Base64-encoded X.509v3 certificates from the certificate chain. If the certificates parameter is “chain”, the entire certificate chain SHALL be returned with the end entity certificate at the beginning of the array. If the certificates parameter is “single”, only the end entity certificate SHALL be returned. If the certificates parameter is “none”, this value SHALL NOT be returned.
6	certificate/issuerDN	String	RC	The Issuer Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string. This value will be returned when certificateInfo is “true”.
7	certificate/serialNumber	String	RC	The Serial Number from the X.509v3 end entity certificate represented as hex-encoded string format. This value will be returned when certificateInfo is “true”.
8	certificate/thumbprint	String	M	The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.
9	certificate/subjectDN	String	RC	The Subject Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string. This value will be returned when certificateInfo is “true”.
10	certificate/validFrom	String	RC	The validity start date from the X.509v3 end entity certificate as character string. This value will be returned when certificateInfo is “true”.
11	certificate/validTo	String	RC	The validity end date from the X.509v3 end entity certificate as character string. This value will be returned when certificateInfo is “true”.
12	certificate/certificateProfile/name	String	M	Name of certificate’s profile. This value will be returned when certificateInfo is “true”.
13	certificate/certificateProfile/description	String	M	Description of certificate’s profile. This value will be returned when certificateInfo is “true”.
14	certificate/purpose	String	O	Purpose usage of the certificate.
15	sharedMode	String	O	Which sharing mode will be used in the Remote Signing. The possible values are: · “PRIVATE_MODE” · “RP_SHARED_MODE” · “AGREEMENT_SHARED_MODE” Default value is PRIVATE_MODE. It’s meant once Relying Party don’t use this parameter, the PRIVATE_MODE is used instead
16	createdRP	String	O	This is Relying Party name. It indicates that the certificate was created by that RP. It is helpful if the certificate is shared to an agreement from different RP.
17	numSignatures	int	M	A number equal or higher to 1 representing the maximum number of signatures that can be created with this credential with a single authorization request.
18	authModeSupported	String[]	M	Specifies one of the authorization modes. § “EXPLICIT/PIN”: the authorization process is managed by the signature application, authentication method is passcode. § “EXPLICIT/OTP-SMS”: the authorization process is managed by the signature application, authentication method is otp sms. § “EXPLICIT/OTP-EMAIL”: the authorization process is managed by the signature application, authentication method is otp email. § “IMPLICIT/CYBER-ID”: the authorization process is managed by the remote service autonomously. Authentication factors are managed by the RSSP by interacting directly with the user, and not by the signature application. § “IMPLICIT/BIP-CATTP”: the authorization process is managed by Cyber-ID – a mobile application – which could interact to PKI USIM for signing. § “EXPLICIT/OTP-MOBILE”: the authorization process is managed by OTP Mobile Application. § “OAUTH2”: not implement yet.
19	authMode	String	M	One value in values of No.15, is authorization mode activated at moment. To change must make by RSSP administrator.
20	SCAL	int	O	§ 1: The hash to-be-signed is not linked to the signature activation data. § 2: The hash to-be-signed is linked to the signature activation data.
21	contractExpirationDt	String	O	Contract's expiration date, to reissue certificate for compensation.
22	remainingSigningCounter	int	O	Remaining signing counter of this certificate. § -1: unlimited. § 0: out of signing.
23	authorizationEmail	String	RC	Authorization email. This value will be returned when authenticationInfo is “true”.
24	authorizationPhone	String	RC	Authorization phone. This value will be returned when authenticationInfo is “true”.
25	passphraseDefault	boolean	RC	True if passphrase is default and user must change passphrase before do cryptography.

Note: authMode is an array combined all authorization method which support for certificateID.

credentials/sendOTP

This method requests a One-Time Password (OTP) for client authentication. Based on client credential, Remote Signing service uses OTP generation mechanism to create and send OTP to end-user through agreed channel such as Email, SMS.

Note 01: Authorization info in the header of the request is presented in following format:

KEY=Authorization, VALUE=Bearer <access token or refresh token>

(Access token or refresh token is obtained from login function which is defined in session 2.2).

Sample Request:

POST /rssp/v1/credentials/sendOTP HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

"relyingParty": "MOBILE-ID",

"relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

"certificateID": 84902,

"authorizeMethod": 1,

"notificationTemplate": "RemoteSigning: Your authorization code {AuthorizeCode}",

"notificationSubject": "Remote Signing - Your authorization code",

"language": "EN"

}

Sample Response:

{

"responseCode": 1007,

"responseMessage": "Request accepted",

"billCode": "MOBILE-ID-190611194921-3-559951"

}

Attributes description:

Request Attributes
No	Name	Type	Require	Description
1	relyingPartyBillCode	String	O	Relying Party’s billcode.
2	billCode	String	O	Request’s bill code.
3	agreementUUID	String	RC	The uuid of agreement, this value was returned from the agreement registration (SOAP API). This param require when access_token is retrieved from login with SSL2 Only.
4	thumbprint	String	M	The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.
5	notificationTemplate	String	O	Message contains Authorize Code will be sent to customer’s Phone/Email. Authorize Code is generated on Remote Signing and embedded into template. E.g: Your authorization code: {AuthorizeCode}. Authorize Code is valid within 300 seconds.
6	notificationSubject	String	O	This parameter is used as Email subject for signing authorization. If OTP Email is used, this parameter is mandatory It should be used in case of the Remote Signing will use owned SMTP to send OTP Email to customer.
7	language	String	O	Possible value: VN, EN

Response Attributes
No	Name	Type	Require	Description
1	responseCode	int	M	Code describes the result. Expected: 1007
2	responseMessage	String	M	Message describes the result in detail.
3	billCode	String	M	Receipt for each transaction
4	temporaryLockTime	Int	RC	Certificate lockout time, only try again when the time is up. In seconds.

credentials/authorize

The function requests the Remote Signing to verify the client credential, it is not only OTP but also the PIN (or PassCode) supported. Once authorization code is valid, Remote Signing will respond the Signature Activation Data (SAD) which is required to authorize the signatures/SignHash method.

Note 01: Authorization info in the header of the request is presented in following format:

KEY=Authorization, VALUE=Bearer <access token or refresh token>

(Access token or refresh token is obtained from login function which is defined in session 2.2).

Note 02: Once the server successfully authorized the credentials, a session will be created binding with an agreementUUID/CertificateID, this session contains IP/Mac Address of the client. Another client using the same agreementUUID/CertificateID on another computer cannot be processed by Remote Signing service until this session released. Session will be released by calling auth/revoke with tokenType is SAD token, as defined in session 2.3.

Note 03: The HTTP-response has the header with name rssp-entity-name, RP must send it in HTTP-request header with name rssp-entity-name of these requests: credentials/extendTransaction, signature/signHash.

Sample Request:

POST /rssp/v1/credentials/authorize HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

"relyingParty": "MOBILE-ID",

"relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

"certificateID": 84902,

"billCode": "MOBILE-ID-190611194921-3-559951",

"authorizeCode": "654321",

"authorizeMethod": 1,

"numSignatures": 2,

"hash": [

"532eaabd9574880dbf76b9b8cc00832c20a6ec113d682299550d7a6e0f345e25",

"bd9c74f0a16ddc8c877651085e161824be897aa129604326fe67bc2a41316b77"

"hashAlgorithm": "sha-256",

"language": "EN",

"notificationTitle":"Dịch vụ SMART-ID",

"notificationMessage":"Yêu cầu cần được xác thực",

"messageCaption":"Đăng nhập dịch vụ VPN",

"transactionInfo":{

"Dịch vụ":"VPN của Mobile-ID",

"Địa điểm":"Hồ Chí Minh"

"clientInfo":{

"iccid":"8991101200003204514",

"imei":"990000862471854",

"macAddr":"00:0a:95:9d:68:16"

"message":"Complete the authentication to use the service",

"logoURI":"https://rssp.mobile-id.vn/images/mobile-id_logo_159x50.png",

"bgImageURI":"https://rssp.mobile-id.vn/images/background02.jpg",

"rpIconURI":"https://rssp.mobile-id.vn/images/mobile-id_logo_159x50.png",

"rpName":"MOBILE_ID",

"confirmationPolicy":"PIN",

"expirationDuration":3,

"vcEnabled":true,

"acEnabled":false,

"messagingMode":1,

}

Sample Response:

{

"responseCode": 0,

"responseMessage": "Successfully",

"billCode": "MOBILE-ID-190611194921-3-559951",

"SAD": "_TiHRG-bAH3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5_pw",

"expiresIn": 60,

"remainingCounter": 5

}

Attributes description:

Request Attributes
No	Name	Type	Require	Description
1	relyingPartyBillCode	String	O	Relying Party’s billcode.
2	billCode	String	O	Request’s bill code.
3	agreementUUID	String	RC	The uuid of agreement, this value was returned from the agreement registration (SOAP API). This param require when access_token is retrieved from login with SSL2 Only.
4	thumbprint	String	M	The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.
5	authorizeCode	String	RC	Authorize Code provided by customer. It could be PIN (PassCode) or OTP. It is required when authMode returned in credentials/info is EXPLICIT/PIN or EXPLICIT/OTP-SMS or EXPLICIT/OTP-EMAIL or EXPLICIT/OTP-MOBILE.
6	language	String	O	Possible value: VN, EN
7	numSignatures	int	M	The number of signatures to authorize. Multi-signature transactions can be obtained by using a combination of passing an array of hash values and calling the signatures/signHash method
8	hash	String[]	RC	One or more Base64-encoded hash values to be signed. It is required when SCAL is level 2.
9	hashAlgorithm	String