Oauth2 authentication

OAuth authentication

Client credentials can be used to fetch JWT tokens, to access HiiRetail APIs. Token request will fail with 401 http code, if client is not in status Authorized

Typically, clients should perform a client_credentials grant flow against our client OAuth2 server.

Token endpoint - https://auth.retailsvc.com/oauth2/token

Example of request:

POST /oauth2/token HTTP/1.1
Host: https://auth.retailsvc.com
Content-Type: application/x-www-form-urlencoded
Authorization: WW5WemFXNWxjM05mZFc1cGRGOXBaRG9nWkdWdGIxOWlkV2xrQ21semIxOWpZem9nWkdWdGJ5MWpiM1Z1ZEhKNUNuTm1kem9nWVdKalFERXVNMEJEU1ZJM2JsRjNkRk13Y2tFMmREQlRObVZxWkFwMGFXUTZJRU5KVWpkdVVYZDBVekJ5UVRaME1GTTJaV3BrQ25kdmNtdHpkR0YwYVc5dVgybGtPaUEwTWpReU5ESTBNZ286YWYwMWY2NzdkYjNkMmNkZTZhNjFlYTc0ZWQ3NTUzYWU5MGM1ZDNmNTBmZjNkOGRiZTQ2OWRkYzJjMmIyNDVhNQ==

grant_type=client_credentials&audience=https://hiiretail.com

client_id - YnVzaW5lc3NfdW5pdF9pZDogZGVtb19idWlkCmlzb19jYzogZGVtby1jb3VudHJ5CnNmdzogYWJjQDEuM0BDSVI3blF3dFMwckE2dDBTNmVqZAp0aWQ6IENJUjduUXd0UzByQTZ0MFM2ZWpkCndvcmtzdGF0aW9uX2lkOiA0MjQyNDI0Mgo
client_secret - af01f677db3d2cde6a61ea74ed7553ae90c5d3f50ff3d8dbe469ddc2c2b245a5

Do not worry, this is sample client, and you cannot actually fetch JWT token :)

Things to consider:

grant_type must be client_credentials
audience must must be https://hiiretail.com. If aud is not passed, token will be always rejected. Read more about why we require audience https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3 in JWT spec
Authorization header must use Basic schema and be a base64 encoded client_id and client_secret, concatenated with colon.

This http call is a part of OAuth 2 spec, so you should find libs to make a process easier.

Example response:

