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 that the provided domain user must be authenticated against an Active Directory (AD). See section Active directory integration for more details.
- machine
  Specifies that 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 that the provided username and password must be authenticated against a Profile in the Access Model.

Profile Credentials Mapping

A token request maps a user and their 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 the Object Properties panel)
A User object must exist beneath the Profile of which the authenticating domain and account name match the provided username OR a Group object must exist beneath the Profile of which the authenticating domain and account name match one of the security groups 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.

in_usr

This field is intended for internal use. Its value depends on the authentication method used. For each of the available options the corresponding in_usr field values are listed:

Credential Based - Built in authentication: inmation profile name - Active Directory: user principal name (user@domain) or Down-Level Logon name (domain\user) as provided when logging on. - Machine:: Down-Level Logon name (machine\name)

SSO Based - Integrated windows authentication (IWA): In this case the in_usr field remains un-set. - ADFS: In this case the in_usr field remains un-set.

The in_usr field should not be used to infer the current user. The sub field should be used instead.

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.

If the authentication or authorization fails, 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. If 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 user logging on must be defined as a local used on the machine where the Web API service is running. In other words, the local machine account integration logic validates the user against the security account manager (SAM) and fetches the authorization groups from the local 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 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. If the authentication is successful an access token response will be returned. Should the authentication fail, an 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. If 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.

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
If the authorization is successful the values will be 200 (OK), otherwise the value will be 401 (UnAuthorized).
token_response
If the authorization is successful, the values will contain 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.

If the Web API is hosted behind a reverse proxy and the reverse proxy rewrites the Web API’s hostname, the X-Forwarded-Host header must be set to forward the upstream hostname, which is used as the hostname in the original authentication request URL.

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 a 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 an 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 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 the 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. If at least one Web API Security AD FS object is configured in the Server Model, the response will contain 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 scenarios where 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 check which user groups the user belongs to. 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 / Name Identifier
Name	Name
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 / Name Identifier

Name

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

Azure Active Directory integration

By using the Azure AD integration, the Web API redirects the authentication request to your organization’s Azure Active Directory Sign-in Page. The user is then able to login by using her / his domain credentials. After a successful login, the Azure AD shares the user’s identity and group membership information, also known as claims, with the Web API. Based on the Azure AD authentication response, 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. If the user authorization is successful, an Access Token Response will be returned.

To configure an Azure AD - Web API integration, the Web API needs to be registered in Azure AD by defining an App registration and a Web API Security AD FS object has to be created as child object of the Web API Server object in the server model.

Configure AZURE AD to integrate with Web API

Azure AD has to share an authentication response with the Web API. To allow this an App registration must be created in Azure AD for each Web API integration. This section shows you how to add and register the Web API in Azure AD using the App registrations experience in the Azure portal so that the Web API can be integrated with the Microsoft identity platform.

Register a new application using the Azure portal

Sign in to the Azure portal using a Microsoft account.
If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the Azure AD tenant that you want.
In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations > New registration.
When the Register an application page appears, enter your application’s registration information:
- Name - Enter a meaningful name that will be displayed to users of the Web API.
- Supported account types - Select which accounts should be able to use the Web API and be able to authenticate through the Azure AD integration.
Redirect URI
- Select the type Web and then enter the redirect URL <WEB_API_BASE_ADDRESS>/api/security/provider/ <WEBAPISECURITYADFS_OBJECTNAME>/authorize/callback. Such as https://mycompany.com:8002/api/security/provider/azure_mycompany/authorize/callback
When finished, select Register.
You’re taken to your application’s Overview page.
Application ID URI
- Azure AD assigns a unique Application (client) ID to the Web API app registration, but for the Web API integration an Application ID URI is required:
  - In the Essentials section select Add an Application ID URI to open the Expose an API window.
  - At the top of the Expose an API window click Set the App ID URI. Such as api://6f40e06b-1298-4963-9584-e04ba8052e36.
Federation metadata document
- In the main toolbar, select the Endpoints, an write down / copy the Federation metadata document. Such as https://login.microsoftonline.com/133c512b-7d04-4341-8467-e4832210dee9/federationmetadata/2007-06/federationmetadata.xml. The endpoint URL needs to be configured as the Federation Metadata Address in the Web API Security AD FS object as described in Configure a Web API Security AD FS object.
Token configuration
- Mandatory claims - The Azure AD authentication response, must contain at least one of the following claims to allow the Web API to identify the user:

Azure AD Attribute	Claim type
Any attribute which uniquely identifies the user	Name Identifier
Name	Name
User-Principal-Name	UPN
SAM-Account-Name	Windows account name

Azure AD Attribute

Claim type

Any attribute which uniquely identifies the user

Name Identifier

Name

User-Principal-Name

UPN

SAM-Account-Name

Windows account name

Groups claim - To include user groups in the Azure AD authentication response, the optional groups claim need to be included:
- In the left-hand navigation pane of the App Registration Overview, select the Token configuration > App groups claim.
- In the Edit groups claim panel select Security groups.
- Customize the token properties for the SAML type to use NetBIOSDomain\sAMAccountName so that a security group can be mapped to a Group object configured in the Access Model. The groups claim contains the Group ID by default. This identifier cannot be used by the Web API to determine the name of the domain to which the group belongs.

Web API Security AD FS object configuration

Create a Web API Security AD FS object as child object of the Web API Server Object by using the following configuration:
- Application ID - The Application ID URI as defined in step 8 of Register a new application using the Azure portal.
  The Application ID is used as the value for the Issuer element in the Authentication request to Azure AD. The Issuer must exactly match one of the ServicePrincipalNames in the cloud service in Azure AD. Typically, this is set to the APP ID URI which is specified during application registration. Azure AD includes the Audience element in the authentication response that identifies the intended audience. Like the Issuer value, the Audience value must exactly match the Applciation ID. However, if the value of the Issuer element is not a URI value, the Audience value in the response is the Issuer value prefixed with spn:. For this reason it is required to use the Application ID URI instead of the Application (client) ID as Application ID in the Web API Server object configuration.
- Callback Url - <WEB_API_BASE_ADDRESS>/api/security/provider/<WEBAPISECURITYADFS_OBJECTNAME>. Do not include the path authorize/callback, like the Redirect URI in the Azure AD App Registration, this is handled at runtime by the Web API Service.
- Federation Metadata Address - The Federation metadata document endpoint as defined in step 9 of Register a new application using the Azure portal.
After configuring the Web API Security AD FS object the ADFS Integration State should show status Federation metadata successfully retrieved. and the authorize and signout Web API endpoints become available.

Required permission per endpoint

Endpoint	Required permission (syslib.model.flags.SecurityAttributes)	Required Model Access
/api/v2/deletefile	MODIFY	The model in which the object is located.
/api/v2/downloadfile	READ	The model in which the object is located.
/api/v2/mass	MODIFY	The model in which the object is located.
/api/v2/querybatchproductionrecords	READ	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/readfilemetadata	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/readrawhistoricaldataattime	READ	The model in which the object is located.
/api/v2/updatebatchproductionrecords	WRITE	Equipment Model.
/api/v2/uploadfile	MODIFY	The model in which the object is located.
/api/v2/write	WRITE	The model in which the object is located.
/api/v2/writefilemetadata	MODIFY	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/deletefile

MODIFY