Onboarding using Sage Network Platform Authentication Service

Details of all calls can be found in API reference.

Sage Network Platform Authentication Service

The Authentication Service allows products to onboard their users’ Organisations and Companies with Sage Network Platform. This allows access to Sage Network Platform services using its JWT tokens.

There are 2 different approaches to onboarding that support the different types of products that we have in Sage:

• For cloud products we can trust our own servers with holding a secret. This determines whether the user can use Sage Network Platform.
• For products driven by a traditional desktop app the situation is more complicated. The application could be tampered with on the client, so we verify the users’ product license differently.

---

Terms and conditions

As part of the in-product onboarding process, a customer needs to agree to the Banking Service terms and conditions. Please refer to the terms and conditions documentation on Teams for the text that needs to be displayed to the customer. Onboarding should not proceed until the customer has agreed to these.

Entitlement

Onboarding for trusted Sage cloud products

1. Make a POST Organisation call to create an organisation.
   • Identify the calling application by using an x-application header
   • Sign the request using the secret signing key and the signature algorithm that Sage Network Platform adopts.
   • The generated OrganisationID will be returned in the response body, along with the PrimarySigningKey.
2. At this point, a JWT can be obtained to access the new organisation by making a GET AccessToken call.
   • Specify the X-OrganisationId header
   • Sign the request with the organisation’s PrimarySigningKey
   • The generated JWT will be returned in the response body.

3. Organisation companies can now be created by making a POST Company call, using the JWT in the Authorization header.

4. To use Sage Network Platform Domain Services, a JWT can be obtained for the company by making a GET AccessToken call.
   • Specify both the X-OrganisationId and X-CompanyId in the headers.
   • Sign the request with the Organisation’s PrimarySigningKey
   • A JWT access token is provided in the response.
5. This JWT access token can be attached to requests in the Authorization header to access Sage Network Platform Domain Services, including Banking Service.

Dynamic implementation (web products)

To support the frequent introduction of new banks supported by Banking Service, the in-product onboarding experience should not be bank specific. It should be developed using a dynamic implementation, or UI, that does not require any changes to the product. The API provides the means to achieve this.

Onboarding for Sage desktop applications

For desktop applications, a user’s access to a Sage Network Platform service is validated based on their product license. Another service supports the Authentication Service in dealing with licenses; the Sage Token Service. This hides the complexity of our licensing methods while considering security.

1. Request a token from the Sage Token Service using a POST requestToken call.
   • Specify the licencing mechanism in the x-provider header
   • Specify the desktop application in the x-application header
   • Licence details (serial number, etc.) should be in the body
   • A token is provided in the response. No attempt to validate the licence has occurred at this point; the user first will be required to process a CAPTCHA session to protect the service.

2. A redirect to the Authentication Service CAPTCHA will occur; the token from the previous step is provided in the query string.

3. Upon CAPTCHA validation, a second token is provided that can be used in a POST Organisation call. This second token usually obtained through a JS message posted to the parent window from the CAPTCHA, but the POST CAPTCHA endpoint can also be called to obtain this token.

4. Make a POST Organisation call.
   • Pass the token from the previous step in the Authorization header
   • This will trigger the creation of an Organisation; prior to this point, the licence has not been validated.
5. Poll the Organisation to complete the creation; the creation will not be created until the licence has been verified, which can take a short period.
   • When the Organisation has been completed, a 201 response will be received with the Organisation details, including the OrganisationID and the PrimarySigningKey.
6. To use Sage Network Platform Domain Services, a JWT can be obtained for the company by making a GET AccessToken call.
   • Specify both the X-OrganisationId and X-CompanyId in the headers.
   • Sign the request with the Organisation’s PrimarySigningKey
   • A JWT access token is provided in the response.
7. This JWT access token can be attached to requests in the Authorization header to access Sage Network Platform Domain Services, including Banking Service.

Additional considerations for working with Authentication Service JWTs

• Authentication Service JWTs expire after 10 minutes. It is recommended you take a proactive and reactive approach to token expiry. You should request a new token when an unauthenticated response is returned. Don’t try to use cached tokens that have expired.
• In order to help protect the signing key used to request JWTs, a signing key rotation mechanism is adopted by the Authentication Service. Periodically the key will be rotated; this is indicated by the presence of the X-Rotate-Key header containing the new key to be used. When the new key is used, the old signing key becomes invalid. Adoption of this process is mandatory.
• If the signing key for obtaining a JWT be lost, such as a user switching to another machine or a backup is restored, there is a CAPTCHA end point which will result in an email being sent with the key. This is only applicable for desktop products.
• The Payments Acceptance Service team are responsible for the maintenance and development of the Authentication Service.