Service client authentication

All our services use client-certificates for authentication. The certificate is used to get an access_token from Azure Active Directory (AAD). This access_token is then used with the service, until the access_token expires.

Technical background:

Azure AD uses a proposed extension to the OAuth standard (described here) that allows the client to authenticate using a certificate. This is done by creating a "client_assertion" which is a JsonWebToken (JWT) which has been signed by the certificate. The process is described here and here and here. However most/all programming languages have some/good support for this process.

Access_token caching:

Caching the access_token is REQUIRED. When you re-use the access_token, your integration will continue to work well even if the authentication service (Azure AD) is slow/unavailable. It will also make the integration faster since there will be only one network call (and not two). Most authentication libraries do this caching automatically, but make sure it works. Also make sure you avoid doing requests with an expired access_token, check it validity before making the request.

Certificate management:

All certificates eventually expire, and it is the clients (i.e. your) responsibility to request a enroll a new certificate well before it expires. Your client application should support having multiple certificates, to support rolling over to the new certificate without interruption. Certificates are (on Windows) stored in the User or Machine certificate store.

Credentials creation workflow:

  1. You request access to one or more of our services. In the request, include the following:
    • A confirmation that you have read and agreed to our integration agreement
    • Which retail chain you are representing
    • Which environment you need access to (DEV, TEST or PROD)
    • The name and email of at least one technical contact person
    • The full URL of each service endpoint you want access to
      • If you do not know which services/endpoints you need, please contact us.
      • Please make yourself acquainted with the service documentation to ensure the service is correct for your use case.
      • We need the list of endpoints to ensure you have the correct access permissions
  2. We will create a new client-definition for you, and give you the following:
    • Your ClientID (A GUID)
    • The AAD URL where you will autenticate with the certificate and get your access_token
  3. You will create the client certificate (using the ClientID), and send us the public key (NOT the private key).
  4. We will confirm that the public key has been receieved and that you have been granted access.
  5. You will verify your credentials by:
    1. Using the private key to get a access_token from AAD (see below for sample code)
    2. Using the access_token to make a request to the service endpoints
    3. Notifying us that access works

Technical details: