Authentication With OAuth 2.0

For being able to use the API a valid JSON Web Token (JWT) is needed. The Authentication-Service supports client_credentials, authorization_code, and refresh_token as grant types. Which grant types are available for a particular client depends on its configuration. The required JWT needs to be requested from the Authentication-Service endpoint.

Independent on the grant type the process ends with a JSON response that contains the attribute "access_token" with the JWT as value. This JWT has to be used as header parameter for requests to the gateway:

  • Header Key: "Authorization"
  • Header Value: "Bearer <fetched JWT>"

To get the right credentials for fetching JWTs please ask someone from our team.

Guest Customers

Any interaction with the shop needs at least a guest token. The grant type client_credentials with the clients credentials and a uuid from the user is used to generate the JWT. The uuid from the user is either located in a cookie or it is generated.

The relevant properties are:

  • Access Token URL: <auth-service-url>/oauth2/token
  • Client ID: <Client ID>
  • Client Secret: <matching password for the Client ID>
  • Grant Type: Client Credentials
  • Scope: shop-guest

After fetching the token it can be tested that everything works with the following query:

query Shop_findCarts {
  shop_findCarts {
    id
  }
}

Since nothing has been done with the customer yet the result should be empty like this response:

{
  "data": {
    "shop_findCarts": []
  }
}

Registering a Customer

The login page on the Authorization-Service contains a register form as well. At least one request of the user on the Authorization-Service must be done with the mcs as a parameter. (e.g. /login/?mcs=%5Bbrand%3Dnovosales%20channel%3Dweb%20country%3Dde%20currency%3DEUR%20language%3Dde%20store%3D%5D) The value is stored in the session and will be used later in the registration process.

<auth-service-url>/login/?mcs=<existing MCS string>

Registered Customers

For registered users the grant type authorization_code is used. The client creates a redirect to the Authorization-Service Auth URL that contains a Callback URL (parameter redirect_uri), the clientId, scope=shop-customer, response_type=code and the mcs. Besides that the target of the user will be remembered by the client. It is possible to use the state parameter to carrier over data, like the target, from the Auth URL to the Callback URL.

The user follows the redirect to the Auth URL:

  • If the user is not logged in to the Authorization-Service, the login page will be shown. With username and password the user can login and the Auth URL will be called again.

  • If the user is logged in and the Auth URL is called a redirect to the Callback URL that contains a code parameter is returned. The user calls the Callback URL on the client. Afterwards the client uses the Access Token URL with parameters code, which is from the Callback URL, the same redirect_uri as used with the Auth URL and grant_type=authorize_code.

The response is a JSON that contains the access_token and if the client has the right the refresh_token as well. In the default configuration of clients the permissions are implicit, so no additional window will pop up in the authorization process.

The required properties are:

  • Auth URL: <auth-service-url>/oauth2/authorize?mcs=<existing MCS string>
  • Access Token URL: <auth-service-url>/oauth2/token
  • Callback URL: <matching URL with the clients configuration from the Authentication-Service>
  • Client ID: <Client ID>
  • Client Secret: <matching password for the Client ID>
  • Grant Type: Authorization Code
  • Scope: shop-customer

After fetching the token it can be tested that everything works with the following query:

query Account_loadCustomer {
  account_loadCustomer {
    firstname
    lastname
  }
}

Assuming for the registration was used John as firstname and Doe as lastname the response should like:

{
  "data": {
    "account_loadCustomer": {
      "firstname": "John",
      "lastname": "Doe"
    }
  }
}

If this query is used with a JWT for a guest customer it would result in an error with message Forbidden.

For clients with the right to use "refresh_token" a new pair of tokens can be created using the Access Token URL with the following parameters only:

  • grant_type=refresh_token
  • refresh_token=<refresh_token>

Refresh tokens can be reusable or not, depending on the clients configuration. Reusable refresh tokens can be used infinitely in their time-to-live to get new access tokens. Non-reusable refresh tokens can be used once in their time-to-live to generate a new token pair. The new refresh token then has its own time-to-live, which allows to stay logged in forever if refreshed often enough.