Authentication

The access to the Web API endpoints is controlled. Only users which are granted access are able to perform requests. Web API users can be authenticated by a Windows account or using Profile Credentials. The Web API supports basic and token authentication.

Basic Authentication can be used for authentication based on an Profile object in the Access Model.

Token based authentication can be used for Profile Credentials, Windows domain and local accounts. The sections Active directory integration, Security Account Manager integration, Integrated Windows Authentication and Active Directory Federation Service integration describe the different ways of authentication based on a Windows account.

Basic Authentication

Basic authentication is a simple authentication schema built into the HTTP protocol. It makes use of the HTTP authorization header or URL query parameter, which contains word Basic followed by a space and a base64-encoded string username:password. The Web API encodebase64 and decodebase64 endpoints can be used to encode or decode base64 strings.

Token Authentication

The Web API supports Token Authentication (also called Bearer authentication). Bearer authentication is an HTTP authentication scheme that involves security tokens called bearer tokens. The bearer token is a cryptic string, which can be acquired by calling the token endpoint as described in the Token endpoint section.

The returned access token is a JSON Web Token (JWT). JWT is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

An access token can be used for authorization in every endpoint in the V2 namespace of the Web API. The client must send this token in the Authorization header using the Bearer schema. The content of the header should look like the following:

Authorization: Bearer <token>

Token endpoint

The endpoint /api/security/oauth2/token acquires an access token based on the Oauth 2.0 Password Grant. The Password Grant is used when an application exchanges the user’s username and password for an access token.

Request Parameters

The access token request will contain the following required parameters.

grant_type
The grant_type parameter must be set to “password”.
username
The user’s username.
password
The user’s password.
authority
Specifies the authority to use for user authentication. Supporter authorities are:
- ad
  Specifies the provided domain user must be authenticated against an Active Directory (AD). See section Active directory integration for more details.
- machine
  Specifies the provided local Windows user must be authenticated against the Security Account Manager (SAM). See section Security Account Manager integration for more details.
- builtin
  Specifies the provided username and password must be authenticated against a Profile in the Access Model.

Profile Credentials Mapping

A token request maps an user and authorization groups to a Profile in the Access Model. The following rules are used to map an inmation profile:

The Profile must exist in the Access Model.
The Profile must be enabled.
The Profile must be authorized for External API calls (under General Authorization in Object Properties panel)
A User object exist beneath the Profile of which the authenticating domain and account name matches the provided username.
A Group object exist beneath the Profile of which the authenticating domain and account name matches one of the security group fetched from the AD.

Access Token payload

Based on the fetched authorization information a JWT will be created. The payload of a JWT can be inspected by using the Debugger section of the site JWT.IO.

The token payload of an inmation access token contains at least the following information, also called claims:

{
  "sub": "DOMAIN\\USERNAME",
  "in_prf": [
    "PowerUser",
    "Operator"
  ],
  "iat": 1534327142,
  "aud": [
    "inmation Web API"
  ],
  "exp": 1534328342,
  "iss": "inmation Web API",
  "nbf": 1534327142
}

Claim	Description
sub	Identifies the principal that is the subject of the JWT. Contains a username in Down-Level Logon Name or User Principle Name (UPN) format.
in_prf	Array of (enabled and Web Data Access granted) profile names of which the 'sub' is member of. The profiles in this claim are used for permission checking in the Web API endpoint logic. At least one of the profiles has to be granted the required permission, otherwise a 'permission denied' error will be returned.
iat	The time at which the JWT was issued. Represented by the number of seconds from 1970-01-01T00:00:00Z UTC.
aud	Identifies the Web API instance(s) that the JWT is intended for.
exp	Contains the expiration time of the token, represented by the number of seconds from 1970-01-01T00:00:00Z UTC. This time is calculated based on the 'iat' and the Web API Server Object property '.WebAPIAuthentication.AccessTokenLifeTime'.
iss	Identifies the Web API that issued the JWT.
nbf	Identifies the time before which the JWT MUST NOT be accepted for processing. Represented by the number of seconds from 1970-01-01T00:00:00Z UTC.

