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:
"Authorization"
"Bearer <fetched JWT>"
To get the right credentials for fetching JWTs please ask someone from our team.
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:
<auth-service-url>/oauth2/token
<Client ID>
<matching password for the Client ID>
Client Credentials
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": []
}
}
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>
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-service-url>/oauth2/authorize?mcs=<existing MCS string>
<auth-service-url>/oauth2/token
<matching URL with the clients configuration from the Authentication-Service>
<Client ID>
<matching password for the Client ID>
Authorization Code
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.