{
    // JWT token, that can be used to access Hiiretail APIs
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpYzplMTNiZDg5Zi1kNjIzLTRmY2ItOTVjNS04NmQ5NDAxODBlZjYiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOlsiaHR0cHM6Ly9oaWlyZXRhaWwuY29tIl0sImNsaWVudF9pZCI6IlluVnphVzVsYzNOZmRXNXBkRjlwWkRvZ1pHVnRiMTlpZFdsa0NtbHpiMTlqWXpvZ1pHVnRieTFqYjNWdWRISjVDbk5tZHpvZ1lXSmpRREV1TTBCRFNWSTNibEYzZEZNd2NrRTJkREJUTm1WcVpBcDBhV1E2SUVOSlVqZHVVWGQwVXpCeVFUWjBNRk0yWldwa0NuZHZjbXR6ZEdGMGFXOXVYMmxrT2lBME1qUXlOREkwTWdvIiwiZXhwIjoxNjM3NjI0OTg4LCJleHQiOnt9LCJpYXQiOjE2Mzc2MjEzODgsImlzcyI6Imh0dHBzOi8vYXV0aC5yZXRhaWxzdmMuY29tLyIsImp0aSI6IjUyOTZlMTVhLThiYWItNDljMy05OWYxLTYxNGM1ZDRjMTlkZSIsIm5iZiI6MTYzNzYyMTM4OCwic2NwIjpbXSwic3ViIjoiWW5WemFXNWxjM05mZFc1cGRGOXBaRG9nWkdWdGIxOWlkV2xrQ21semIxOWpZem9nWkdWdGJ5MWpiM1Z1ZEhKNUNuTm1kem9nWVdKalFERXVNMEJEU1ZJM2JsRjNkRk13Y2tFMmREQlRObVZxWkFwMGFXUTZJRU5KVWpkdVVYZDBVekJ5UVRaME1GTTJaV3BrQ25kdmNtdHpkR0YwYVc5dVgybGtPaUEwTWpReU5ESTBNZ28ifQ.HYrz7bpZZ1G4pOfuDqv9dgWIJ5MghPFEqIpvhFROuaiUbGFezsNj4kE9rU3kDVDfOF2PH5QGgWUPRDzxrYfwIRh8N6iLhD0Tn4rIGU19cpqNWLlTiKp5-iRz8dP7maIUhGk6Y9EhvC-eRcD43mgxz_642hfLxfeG5MeOc5YgZLre-vmAHWFcAWkrcZersMVGAVKsOKk5xBlBzAyDPBeiCCHLK4NNhHBViy2LNb1doell2KJ29qK3NsUZCaJjMcM12v6pj3yIm_Ra_yH6JhqPxv6Duov7Q9jKk-3gYZO_ptLD-WFtG7nbUrxGXOgy8-L8hdktR34_HvEysvMy7eUCESyo8jR6gd9jzi10pA1oeP-mJCWYxiHBckuzSd4-axZHN31_QNc6ZHFxNlIBoGqG0fScdaiY_Uo87KsgkLlNqPg7vM_bxRfDn-ETEO2eoDKt3RroX1pK8zQOkg58YhQjtZYdy-znJAOMnW95zm9NaZesyXHEsBvO8kEtSUFwbVZYY7HnQ4tUK1L_2cYCpEZ7a7-o2fv52J3jDcvyVrKZQHXw-Jq0lC0Te1Qcr6m_yIElef30jSv73_ainlP_TIwgiwRHOsU7HlFjqq3OjrmRl5yX4fBZqiuCZheybX95dPtRm5uSHO5n27hXKbmlzC_ivcpn0pM0Jk_t3We-n-mNaF8",
  "expires_in": 3599,
  "scope": "",
  "token_type": "bearer"
}

Decoded token:

{
  "aud": [
    "https://hiiretail.com"
  ], // constant
  "client_id": "YnVzaW5lc3NfdW5pdF9pZDogZGVtb19idWlkCmlzb19jYzogZGVtby1jb3VudHJ5CnNmdzogYWJjQDEuM0BDSVI3blF3dFMwckE2dDBTNmVqZAp0aWQ6IENJUjduUXd0UzByQTZ0MFM2ZWpkCndvcmtzdGF0aW9uX2lkOiA0MjQyNDI0Mgo",
  "exp": 1637624988,
  "ext": {},
  "iat": 1637621388,
  "iss": "https://auth.retailsvc.com/", // constant
  "jti": "5296e15a-8bab-49c3-99f1-614c5d4c19de",
  "nbf": 1637621388,
  "scp": [],
  "sub": "YnVzaW5lc3NfdW5pdF9pZDogZGVtb19idWlkCmlzb19jYzogZGVtby1jb3VudHJ5CnNmdzogYWJjQDEuM0BDSVI3blF3dFMwckE2dDBTNmVqZAp0aWQ6IENJUjduUXd0UzByQTZ0MFM2ZWpkCndvcmtzdGF0aW9uX2lkOiA0MjQyNDI0Mgo"
}

base64url decoded client_id:

business_unit_id: demo_buid
iso_cc: demo-country
sfw: abc@1.3@CIR7nQwtS0rA6t0S6ejd
tid: CIR7nQwtS0rA6t0S6ejd
workstation_id: 42424242

Just for reference, registration request example:

POST /v1/registration HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "softwareId": "abc",
  "softwareVersion": "1.3",
  "usingGlobalTemplate": false,
  "tenantId": "CIR7nQwtS0rA6t0S6ejd",
  "claims": {
    "iso_cc": "demo-country",
    "business_unit_id": "demo_buid",
    "workstation_id": 42424242
}

Verification

Generally, a token is valid when:

token can be verified via certs
iss is valid
exp is valid
nbf is valid

Public certs are at well known path - https://auth.retailsvc.com/.well-known/jwks.json

OAuth authentication

Verification​

Verification