Claim

Description

sub

Identifies the principal that is the subject of the JWT. Contains a username in Down-Level Logon Name or User Principle Name (UPN) format.

in_prf

Array of (enabled and Web Data Access granted) profile names of which the 'sub' is member of. The profiles in this claim are used for permission checking in the Web API endpoint logic. At least one of the profiles has to be granted the required permission, otherwise a 'permission denied' error will be returned.

iat

The time at which the JWT was issued. Represented by the number of seconds from 1970-01-01T00:00:00Z UTC.

aud

Identifies the Web API instance(s) that the JWT is intended for.

exp

Contains the expiration time of the token, represented by the number of seconds from 1970-01-01T00:00:00Z UTC. This time is calculated based on the 'iat' and the Web API Server Object property '.WebAPIAuthentication.AccessTokenLifeTime'.

iss

Identifies the Web API that issued the JWT.

nbf

Identifies the time before which the JWT MUST NOT be accepted for processing. Represented by the number of seconds from 1970-01-01T00:00:00Z UTC.

Access Token Response

When the authentication and authorization of a user is successful the generated access token payload will be signed with the 'Access Token Secret' defined in the Web API Server Object and returned in the access token response.

An access token response has the following structure:

{
    "access_token": <token>,
    "token_type": "Bearer",
    "expires_in": 1199
}

The access_token field contains the access token string. The token type is Bearer. The expires_in field contains the number of seconds the access token is granted for.

In case the authentication or authorization failed an Unauthorized (401) HTTP response will be returned. An Unauthorized response body has the following structure:

{
    "error": [
        {
            "msg": "User authentication failed."
        }
    ]
}

Active Directory integration

For Active Directory integration it is required that the Web API is hosted on a machine which is part of the domain. In a token request the 'authority' parameter has to be provided with value 'ad'.

The following diagram shows the OAuth 2 flow for Windows Active Directory users:

                +------------------------------+
                |            Web API           |
+--------+      | +--------+        +--------+ |      +--------+        +--------+
|        |      | |        |        |        | |      |        |        |        |
|  User  |      | |  Auth  |        |Resource| |      |  Core  |        |   AD   |
|        |      | |        |        |        | |      |        |        |        |
+---+----+      +-----+-----------------+------+      +---+----+        +---+----+
    |                 |                 |                 |                 |
    |  Token request  | Validate credentials              |                 |
    +---------------> +---------------------------------------------------> |
    |                 |                 |                 |                 |
    |                 | <---------------------------------------------------+
    |                 |                 |                 |                 |
    |                 | Fetch authorization groups        |                 |
    |                 +---------------------------------------------------> |
    |                 |                 |                 |                 |
    |                 | <---------------------------------------------------+
    |                 |                 |                 |                 |
    |                 |  Fetch authorization info         |                 |
    |                 +---------------------------------> |                 |
    |                 |                 |                 |                 |
    |   Access token  | <---------------------------------+                 |
    | <---------------+                 |                 |                 |
    |                 |                 |                 |                 |
    |  Request with access token        |                 |                 |
    +---------------------------------->+                 |                 |
    |                 |                 +---------------> |                 |
    |                 |                 |                 |                 |
    |                 |                 | <---------------+                 |
    | <---------------------------------+                 |                 |
    |                 |                 |                 |                 |

The Web API validates the provided username and password in the token request against the Active Directory. In case the credentials are valid, the Web API queries the AD for security groups the user is member of. The Web API uses the Web API Server object property 'LDAP Directory Query Root' as query root.

Security Account Manager integration

The local machine account integration logic validates the user against and fetches the authorization groups from the local Security Account Manager (SAM) store of the machine where the Web API Service is hosted. In a token request the 'authority' parameter has to be provided with value 'machine'.

Integrated Windows Authentication

