API Authentication / Authorization

Requests to IDI’s APIs are authenticated to ensure the resources provided by the API are only accessed by authorized clients. Depending on the API being used different levels of authorization may be required. Details on the required level of authorization will be indicated on the API operation documentation if more than an authenticated user is required.

Authentication

Authentication of IDI’s APIs is accomplished using a WS-Trust protocol. Specifically, IDI relies on a security token supplied by a Security Token Service (STS) to authenticate API requests. Depending on the resource the request may require a SAML Token, for SOAP requests, or a Simple Web Token (SWT), for RESTful requests, for authentication. The following diagram illustrates IDI’s implementation of the WS-Trust protocol.

Simple Web Token (SWT)

A Simple Web Token (SWT) is the primary form of authorization for IDI’s RESTful APIs. To get a new SWT a client must request one from the Security service using the api/login method. The URI for this API is https://api.idibilling.com/securitytoken/1x/environment/api/login. Once an SWT has been obtained it should be passed along to all future RESTful API requests in the form of an Authorization header. The header key should use the following format WRAP access_token=”<security token>”.

SAML Token

A SAML (Security Assertion Markup Language) Token is primary form of authorization for SOAP based APIs. To get a new SAML Token a client must request one from the Security service using the Issue operation. The URI for this API is https://api.idibilling.com/securitytoken/1x/environment. Once a SAML token has been obtained it should be passed along to all future SOAP API requests within the SOAP envelope header. SAML Tokens are more complex than SWT and require more in depth understanding on how to incorporate them into the request. Please see Securing SOAP Messages below for more information.

Authorization

Authorization is handled server side by the webservice by checking the security token for the appropriate claims, and expiration information. All the required information to do the authorization is included with the security token and is signed by IDI to prevent tampering. Any attempt to alter a security token will invalidate the token and will cause the authorization of that token to fail.

To limit potential security threats a security token has a predefined expiration date. A new security token should be acquired before this expiration date to prevent authorization failures. It is IDI’s recommendation that clients refresh their security tokens after it has reached 80% of its lifetime to prevent these scenarios.

Web Service Users

Web service users are most basic type of user. IDI will set one of these users up for clients to use for API access in any of their environments. Web service users when accessing an API will not be restricted to accessing any information within the environment, for this reason the credentials for the web service user should always be kept secure and never transmitted to client facing application. To obtain the credentials for your web service user please see your Account Manager for details. You should consider using a web service user if

• Recording the actual user for auditing / logging is not a concern
• Backend or automated processes

Application Users

Application users are users which are setup by clients for access to the system. Application users by themselves cannot directly communicate with IDI APIs, instead an application user must login using both their own credentials supplied through a login screen, and an underlying web service user’s credentials supplied by backend configuration. An application user differs from a web service user in that an application user will have a set of claims associated to them that differ from environment to environment. These claims will help dictate what API operations the user should or should not have access to. You should consider using an application user if

• The user making the updates needs to be recorded for auditing purposes.
• The client application wishes to check the claims of a user.
• Server side restrictions such as customer limit tos need to be enforced on the authenticated user.

Securing SOAP Messages

IDI SOAP based APIs rely on both signing and encrypting algorithms to protect and authenticate API calls.

Encrypting Responses

IDI’s APIs currently rely on encryption to secure the claims being transmitted to the clients. The information contained within these claims mostly indicate basic user information such as name, login environment and granted permissions for the application they have signed into. The claims within the SAML token will also contain a SWT that can be used to make RESTful API calls, this allows clients to make a single sign in call and retrieve security tokens for both types of APIs. If a client wishes to decrypt the SAML token they will need to use the public key contained with the IDISaaSWebServices-Customer.pfx 

Signing Responses

In additional to message encryption IDIs APIs will also sign their responses. By signing all responses, a receiving client can verify that the payload received originated from IDI and was not altered in any way. If a client wants to verify the signature or is using a library that automatically validates the signature you will need to install the following certificate on the client machine IDISaaSSecurityToken-NoPrivateKey.p7b.

Signing Requests

Every request made to a SOAP bases IDI API in addition to needing a security token must also be signed to ensure the message is being sent from a legitimate source and has not been tampered with. To do this the API relies on standard XML signatures.

Security Token RESPONSE

The security token response returned from the call to the issue operation will contain two key components that will be required to sign the message. These two values are

1. 1. SecurityTokenReference

<o:SecurityTokenReference k:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:k="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd">
	<o:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID">_779a5338-26ed-4b91-8ed3-ca3e366652b5</o:KeyIdentifier>
</o:SecurityTokenReference>

1. 1. BinarySecret

<trust:BinarySecret>omitted for security purposes</trust:BinarySecret>

1. EncyptedData

<xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
	<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
	<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
		<e:EncryptedKey xmlns:e="http://www.w3.org/2001/04/xmlenc#">
			<e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">
				<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
			</e:EncryptionMethod>
			<KeyInfo>
				<o:SecurityTokenReference xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
					<X509Data>
						<X509IssuerSerial>
							<X509IssuerName>CN=IDIBILL-ISSUING-CA, DC=idibill, DC=com</X509IssuerName>
							<X509SerialNumber>omitted for security purposes</X509SerialNumber>
						</X509IssuerSerial>
					</X509Data>
				</o:SecurityTokenReference>
			</KeyInfo>
			<e:CipherData>
				<e:CipherValue>omitted for security purposes</e:CipherValue>
			</e:CipherData>
		</e:EncryptedKey>
	</KeyInfo>
	<xenc:CipherData>
		<xenc:CipherValue>omitted for security purposes</xenc:CipherValue>
	</xenc:CipherData>
</xenc:EncryptedData>

Web Service Request

In order to properly sign a web service request the following components need to be added the soap message.

1. TimeStamp: This is what is going be signed. This timestamp should be limited to a 5-minute duration that encompasses the current time.
2. EncryptedData: This should be copied directly from EncryptedDate (#3) of the security token response.
3. SignedInfo
   1. Reference: to the timestamp usually done by ID
   2. CanonicalizationMethod: this should be “http://www.w3.org/2001/10/xml-exc-c14n#”.
   3. DigestMethod: algorithm that should be “http://www.w3.org/2000/09/xmldsig#sha1”.
   4. DigestValue: the actual digest value for the timestamp calculated using 2 & 3 above.
4. SignatureValue: This should be the computed signature value of the DigestValue using the BinarySecret (#2) from the security token response. Note the binary secret from the response is base64 encoded you will need to decode this properly to get the actual bytes of the key.
5. SecurityTokenReference: This should be set from the SecurityTokenReference (#1) of the security token response

You can viewa full sample here: Web Service Request Sample