Business Chat Sending Authenticate Messages. June

Transcription

1 Business Chat Sending Authenticate Messages June

2 Contents Overview 3 Capabilities... 3 How to Pass Authenticate Data... 3 User Authorization with Safari Password AutoFill... 8 Decrypting the Auth Token... 8 Decryption Example... 8 How to Decrypt Your Auth Token... 9 Request Data Dictionary Authenticate Data Dictionary OAuth2 Data Dictionary Response Error Response Dictionary Error codes Business Chat Sending Authenticate Messages June

3 Overview Business Chat allows authentication data to pass between customers and businesses on the Customer Service Platform (CSP) using the OAuth 2.0 protocol. Businesses are required to supply authentication details about the OAuth provider, including authentication endpoint URLs, client identifier, and business information verified by Apple Business Register. Changing any of these authentication parameters requires additional verification and approval from multiple customers that own or administer the business. Capabilities The auth capability is included in the capabilities header of the message request for customer devices that support the Authenticate message. Devices with ios 12 or later and macos or later support Authenticate message. CSPs can send Authenticate messages to a customer s device with auth capability announced. In Integrating with Business Chat, under Authorize a Message, the following information will be added: capabilities A string list that identifies Business Chat features supported by the customer s device. The list is case insensitive and separated by commas. When a customer sends a message, the Customer Service Platform (CSP) can obtain the customer device capabilities to compose an appropriate response message for that device. Possible value is auth for Authenticate message support. See How to Pass Authenticate Data. How to Pass Authenticate Data To pass Authenticate data, send a POST request to /v1/authenticate endpoint hosted by Business Chat, with the authenticate message in the request body. Authenticate requests sent by a business to a user should be secured. The OAuth provider endpoints should present a valid Extended Validation (EV) certificate. The Authenticate Data dictionary and the responseencryptionkey are used to authenticate to the OAuth provider endpoints. This allows the OAuth provider to audit the public key that is used to encrypt the OAuth access token. The requestidentifier in the data dictionary is used to identity the authentication request and to map the access token in the response to the request originator. The requestidentifier and responseencryptionkey can be generated by either the business or the CSP. Business Chat returns a JSON dictionary containing the encrypted token field. The business or CSP can decrypt the access token and verify the user access. When this responsibility is owned by the business, the business and CSP should implement the delegation of key generation. Key verification and access token verification are highlighted by the orange boxes in Figure 1. Business Chat Sending Authenticate Messages June

4 Figure 1 Authentication flow between a CSP and a user's device. Business Chat Sending Authenticate Messages June

5 The following examples show an authentication request (Listing 1), with its corresponding successful (Listing 2) and failed (Listing 3) responses. interactivedata : { "bid": "com.apple.messages.msmessageextensionballoonplugin: :com.apple.icloud.apps.messages.business.extension", "data": { version": "1.0", "requestidentifier": "3EF748B5-3DC5-47AE-B185-91E91518D105", "authenticate" : { "oauth2": { "responsetype" : "code", "scope" : [" ", "profile"], "state" : "security_token", "responseencryptionkey" : BFz948MTG3OQ0Q69JHUiBG7dZ3SMGU1s2bVG9Hu yx/heu4h0pqjujm/j93uqyvobm8+i0algdvpoz+ujzy6ygmu=, "authorizationurl" : "accesstokenurl" : "clientidentifier" : "client_identifier" } "images": [ { "data": ivborw0kggoaaaansuheugaaalqaaac0caiaaacyr5flaaaagxrfwhrtb2 Z0d2FyZQBBZG9iZSBJbW [output truncated]", "identifier": "1" } ] "receivedmessage": { "title": "Sign In to Green Bank", "imageidentifier": "1" "replymessage": { "title": "You Signed In", "imageidentifier": "1" } Listing 1 A sample of an Authenticate request sent to a customer. Business Chat Sending Authenticate Messages June

6 { "data": { "version": "1.0", "requestidentifier": "8EF748B5-3DC5-47AE-B185-65E91518D209", "authenticate": { "status":"authenticated", "token": "<Base 64 encrypted token>" "images": [{ "data": "ivborw0kggoaaaansuheugaaadiaaaaycaiaaacrxr\/ maaaaaxnsr0iars4c6qaaabxpre9uaa[output truncated]", "identifier": "1" }] "bid": "com.apple.messages.msmessageextensionballoonplugin: :com.apple.icloud.apps.messages.business.extension", "receivedmessage": { } "title": "Sign In to Green Bank", "subtitle": "Authentication required to access your customer data", "style": "icon", "imageidentifier": "1" "replymessage": { "title": "You Signed In", "subtitle": "", "style": "icon", "imageidentifier": "1" } Listing 2 A sample of a successful Authenticate response sent to CSP. Business Chat Sending Authenticate Messages June

7 { "data": { "version": "1.0", "requestidentifier": "8EF748B5-3DC5-47AE-B185-65E91518D209", "authenticate": { "status":"failed", "errors": [{ "code": 2, "domain": "com.apple.icloud.messages.business.cryptor", "message": "Key is not UTF8" }] "images": [{ "data": "ivborw0kggoaaaansuheugaaadiaaaaycaiaaacrxr\/ maaaaaxnsr0iars4c6qaaabxpre9uaaaaagaaaaaaaaazaaaakaaaabkaaaazaaaafq7npu0aaa BJSURBVFgJ7NTBCQAwCENR5+n++9WuICXg4YHnED4\/ Vp278TZ2eqTUmtiCFlopB1K5n+9QLcqnHEjlUn7iLFpoWeLEAbTQCjnQAAAA\/\/ +ttsshaaaarkleqvtt1mejadaiq1hn6f771a4gjedhgecqpj9wnbvxnnz6pnsa2iiwwikhurmf7 1AtyqccSOVSfuIsWmhZ4sQBtNAKOdCb3VUKqviC4gAAAABJRU5ErkJggg==", "identifier": "1" }] "bid": "com.apple.messages.msmessageextensionballoonplugin: :com.apple.icloud.apps.messages.business.extension", "receivedmessage": { "title": "Sign In to Green Bank", "subtitle": "Authentication required to access your customer data", "style": "icon", "imageidentifier": "1" "replymessage": { "title": "Authentication Failed", "subtitle": "", "style": "icon", "imageidentifier": "1" } Listing 3 A sample of a failed Authenticate response sent to CSP. Business Chat Sending Authenticate Messages June

8 User Authorization with Safari Password AutoFill To support the OAuth exchange using Safari 12 for ios 12 and Safari 12 for macos 10.14, the web sheet must support the Safari Password Autofill. In Figure 1, the flow chart shows User Authorization after OAuth request/response. In this step, the user s device is redirected to a URL that triggers a web sheet to pop up. For example, a Log In web sheet. The web sheet is not a full Safari app as some menu items are hidden, like the address bar. For the Log In sheet, the user is expected to submit their username and password to continue the flow. The web sheet must support Safari Password AutoFill by annotating the autocomplete attribute in this format: <input autocomplete= value > Possible values for the autocomplete attribute are username, current-password, new-password, and one-time-code. For more information on Safari Password AutoFill, see What s New in Safari. Decrypting the Auth Token To authenticate users you need to decrypt the encrypted authentication token from the response. This section explains the method used to decrypt the authentication token. To begin with, the authentication token should have the following qualities: The public key specified in the authenticate request should be an 384-bit EC public key (Elliptic curve secp384r1). The OAuth authentication token provided to the Customer Service Platform (CSP) is encrypted by the customer's device using the eciesencryptioncofactorvariableivx963sha256aesgcm algorithm. The business or CSP uses the associated private key generated for the request to decrypt and obtain the clear text auth token. Decryption Example In this example, all binary data is Base64-encoded. The public key in the request is encoded in X9.63 uncompressed form. The example private key is represented as the unsigned scalar converted to bytes. The private key is not sent in the request, so businesses can choose any encoding format. The following private key, public key, and encrypted auth token examples are used throughout this example. Public Key BNY+I93aHVkXnNWKVLdrMJLXpQ1BsyHYoiv6UNi4rDUsRx3sNNhW8FNy9yUwxYprAwwfj1ZkoJ6 1Fs+SwjIbGPtXi52arvSbPglyBN4uAxtP3VP3LCP4JtSEjdgsgsretA== Private Key px/bvdxxudpc79mw/jwi10z6pjb5sby2+aqkr/qyojqgakksqzfknl0kz10ve+bp Business Chat Sending Authenticate Messages June

9 Encrypted Auth Token BDiRKNnPiPUb5oala31nkmCaXMB0iyWy3Q93p6fN7vPxEQSUlFVsInkJzPBBqmW1FUIY1KBA3BQ b3w3qv4akz8kblqbmvupe/ EJzPKbROZFBNvxpvVOHHgO2qadmHAjHSmnxUuxrpKxopWnOgyhzUx+mBUTao0pcEgqZFw0Y/ qzijpf1kuscmlz5tahpjsw= The data bytes in encrypted auth token are composed of the following parts: n-15 N-16 n-1 0x04 Ephemeral Public Key Encrypted Data Encryption Tag How to Decrypt Your Auth Token 1. Extract the ephemeral public key from the encrypted data. The first byte 0x04 indicates the key in uncompressed form. Since the key is over secp384r1 curve, the key data is 96 bytes (384/8 * 2). The ephemeral key data in uncompressed form: BDiRKNnPiPUb5oala31nkmCaXMB0iyWy3Q93p6fN7vPxEQSUlFVsInkJzPBBqmW1FUIY 1KBA3BQb3W3Qv4akZ8kblqbmvupE/EJzPKbROZFBNvxpvVOHHgO2qadmHAjHSg== The following is confirmation that the ephemeral key data was correctly decoded: (curve=secp384r1,x= , y= ) 2. Perform an Elliptic Curve Diffie-Hellman with Cofactor operation using the ephemeral public key obtained in Step 1 and the private key. After using the Elliptic Curve Diffie-Hellman with Cofactor operation, you should be presented with the following shared key: 2lvSJsBO2keUHRfvPG6C1RMUmGpuDbdgNrZ9YD7RYnvAcfgq/fjeYr1p0hWABeif 3. Run the shared key, obtained in Step 2, through a key derivation function (KDF) to generate 48 bytes of data. The first 32 bytes yields the key and the last 16 bytes the initialization vector (IV) that is used to perform the decryption. To generate the bytes of data, use the following KDF2 algorithm with SHA256 hash function on the ephemeral key data, obtained in Step 1, as additional data passed to the derivation function. See Key Derivation Functions: How many KDFs are there? A. Set d = ceiling(klen/hlen) B. Set T = "", the empty string Business Chat Sending Authenticate Messages June

10 C. For Counter = 1-d do: where: C = IntegerToString(Counter, 4) T = T Hash(Z C [other_data]) Hash is the hash function with output hlen in bytes, must be 48 bytes Z is the shared key [other_data] is the extra shared material and it must be set to the ephemeral key bytes (97 bytes) D. Output the first klen bytes of T as K. The resulting output is the derived key, K, of length klen bytes. KDF output: mazkyatdlz4szrcym23nhgl/+me3eggfuz9h1cfphzotxequzn3q8w+b5ge2eu5g Decryption key (first 32 bytes of KDF output): mazkyatdlz4szrcym23nhgl/ +me3eggfuz9h1cfphzm= Decryption IV (last 16 bytes): rv3qrszd0pmpgerhnnloya== The last 16 bytes of the encrypted data is the tag used in Step 4. This is also represented in the table showing the byte layout of the N byte encrypted data. You should have the following encrypted data with last 16 bytes representing the tag to use for decryption with AES-GCM in Step 4: Encrypted data: affs7gukrgilac6dkhnth6yfrnqjslwscpkxdrj+ Tag: pkgk9/uq6wiyxplmcgmoza== 4. Perform decryption using AES-GCM with the key and IV obtained in Step 3. The tag in Step 4 needs to be passed in for performing message authentication code (MAC) validation. This yields the plain text token: "xxti32izwrq6o8sy6r1iskwf6ff1py" (actual string token, not Base64-encoded) If the key's derived in Step 3 or the associated tag is incorrect the decryption fails. Tokens that fail decryption, including associated tag validation, must be rejected. Request Authenticate request is an interactive message. When composing an Authenticate message, include the Authenticate Data Dictionary in the interactive data's data dictionary to describe the behavior and content of the authentication request. Data Dictionary The data dictionary keys for an Authenticate message are: version A numerical version number of the message extension schema; the version should be 1.0. requestidentifier An identifier for the request. Business Chat returns the identifier in the response it sends back to the CSP. Business Chat Sending Authenticate Messages June

11 images An array of image dictionaries. For the list of keys in the image dictionary, see Image Item Dictionary. authenticate A dictionary that describes the authentication request. For more information about this dictionary, see Authenticate Data Dictionary. Authenticate Data Dictionary The Authenticate dictionary contains the following key: oauth2 A dictionary of OAuth parameters. See OAuth Data Dictionary. OAuth2 Data Dictionary The OAuth dictionary keys are as follows and can be expanded to include other keys from RFC responsetype A string indicating the type of authentication request. Business Chat only supports token or code access request types. scope An array of scope items that specifies the scope of the request. This is defined by the business. state A string indicating the state of the authentication request. responseencryptionkey A string indicating the Base64 encoded public key that is used to encrypt the access token sent back in the response. authorizationurl A string indicating the authorization endpoint that authenticates the access request owner. It can issue the access token when performing an implicit grant. For more detail on implicit grant, see RFC accesstokenurl A string that indicates the token endpoint that issues the access token when performing an authorization code grant. For more detail on authorization code grant, see RFC clientidentifier A string that uniquely identifies the access request owner, provisioned by the authorization server. Business Chat Sending Authenticate Messages June

12 Response The response body is a JSON dictionary containing the following keys: status A string indicating the status of the authentication request. token (Optional) A string of the Base64 encoded authentication token that is encrypted with the responseencryptionkey from the request when authentication was successful. errors (Optional) A list of errors for authentication failure case. For the list of error dictionary keys, see Error Response Dictionary. Error Response Dictionary The dictionary keys are as follows: code Numerical error code. See Error Codes. domain A string indicating the error domain. message A string indicating the description of the error. Error codes The following errors may be returned by the device. All domains listed in the table are read as com.apple.icloud.messages.business.<domain> Error Domain Code Message Description BCTokenMissingError.authentication 1 Missing Token or Missing Code Thrown when the authentication plugin cannot retrieve a token or a code from the redirect URL. BCEmptyDataReceived Error BCAccessTokenMissing FromResponseError.authentication 2 Empty data received when exchanging token..authentication 3 Missing access token from response. Thrown when the authentication plugin receives an empty response when exchanging the code for a token. Thrown when the authentication plugin receive an valid response but the response is missing access_token from the JSON body. Business Chat Sending Authenticate Messages June

13 Error Domain Code Message Description BCPublicKeyIsEmpty Error.cryptor 1 Empty string received for key. Thrown when the crypto is given an empty public key. BCPublicKeyIsNotUTF8 Error.cryptor 2 Key is not UTF8. Thrown when the cryptor base64 decodes the public key and fails because the encoding is not UTF8. BCPublicKeyIsInvalid Error BCPublicKeyInternal Error.cryptor 3 Public key is invalid..cryptor 3 Failed adding key OR failed reading key OR failed deleting key. Thrown when the cryptor fails to validate the key against SecKeyAlgorith.eciesEnCry ptioncofactorvariablevx963 SHA256AESGCM. Thrown when the cryptor cannot complete the given task due to internal error. BCEncryptionError.cryptor 4 Unable to encrypt token. Thrown when the cryptor fails to encrypt a given payload using the provided public key Apple Inc. All rights reserved. Apple and the Apple logo are trademarks of Apple Inc., registered in the U.S. and other countries. Business Chat Sending Authenticate Messages June