The endpoint /api/security/windows/authorize Authorizes a user based on Integrated Windows Authentication (IWA). Integrated Windows Authentication uses the security features of Windows clients and servers and is supported with most modern web browsers. The current Windows user information on the client computer is supplied by the web browser to the Web API. The Web API will authorize the user by mapping the user information to profiles as described in the Profile Credentials Mapping section. In case the authentication is successful an access token response will be returned. In case the authentication fails a UnAuthorized HTTP response will be returned and the web browser will automatically prompt the user for a Windows user name and password.

Include credentials

The authorize request requires the presence of credentials from a Windows domain in the request. In JavaScript, the credentials options has to be provided in the HTTP GET request with value include:

fetch(https://<webapi_hostname/api/security/windows/authorize>, { credentials: "include"})

In .NET the UseDefaultCredentials property of the HttpClientHandler has to be set to true:

HttpClientHandler httpClientHandler = new HttpClientHandler()
{
    AllowAutoRedirect = true,
    AutomaticDecompression = DecompressionMethods.Deflate | DecompressionMethods.GZip,
    UseDefaultCredentials = true
};

HttpClient httpClient = new HttpClient(httpClientHandler);

Active Directory Federation Service integration

Active Directory Federation Services (AD FS) is a software component developed by Microsoft that can be installed on Windows Server operating systems to provide users with single sign-on access to systems and applications located across organizational boundaries.

The Web API redirects the authentication request to the login page of the AD FS. The user is then able to login by using her / his domain credentials. After a successful login, the AD FS shares the user’s identity and group membership information, also known as claims, with the Web API. The Web API will try to authorize the user by mapping the provided claims to a Profile as described in the Profile Credentials Mapping section. In case the user authorization is successful an Access Token Response will be returned.

To enable / configure an AD FS integration, a Web API Security AD FS object has to be created as child object of the Web API Server object in the server model. Multiple AD FS integrations can be configured side-by-side.

After configuring a Web API Security AD FS object the authorize and signout Web API endpoints become available instantly.

Authorize endpoint

Authorizes a user based on AD FS authentication. The path of this endpoint is /api/security/provider/<ObjectName>/authorize, where <ObjectName> is the ObjectName of the Web API Security AD FS object in the server model.

Behavior

The endpoint behavior depends on the presence of the URL query parameter target_link_uri.

By default this endpoint returns an HTTP response, which contains an Access Token Response.

The URL query parameter target_link_uri can be used to specify to which URI the Web API should redirect to after authorization. To communicate the Access Token Response to the client, the Web API appends the following two URL query parameters to the provided target_link_uri:

token_response_status
In case the authorization is successful the values will be 200 (OK), otherwise the value will be 401 (UnAuthorized).
token_response
In case the authorization is successful the values contains a base64 encoded JSON string, which contains the access token response as described in the Access Token Response section. Otherwise the value will be an empty string.

Authorize Example

Request URL:

https://LAB-HOST:8002/api/security/provider/adfs_dev/authorize?target_link_uri=https://LAB-HOST:8002/api/docs

Redirect URL:

https://LAB-HOST:8002/api/docs?token_response_status=200&token_response=eyJhY2Nlc3NfdG9rZW4iOiJleUpoYkdjaU9pSm9kSFJ3T2k4dmQzZDNMbmN6TG05eVp5OHlNREF4THpBMEwzaHRiR1J6YVdjdGJXOXlaU05vYldGakxYTm9ZVEkxTmlJc0luUjVjQ0k2SWtwWFZDSjkuZXlKaGRXUWlPbHNpYVc1dFlYUnBiMjRnVjJWaUlFRlFTU0pkTENKbGVIQWlPakUxTnpRM01ERTJNVGNzSW1saGRDSTZNVFUzTkRjd01EUXhOeXdpYVc1ZmNISm1JanBiSW5OdklsMHNJbWx6Y3lJNkltbHViV0YwYVc5dUlGZGxZaUJCVUVraUxDSnVZbVlpT2pFMU56UTNNREEwTVRjc0luTjFZaUk2SW1GMWRHOTBaWE4wTVVCcGJtMWhkR2x2Ym1SbGRpNWpiMjBpZlEuampuajVlUUhfOUI2T3VXMnNwVmZaS3hrTTZfUUpBcUN5VE8tN0tseVlCVSIsInRva2VuX3R5cGUiOiJCZWFyZXIiLCJleHBpcmVzX2luIjoxMTk5fQ%3d%3d

The value of the token_response URL query parameter is an URL encoded string, containing the base64 encoded JSON string representation of the Access Token Response.

Sign out endpoint

Signs out a user from the AD FS. The path of this endpoint is /api/security/provider/<ObjectName>/signout, where <ObjectName> is the ObjectName of the Web API Security AD FS object in the server model.

Behavior

The endpoint behavior depends on the presence of the URL query parameter target_link_uri.

By default this endpoint returns a HTTP response with an empty body and HTTP status code 204 (No Content).

The URL query parameter target_link_uri can be used to specify to which URI the Web API should redirect to after signing out from AD FS. The redirect feature after signing out, works only when the Ws-Federation endpoint defined in AD FS is set as default:

This is a behavior of AD FS. In case of a sign-out request, the AD FS honors the callback URL only if it matches a Trusted URL, which is set as default URI for the relying party trust. If there is no match among the Trusted URLs or if the matched Trusted URL is not set as default, the user stays on the AD FS own sign-out page.

How to configure the AD FS is described in more detail in the section Configure AD FS to integrate with Web API.

Sign out Example

Request URL:

https://LAB-HOST:8002/api/security/provider/adfs_dev/signoot?target_link_uri=https://LAB-HOST:8002/api/docs

Redirect URL:

https://LAB-HOST:8002/api/docs

Check Status endpoint

The check status endpoint can be used to check the status of the configured AD FS security providers. In case at least one Web API Security AD FS object is configured in the Server Model, the response contains the dependency with name WebAPISecurityProviders. This dependency contains the combined status of the configured security providers. The security_providers JSON array element in the response contains details information for each security provider:

{
    "status": "OK",
    "message": "Status is OK.",
    "dependencies": [
        {
            "name": "ChannelAgent",
            "status": "OK",
            "message": "Status is OK."
        },
        {
            "name": "WebAPISecurityProviders",
            "status": "OK",
            "message": "Status is OK."
        }
    ],
    "security_providers": [
        {
            "class": "WebAPISecurityAdfs",
            "type": "ADFS",
            "numid": 281477152112640,
            "name": "ADFS_dev",
            "status": "OK",
            "message": "Federation metadata successfully retrieved.",
            "links": [
                {
                    "rel": "authorize",
                    "href": "/api/security/provider/adfs_dev/authorize",
                    "type": "navigate"
                },
                {
                    "rel": "signout",
                    "href": "/api/security/provider/adfs_dev/signout",
                    "type": "navigate"
                }
            ]
        }
    ]
}

Configure AD FS to integrate with Web API

The AD FS has to share a security token to the Web API. To allow this a Relying Party Trust must be created in AD FS for each Web API instance.

Create a relying party

Log in to your AD FS server.
On the Start menu, click Administrative Tools > AD FS Management. The AD FS Management console is launched.
Click Relying Party Trusts. The wizard to add a relying party is launched.
On the Welcome page, choose Claims aware and click Start.
On the Select Data Source page, click Enter data about the relying party manually, and then click Next.
On the Specify Display Name page, type a name in Display name, under Notes type a description for this relying party trust, and then click Next.
On the Configure Certificate page, if you have an optional token encryption certificate, click Browse to locate a certificate file, and then click Next.
On the Configure URL page, select the Enable support for the WS-Federation Passive protocol check box. Under Relying party WS-Federation Passive protocol URL, type the URL for this relying party trust, and then click Next.

The Callback URL configured in the Web API Security AD FS object must match the configured URL.
On the Configure Identifiers page, specify one or more identifiers for this relying party, click Add to add them to the list, and then click Next.

The Application ID configured in the Web API Security AD FS object must match one of the configured identifiers in the Relying Party Trust exactly.

In case the Web API must be able to redirect back to a third party application after a request to sign out from the AD FS a separate Relying Party Trust must be created for each Web API Security AD FS object. In this scenario it is not possible to link multiple Web API Security AD FS objects to the same Relying Party Trust, by defining multiple identifiers.
On the Choose Access Control Policy page, select a policy and click Next. For more information about Access Control Policies, see Access Control Policies in AD FS.
On the Ready to Add Trust page, review the settings, and then click Next to save your relying party trust information.
On the Finish page, click Close. This action automatically displays the Edit Claim Rules dialog box.
On the Edit Claim Issuance Policy page, click Add Rule.
On the Select Rule Template page, select the claim rule template Send LDAP Attributes as Claims, and then click Next.
On the Configure Rule page, provide a name for the claim rule and select the attribute store Active Directory. Add the claims required for your project. The details about mandatory and optional claims are described further below. When the claims are defined, click Finish.

Mandatory Claims

The security token which is shared by the AD FS must contain claims to allow the Web API to identify the user and optionally to check to which user groups the user belongs. At least one of the following AD FS claims must be present to be able to identify a user:

LDAP Attribute	AD FS claim type
Any attribute which uniquely identifies the user	Name ID
User-Principal-Name	UPN
SAM-Account-Name	Windows account name

LDAP Attribute

AD FS claim type

Any attribute which uniquely identifies the user

Name ID

User-Principal-Name

UPN

SAM-Account-Name

Windows account name

The AD FS claim type Group has to be used to communicate the authorization groups a user is member of. The values for the group claim can either be the Distinguished Name (DN) of the group or the group name qualified by the domain name or the long domain name. A long domain name contains the Top Level Domain (TLD).

Optional Claims

Any claim can be included in the access token generated by the Web API. To include custom claims, the claim must be configured in AD FS and the Web API Security Provider authorize endpoint must be called by providing the URL query parameter include_claims. The value of this query parameter has to be a comma separated string, containing the names of the custom AD FS claims to included.

An overview of the common ADFS claims types can be found here. The last path segment of the URI has to be used as value in the include_claims parameter.

Some AD FS claim names are registered differently as public JWT claim names in the IANA "JSON Web Token Claims" registry. For this reason the following AD FS - JWT claim name conversions will be done by the Web API automatically.

AF DS claim name	JWT claim name
authenticationinstant	auth_time
emailaddress	email
givenname	given_name
homephone	phone_number
mobilephone	phone_number
otherphone	phone_number
surname	family_name

AF DS claim name

JWT claim name

authenticationinstant

auth_time

emailaddress

givenname

given_name

homephone

phone_number

mobilephone

phone_number

otherphone

phone_number

surname

family_name

Include Claims Example

Authorize Request URL:

https://LAB-HOST:8002/api/security/provider/adfs_dev/authorize?include_claims=emailaddress,surname,givenname&target_link_uri=https://LAB-CORE7:8002/api/docs

Required permission per endpoint

Endpoint	Required permission (syslib.model.flags.SecurityAttributes)	Required Model Access
/api/v2/mass	MODIFY	The model in which the object is located.
/api/v2/querybatchproductionrecords	-	Equipment Model
/api/v2/read	READ	The model in which the object is located.
/api/v2/readfile	READ	The model in which the object is located.
/api/v2/readhistoricaldata	READ	The model in which the object is located.
/api/v2/readhistoricaldataattime	READ	The model in which the object is located.
/api/v2/readrawhistoricaldata	READ	The model in which the object is located.
/api/v2/write	WRITE	The model in which the object is located.
/api/v2/execfunction	Requires custom implementation to check permissions.	-
/api/v2/execfunction/v2b	Requires custom implementation to check permissions.	-

Endpoint

Required permission (syslib.model.flags.SecurityAttributes)

Required Model Access

/api/v2/mass

MODIFY