Authentication

All of our services require you to provide a valid authentication token signed for the MAX Customer API. This token is used to identify the customer and therefore the accessible set of units. In order to achieve this, you can use the built-in OAuth2 Identity Services (implicit flow) or acquire a token within your daemon application programatatically by using the OAuth 2 Resource Owner Password Credentials flow and the corresponding ROPC Proxy authentication application.

Implicit Flow (Developer Portal)

Whenever you are testing APIs and Products within the Developer Portal, you can make use of the internal implicit flow integration to get an active access token for your Customer Services account.


Picture
Picture

Implicit Flow (External application)

Whenever you use our services in customer facing applications, you need a dedicated application id in order to allow your users to sign in interactively.

Please do not collect the user's credentials manually and request a token by using the ROPC flow. This is insecure as other might imitate your application and try to fish your user's credentials.

In order to allow us to create a dedicated application for you, please provide us with the following information

  • Application Name

  • Application Type (Web, Desktop or Mobile)

  • Redirect URLs (Required for web based applications)

We will then provide you with a dedicated application id, so you can forward your users to the authentication service where they can enter their credentials safely.

My App

Client ID
fd23f5d0-7f0a-4218-afa9-2f8edd0ab471

Authentication Libraries

Picture

https://jwt.ms/

The JSON Web Bearer Token (JWT)

Whenever you obtain an access token from the authentication service, you can decode it to obtain some basic information that can be used in your application. 

  • User Id, required for user specific endpoints

  • User name and E-Mail address

  • Additional flags indicating TK employees etc.

Furthermore, you need to send this token (Header) with every request made to the API to successfully authenticate your request. 

ROPC (Backend Daemons)

When you are working on Backend applications, you do not have the chance to obtain the user's credentials interactively. Usually you are working with technical accounts and your Daemon handles the authentication request. For this use case, we have exposed a ROPC Proxy authentication application that allows an external component to request an authentication token using their service accounts programmatically. Please do not use this flow for an interactive sign-up in your application.

OAuth2 Token Endpoint:
https://maxcustomerportal.b2clogin.com/maxcustomerportal.onmicrosoft.com/B2C_1_ROPC/oauth2/v2.0/token

ROPC Proxy Client ID:
74c72ab2-3ade-45fe-83e0-cd5b90704539

To request a proper access token which is also authenticated to access the Customer API resource, you must include the application’s scope.

You may also include the scope offline_access. Offline access is optional if you want to receive a refresh token. The refresh token allows your program to refresh the access token without any interaction of the user itself, example given in a mobile application where the user only must enter his credentials on the first start of the application. You can find more information about this topic within the following knowledge article:
https://docs.microsoft.com/en-us/azure/active-directory-b2c/configure-ropc 

Obtaining access tokens programmatically

The following snippet shows how to obtain an access token using cURL. This can be easily adapted to any programming language that is able to file a HTTP Request.

curl -X POST \
'https://maxcustomerportal.b2clogin.com/maxcustomerportal.onmicrosoft.com/B2C_1_ROPC/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=74c72ab2-3ade-45fe-83e0-cd5b90704539' \
--data-urlencode 'username=sam.sample@mail.com' \
--data-urlencode 'password=*************' \
--data-urlencode 'scope=https://maxcustomerportal.onmicrosoft.com/ea/api' \
--data-urlencode 'grant_type=password'

If you need more examples, please contact us.