Understanding how the authentication process works in ClearIP can help users configure appropriate policies and troubleshoot problems.
For more information on authentication policies and configuration details, please refer to the Authentication Policies page. This page will break down the steps of the authentication process in ClearIP, authentication error handling (policy action configuration) throughout the process and common questions that can arise during authentication configuration.
Policy Check
The first step in the authentication process is to check that there is a policy enabled. As a reminder, ClearIP by default does not authenticate calls; users must configure policies to enable authentication. ClearIP supports the following authentication methods:
- In-Band: PASSporT token returned as an identity header in the SIP Messaging.
- Out-of-Band: PASSporT token submitted directly to terminating service provider’s call placement service (CPS), independent of the call routing.
- In-Band and Out-of-Band: Both above actions happen.
The Actions that can be taken during authentication are: ignore, attest or block. The overall behavior of the authentication process will depend on how users configure these Actions in their authentication policies. For more on policy setup, please read the Authentication Policies page.
Block Action Check
Some users might configure a policy in which they block certain calls by specific calling numbers. If this type of policy is enabled, and the calling number is not whitelisted, ClearIP will check for it at this point to end the authentication process. ClearIP will then return a ‘sti-blocked’ in the Reason header, as well as a 603 decline message in the SIP Response.
Asserted Calling and Asserted Called Number Checks
The next step in the authentication process is to check both calling and called number assertions are valid numbers. To qualify, as valid numbers, the following criteria must be met for each field:
- Asserted Calling Number: 7 to 15 digits
- Asserted Called Number: 7 to 15 digits, OR N11, 933, 988 numbers
If the Asserted Calling and/or Called Numbers are invalid based on the above, ClearIP will skip authentication and record the STI Authentication Status (viewable on SIP Messages page) as Invalid Calling and/or Called Number.
Certificate Retrieval
ClearIP will then retrieve the certificate stored in the system. Authentication cannot be enabled without a valid certificate. For more on certificates, please read the Certificates page.
Header and Token Creation
The next step in the authentication process is the construction of the Identity Header, which consists of the following main components:
- PASSporT - This is the Base64 encoded portion of the Identity header, which consists of the header, payload, and signature. The header and payload are what contain information about the call.
- info parameter - This is where the URL of the certificate repository is located.
- alg parameter - This is the algorithm used to create the signature.
- ppt parameter - This is where it is communicated that the token is used for STIR/SHAKEN.
During the payload construction is when the user’s policies on attestation and orgid are applied to set both the attest and orgid fields in the payload. Below is an example of an encoded Identity Header and its decoded header and payload.
Identity Header
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5LzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODU1NDc0MjUzNiJdfSwiaWF0IjoxNTc3ODM2ODAwLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5In0.abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123;info=<https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem>;alg=ES256;ppt=shaken
Decoded Header and Payload
{
"header": {
"alg": "ES256",
"ppt": "shaken",
"typ": "passport",
"x5u": "https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem"
},
"payload": {
"attest": "A",
"dest": {
"tn": [
"18554742536"
]
},
"iat": 1577836800,
"orig": {
"tn": "14045266060"
},
"origid": "99999999-9999-4999-9999-999999999999"
},
"signature": "abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123"
}
Token Signature
After successfully constructing the header and token, ClearIP will then sign the token. Digital signatures are created with a hashing algorithm; hashing compresses a message for easier handling.
To create the digital signature, the authentication service inputs the token header and payload into the hashing algorithm and obtains the hash value.
Then the authentication service obtains the originating provider’s private key from the secure key store to create the signature.
The signature is created by a signature generation algorithm, which uses the private key and hash value to create a digital signature unique to the originating provider, token header and payload. This ensures the digital signature cannot be used by a different service provider and cannot be reused later for a different call by any service provider.
The digital signature is then combined with the original token header and payload to create the signed PASSporT.
In-Band and Out-of-Band
The final step of the authorization process is to send the signed PASSporT, depending on whether In-Band, Out-of-Band or both are being used.
If doing In-Band STIR/SHAKEN, ClearIP will put the signed PASSporT token into the Identity header, which will be sent to the originating service provide in a SIP Response. The OSP then must use the Identity header and put it into the SIP Invite they send to the terminating service provider.
If doing Out-of-Band SHAKEN, the signed PASSporT will be sent to the call placement service via the internet.