Authentication, Authorization and Access Control

Authentication

Human user and device authentication is done by email/password authentication. Any human user can sign up for an netilion account and login after he validated his email address via the automated confirmation email. To authenticate devices and machines so called technical users can be created.

For security reasons, the authentication of human users is only possible via the Netilion ID web application: https://netilion.endress.com/app/id.

Authorization

As mentioned before, human users can only authenticate themselves via the Netilion ID web application. To allow an application to access the data of a user, the OAuth 2 protocol is used. In detail, this means that an application can request an access token via the Authorization Code Flow to gain access to the data without seeing the user's credentials.

For devices or machines that need to access data in a process where no human interaction is involved, technical users can be used to authenticate and authorize the devices. In OAuth 2 terms this is done via the Password Grant. Access Controls can then be used to define which data a device can access.

The OAuth 2 protocol can easily be implemented in any programming language. To get it running faster you can also use one of many open source libraries which are listed here.

Password Grant

The password grant only works for devices or machines, but not for human users. To access the API the client requests an token using the api key, api secret, username and password. The API returns an access token which is valid for 11 minutes and a refresh token with longer validity time which can be used to refresh the access token. The access token can than be used to access the API resources. If the access is not needed anymore the token must be revoked.

Requirements

To get access to the API, a connect subscription with API Key of type OAuth and a Technical User is needed. You can create one in the Netilion ID web application under: https://netilion.endress.com/app/id/subscriptions/connect.

Connect Subscription

Request Token

To request a token, following request needs to be made against https://api.netilion.endress.com/oauth/token with the Content-Type application/x-www-form-urlencoded.

Content-Type: application/x-www-form-urlencoded

client_id=[API KEY]&client_secret=[API SECRET]&grant_type=password&username=[USERNAME]&password=[PASSWORD]


Parameter  Description
client_idYour client applications api key.
client_secretYour client applications api secret.
grant_typeThis tells the token endpoint that the application is using the password code grant type.
usernameThe username of the technical user.
passwordThe password of the technical user.


The response for this request will look like this:

{
  "access_token": "fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79",
  "token_type": "Bearer",
  "expires_in": 660,
  "refresh_token": "d2375e356e185a745b1176f952ab7c37e58e95a1fabe715a2d4a2bc5a9e00835",
  "created_at": 1593675309
}


The returned access_token can be used to make further requests by adding following HTTP Header to any request against the API:

Authorization: 'Bearer fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79'

