2.1 User Credentials and WS-Security

An EasyLink user account is necessary to use the Cloud Fax and Notifications API. Every web service request must include user credentials that identify the requesting user and authorize the request.

2.1.1 ID and Password

The most common method of providing these credentials is to include the user ID and password in the Request element in the SOAP Header of the request. The XDDSAuth child element must be used to carry this information. Use of the HTTPS protocol protects this information in transmission.

"Aliases" may exist for a user account, and these can be used instead of the user ID. Several different types of aliases exist, and the type of alias being provided must be indicated. The alias appears in the request in the same RequesterID element that is used for a user ID, just with the additional indicator of the type of alias being used. The password is still required. The most common use of aliases is for "Fax-to-Mail" users who use an "M2F" type of alias, which is their email address.

For most requests, using an alias is equivalent to using the user id. The exception to this is JobSubmit, where the type of user identification used may affect the subsequent processing of the message delivery - an "M2F" alias causing the creation of a "fax2mail" job in the EasyLink switch.

2.1.2 Site Access Restrictions

Certain customers may not wish to use certain installations of the Cloud Fax and Notifications API, usually for reasons of data sovereignty, and account settings can help protect against inadvertently using an inappropriate site. If an API request is received at such a site, the request will be rejected, and the response will contain an ErrorCode with the value 2920. Customers who encounter this unexpectedly should contact their representatives to ensure they are using the correct webservice endpoint URL.

2.1.3 X.509 Certificate and WS-Security

As an alternative to providing an ID and password in the request, Web Services Security (WS-Security 1.1) mechanisms can be used to digitally sign SOAP requests and provide the requesting user's X.509 certificate. A valid certificate identifies the user, and a valid signature authorizes the request. A Request SOAP header element is still required (as set out in the WSDLs), but it may not be necessary to provide any additional information relating to the requesting user. If additional information is necessary (see below), the WSSAuth element can be used instead of XDDSAuth. When a certificate and signature are provided in the request, they take precedence in identifying the requesting user.

Users may obtain an X.509 certificate from EasyLink that can be used in connection with the Cloud Fax and Notifications API. Certificates issued by other Certificate Authorities can also be used (providing EasyLink recognizes the CA), but must be registered with EasyLink in advance. (See instructions for obtaining or registering a certificate.)

Note that a certificate can only be associated with a single user account. Since the certificate is used to identify the particular user, it cannot be shared by multiple users.

The usability of a certificate involves not only a valid signature, but also the status of that certificate and the associated account. This means that certficates for discontinued accounts or that have been reported as compromised and removed from the EasyLink registration will not provide access to Cloud Fax and Notifications API services.

The WS-Security specification defines many methods for representing security information. The Cloud Fax and Notifications API will only accept certain specific usages of these methods:

• The X.509 certificate itself must be provided in the request, and must be referred to via a "direct reference"
• An XML digital signature must be present that can be verified with the provided certificate, and which includes at least the SOAP Body element of the request.

The request may include a certificate chain using either a X509PKIPathv1 BinarySecurityToken, or multiple X509v3 BinarySecurityTokens, although of course they must lead to certificates known to the Cloud Fax and Notifications API.

EasyLink does not currently support all WS-Security features. The limitations include:

• XML encryption is not supported.
• Signature confirmations are not provided.

In order to use this method, users must obtain an X.509 certificate from EasyLink or register a third-party X.509 certificate with EasyLink, and then use their private key (from the key pair used to generate the certificate request) in their application to prepare the request before it is sent to EasyLink. Users considering this should take into account the need to manage the deployment of their private key as well as the additional processing requirements. The ability of the development tools and deployment environment to correctly prepare requests (which have the potential to be quite large) should be considered as well.

A SOAP request using this method might look like this:

<tns:Envelope
    xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <tns:Header>
  <wsse:Security tns:mustUnderstand="1"
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <wsse:BinarySecurityToken
       EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
       ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
       wsu:Id="CertId-7A978793132DCD2B2C12972851078131"
       xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
       xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
...
   </wsse:BinarySecurityToken>
   <ds:Signature Id="Signature-1" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>
     <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
     <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
     <ds:Reference URI="#id-2">
      <ds:Transforms>
       <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      </ds:Transforms>
      <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
      <ds:DigestValue>7YZgmIHlqrtQsQx19iseBgFwRd8=</ds:DigestValue>
     </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>
...
    </ds:SignatureValue>
    <ds:KeyInfo Id="KeyId-7A978793132DCD2B2C12972851078582">
     <wsse:SecurityTokenReference
         wsu:Id="STRId-7A978793132DCD2B2C12972851078683"
         xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
         xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
      <wsse:Reference URI="#CertId-7A978793132DCD2B2C12972851078131"
          ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
          xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"/>
     </wsse:SecurityTokenReference>
    </ds:KeyInfo>
   </ds:Signature>
  </wsse:Security>
  <Request xmlns="http://ws.easylink.com/RequestResponse/2011/01">
   <ReceiverKey>http://messaging.easylink.com/soap/sync</ReceiverKey>
   <Authentication>
    <WSSAuth/>
   </Authentication>
  </Request>
 </tns:Header>
 <tns:Body wsu:Id="id-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <AuthenticateRequest xmlns="http://ws.easylink.com/Authenticate/2011/01"/>
 </tns:Body>
</tns:Envelope>

2.1.4 Additional User Information

As mentioned above, the type of ID used can affect the processing of a request - specifically the use of an "M2F" alias with a JobSubmit request. When an X.509 certificate is used to identify the user, this additional "type", if it is needed, can be provided using the WSSAuth/RequesterType element.

Certain users may be authorized to submit requests on behalf of other users. Fax2Mail administrators, for instance, may submit requests for members of the group(s) they administer. In these cases, the requester must provide valid credentials for themselves, and then indicate the user they are "acting as" by providing a TargetID. Just as for the requesting user, the TargetID may be a user ID or an alias. The alias type (if any) of the TargetID will determine any effect on the processing of the request.

2.1.5 WS-Security and Older Namespaces

Use of the current schemas is strongly encouraged, and the current WSDLs all support the WS-Security features described above. The supported WS-Security mechanisms can be used with the older WSDLs as well, but the schemas for those all require an XDDSAuth element to be present. If requests in those namespaces are digitally signed, then the Password element will be ignored, the TargetID will be used if present, and the alias type prefix (if any) of the RequesterID will be considered (but not the userid itself.)

2.1.6 Signed Replies

Users submitting requests signed with an X.509 certificate may want the reply to be signed by EasyLink. There may not be any real benefit from this for most applications, and the need for it should be carefully considered. But if it is necessary, EasyLink can sign these replies.

Various user environments and tools may have different requirements or expectations for signed replies. To accommodate these, different URL paths for the service endpoint provide different signing behavior:

User account settings may also influence the signing of replies and alter the default behavior described above.

Certificates may expire or be changed from time to time, so developers of applications that expect to process signed replies should make it relatively easy to update or expand the set of acceptable certificates.

When a reply is signed, a Timestamp element is added to the SOAP Header and both the Timestamp and the SOAP Body is covered by the signature. If the SOAP Header contains an EMAPI Response element in a namespace more recent than the "2009/07" namespaces, then the Response element will also be covered by the signature.