Skip to content
Developer home

On-boarding Using Service Fabric Auth Service

  Less than to read

Details of all calls can be found in API Reference.

Service Fabric Auth Service

The Auth Service is responsible for allowing products to onboard their users’ Organisations and Companies with Service Fabric; this allows access to Service Fabric services using its JWT tokens.

There are two different approaches to on-boarding 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, and in determining whether the user is entitled to use Service Fabric.
  • For products driven by a traditional desktop app the situation is more complicated. The application could be tampered with on the client and as such a different mechanism is used which also verifies the users’ product license.

On-boarding 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 Service Fabric 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 Service Fabric 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 Service Fabric Domain Services, including Banking Service.

On-boarding for Sage Desktop Applications

In this scenario, a user’s access to a Service Fabric service is validated based on their product license. Another Service Fabric service supports the Auth Service in dealing with licenses; the Sage Token Service. This hides the complexity of our many products’ licensing methods whilst 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 re-direct to the Auth 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 Service Fabric 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 Service Fabric Domain Services, including Banking Service.

Additional considerations for working with Auth Service JWTs

  • Auth Service JWTs have an expiry of 10 minutes. It is recommended you take a pro-active and re-active approach to token expiry; requesting a new token should an unauthenticated response be returned, whilst not attempting to use cached tokens that are known to have expired.
  • In order to help protect the signing key used to request JWTs, a signing key rotation mechanism is adopted by the Auth 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. Once the new key is used, the old signing key becomes invalid. Adoption of this process is mandatory.
  • Should 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 Fabric team are responsible for the maintenance and development of the Auth Service.