With the returned refresh token, a new access token can be created. The expiration time of the access token is fixed to 11 minutes (it doesn't get extended with every request like normal sessions do), this means the access token must be refreshed when it gets expired.


Refresh Token

To refresh a token, following request needs to be made against https://api.netilion.endress.com/oauth/token with the Content-Type application/x-www-form-urlencoded:

Content-Type: application/x-www-form-urlencoded

client_id=[API KEY]&client_secret=[API SECRET]&grant_type=refresh_token&refresh_token=[REFRESH TOKEN]


Parameter  Description
client_idYour client applications api key.
client_secretYour client applications api secret.
grant_typeThis tells the token endpoint that the application wants to refresh the token.
refresh_tokenThe refresh token.


The response for this request will look like this:

{
  "access_token": "4984907bf742025b93883c6081ff2acb70fa04c485ac95ca88d00ce4addc6a18",
  "token_type": "Bearer",
  "expires_in": 660,
  "refresh_token": "f26a8fa2f25e01c6a1581c354b6ab4008d236ae41e143162f0a91c4baed91ea4",
  "created_at": 1593679241
}


Revoke Token

If the token is not needed anymore, it can be revoked with following request against https://api.netilion.endress.com/oauth/revoke with the content type application/x-www-form-urlencoded and the Authorization header:

Content-Type: application/x-www-form-urlencoded
Authorization: 'Bearer [ACCESS TOKEN]'

token=[ACCESS_TOKEN]


Parameter  Description
tokenThe access token to revoke.


Authorization Code Flow (Web Applications)

Requirements

To get access to the API, a connect subscription with API Key of type OAuth. You can create one in the Netilion ID web application under: https://netilion.endress.com/app/id/subscriptions/connect.

There you can also define the redirect URIs for the authorization process (details will follow below).

Notice: Please contact our support to get your application approved and enabled for the Authorization Code Flow.


Process

This sequence diagram shows the complete process to retrieve a token using the Authorization Code Flow:

Authorization Code Flow


Request Authorization Code

To request the authorization code, you need to redirect the users browser to following URL:

https://netilion.endress.com/app/id/sign_in
  ?response_type=code
  &client_id=[API_KEY]
  &redirect_uri=https%3A%2F%2Fexample.org%2Fcallback
  &state=[STATE]


Parameter  Description
response_typeThis tells the authorization server that the application is initiating the authorization code flow.
client_idYour api key
redirect_uriThe URL which Netilion ID should redirect to after the sign in of the user (This URI needs to match with one of the redirects URIs defined in your connect subscription)
stateThe state will be send back as a param with your redirect URI after the user was authenticated. A state is typically a random string which you need to generate. You need to save the state on your end, so you can validate it when handling the callback. This is used to prevent CSRF attacks.


After the user signed in, the Netilion ID web application will redirect the user back to your application:

https://example.org/callback
  ?code=[AUTHORIZATION CODE]
  &state=[STATE]

Your should now validate the state, by comparing it to the string you stored in the session. If they match, you can request an access token with the given authorization code.


Request Token

To request a token, the following request needs to be made against https://netilion.endress.com/app/id/oauth/token with the Content-Type application/x-www-form-urlencoded:

Content-Type: application/x-www-form-urlencoded

client_id=[API KEY]&client_secret=[API SECRET]&grant_type=authorization_code&code=[AUTHORIZATION CODE]&redirect_uri=https%3A%2F%2Fexample.org%2Fcallback


Parameter  Description
client_idYour client applications api key.
client_secretYour client applications api secret.
grant_typeThis tells the token endpoint that the application is using the authorization code grant type.
codeThe authorization code it was given in the redirect.
redirect_uriThe same redirect URI that was used when requesting the code.


The response for this request will look like this:

{
  "access_token": "fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79",
  "token_type": "Bearer",
  "expires_in": 660,
  "refresh_token": "d2375e356e185a745b1176f952ab7c37e58e95a1fabe715a2d4a2bc5a9e00835",
  "created_at": 1593675309
}


The returned access_token can be used to make further requests by adding following HTTP Header to any request against the API:

Authorization: 'Bearer fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79'

With the returned refresh token, a new access token can be created. The expiration time of the access token is fixed to 11 minutes (it doesn't get extended with every request like normal sessions do), this means the access token must be refreshed when it gets expired.


Refresh Token

To refresh a token, following request needs to be made against https://netilion.endress.com/app/id/oauth/token with the Content-Type application/x-www-form-urlencoded:

Content-Type: application/x-www-form-urlencoded

client_id=[API KEY]&client_secret=[API SECRET]&grant_type=refresh_token&refresh_token=[REFRESH TOKEN]


Parameter  Description
client_idYour client applications api key.
client_secretYour client applications api secret.
grant_typeThis tells the token endpoint that the application wants to refresh the token.
refresh_tokenThe refresh token.


The response for this request will look like this:

{
  "access_token": "4984907bf742025b93883c6081ff2acb70fa04c485ac95ca88d00ce4addc6a18",
  "token_type": "Bearer",
  "expires_in": 660,
  "refresh_token": "f26a8fa2f25e01c6a1581c354b6ab4008d236ae41e143162f0a91c4baed91ea4",
  "created_at": 1593679241
}


Revoke Token

If the token is not needed anymore, it can be revoked with following request against https://netilion.endress.com/app/id/oauth/revoke with the Content-Type application/x-www-form-urlencoded and the Authorization header:

Content-Type: application/x-www-form-urlencoded
Authorization: 'Bearer [ACCESS TOKEN]'

token=[ACCESS_TOKEN]


Parameter  Description
tokenThe access token to revoke.


Authorization Code Flow with PKCE (Mobile Applications)

You can fully implement the authorization process yourself as described here, but we recommend using one of the following libraries (it must be one that supports PKCE):

  • iOS: https://github.com/openid/AppAuth-iOS
  • Android: https://github.com/openid/AppAuth-Android
  • React Native: https://github.com/FormidableLabs/react-native-app-auth

Requirements

To get access to the API, a connect subscription with API Key of type OAuth. You can create one in the Netilion ID web application under: https://netilion.endress.com/app/id/subscriptions/connect.

There you can also define the redirect URIs for the authorization process (details will follow below).

Notice: Please contact our support to get your application approved and enabled for the Authorization Code Flow with PKCE.


Process

This sequence diagram shows the complete process to retrieve a token using the Authorization Code Flow:

Authorization Code Flow


Request Authorization code

In order to start the auhtorization process, a so-called "code verifier" must first be created in the app. This is a cryptographically random string of characters A-Z, a-z, 0-9 and the punctuation marks -._~ (hyphen, dot, underscore and tilde), between 43 and 128 characters long.

For the authorization code request, the SHA256 hash of this "code verifier" must be sent as a BASE64-encoded encoded string in the parameter "code_challange".

To request the authorization code, you need to open an in app browser in your app and point it to the following URL:

https://netilion.endress.com/app/id/sign_in
  ?response_type=code
  &client_id=[API_KEY]
  &redirect_uri=my-netilion-app%3A%2F%2Foauth%2Fcallback
  &code_challenge=[CODE_CHALLANG]
  &code_challenge_method=S256
  &state=[STATE]


Parameter  Description
response_typeThis tells the authorization server that the application is initiating the authorization code flow.
client_idYour api key
redirect_uriThe URL which Netilion ID should redirect to after the sign in of the user (This URI needs to match with one of the redirects URIs defined in your connect subscription)
stateThe state will be send back as a param with your redirect URI after the user was authenticated. A state is typically a random string which you need to generate. You need to save the state on your end, so you can validate it when handling the callback. This is used to prevent CSRF attacks.
code_challengeThe BASE64-encoded SHA256 hash of the code verifier.
code_challenge_methodThe state will be send back as a param with your redirect URI after the user was authenticated. A state is typically a random string which you need to generate. You need to save the state on your end, so you can validate it when handling the callback. This is used to prevent CSRF attacks.


After the user signed in, the Netilion ID web application will redirect the user back to your application:

my-netilion-app://oauth/callback
  ?code=[AUTHORIZATION CODE]
  &state=[STATE]

Your should now validate the state, by comparing it to the string you stored in the session. If they match, you can request an access token with the given authorization code.


Request Token

To request a token, the following request needs to be made against https://netilion.endress.com/app/id/oauth/token with the Content-Type application/x-www-form-urlencoded:

Content-Type: application/x-www-form-urlencoded

client_id=[API KEY]&grant_type=authorization_code&code=[AUTHORIZATION CODE]&code_verifier=[CODE VERIFIER]&redirect_uri=my-netilion-app%3A%2F%2Foauth%2Fcallback


Parameter  Description
client_idYour client applications api key.
grant_typeThis tells the token endpoint that the application is using the authorization code grant type.
codeThe authorization code it was given in the redirect.
code_verifierThe code verifier create on the beginning of the authorization process.
redirect_uriThe same redirect URI that was used when requesting the code.


The response for this request will look like this:

{
  "access_token": "fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79",
  "token_type": "Bearer",
  "expires_in": 660,
  "refresh_token": "d2375e356e185a745b1176f952ab7c37e58e95a1fabe715a2d4a2bc5a9e00835",
  "created_at": 1593675309
}


The returned access_token can be used to make further requests by adding following HTTP Header to any request against the API:

Authorization: 'Bearer fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79'

With the returned refresh token, a new access token can be created. The expiration time of the access token is fixed to 11 minutes (it doesn't get extended with every request like normal sessions do), this means the access token must be refreshed when it gets expired.


Refresh Token

To refresh a token, following request needs to be made against https://netilion.endress.com/app/id/oauth/token with the Content-Type application/x-www-form-urlencoded:

Content-Type: application/x-www-form-urlencoded

client_id=[API KEY]&grant_type=refresh_token&refresh_token=[REFRESH TOKEN]


Parameter  Description
client_idYour client applications api key.
grant_typeThis tells the token endpoint that the application wants to refresh the token.
refresh_tokenThe refresh token.


The response for this request will look like this:

{
  "access_token": "4984907bf742025b93883c6081ff2acb70fa04c485ac95ca88d00ce4addc6a18",
  "token_type": "Bearer",
  "expires_in": 660,
  "refresh_token": "f26a8fa2f25e01c6a1581c354b6ab4008d236ae41e143162f0a91c4baed91ea4",
  "created_at": 1593679241
}


Revoke Token

If the token is not needed anymore, it can be revoked with following request against https://netilion.endress.com/app/id/oauth/revoke with the Content-Type application/x-www-form-urlencoded and the Authorization header:

Content-Type: application/x-www-form-urlencoded
Authorization: 'Bearer [ACCESS TOKEN]'

client_id=[API KEY]&token=[ACCESS_TOKEN]


Parameter  Description
client_idYour client applications api key.
tokenThe access token to revoke.


Access Controls

Permissions

Users can authorize other users to read, update, delete and/or manage their data. They can create new permissions to a single user or to all users within a user group.

To create this, this endpoint can be used

POST https://netilion.endress.com/v1/permissions

A sample body for this POST request:

{
  "permission_type": [
    "can_read"
  ],
  "assignable": {
    "id": 47392,
    "type": "Usergroup"
  },
  "permitable": {
    "id": 4485958,
    "type": "Asset"
  }
}

permission_type points to what kind of permission do you want to grant, there are four types:

  • can_read: enable user to see the object
  • can_update: enable user to change the object attributes (not necessarily all)
  • can_delete: enable user to delete the object
  • can_permit: enable user to grant new permissions or delete existing permissions on this object

Keep in mind, these permissions are disjoint from each other, they do not imply anything on each other. There is no hierarchy between the permission types themselves.

assignable points to whom you want to assign the permission, the following assignable types are available:

  • User
  • Usergroup

The given ID, is the ID of the User or Usergroup you want to assign the permission to.

permitable points to which object you want to give the permission, the following permitable types are available:

  • Asset
  • Instrumentation
  • Node
  • Document
  • EDM::EdgeDevice
  • Event
  • Usergroup
  • APIKey
  • ClientApplication
  • BillOfMaterial
  • PurchaseOrder
  • Delivery
  • Quotation
  • RequestOfQuotation
  • Recipe

The given ID, is the ID of the object you want to assign the permission to.

Inherited Permissions

For some objects that are closely related in real life, e.g. Asset and instrumentation/tag. There is an implicit permission inheritance between the models. For example, if the user get the 'update' permission on a certain instrumentation/tag, she/he will get automatically the 'update' permission to all assets that are assigned to this instrumentation/tag. These permissions on these assets will be automatically removed when this relation is removed, e.g. instrumentation/tag is deleted or the asset is not assigned to the instrumentation/tag anymore.

The following graph shows the models that are affected with this inheritance concept:

Keep in mind, that the object can inherit the permission from two different paths, e.g an asset can be under two nodes with read permission to a certain user. If you remove the read permission from one node, the user can still see the asset because of the permission inherited from the other node which still exists.