Authentication

On this page

An API instance runs in one of two authentication modes: Windows authentication, or token authentication. The mode is part of the instance's configuration, not something a request chooses: the instance uses Windows authentication when Windows authentication is enabled for it in IIS, and token authentication otherwise. In token authentication mode, Windows credentials are not consulted.

The settings that control token authentication are made outside the API:

In the API

Windows authentication

When an instance uses Windows authentication, no token endpoint exists: a POST to /token answers, in the response envelope, that access-token authentication is not configured. Calls carry the caller's Windows credentials instead of a token.

The caller's Windows identity must resolve to an Alloy Navigator account that is not a portal-customer account. A portal-customer account is rejected outright; any other login is checked against the directory or the technician credentials. Opening the API's root page reports, without authenticating anything further, whether the current Windows user has API access.

Get a token by password

When an instance uses token authentication, a technician gets a token from POST /token with grant_type=password, username, and password. The two token endpoints, /token and /externalToken, sit at the root of the API's URL, with no V1 or V2 segment.

Before you begin:

  • Password authentication must be allowed for the instance. It is checked first, before the login is checked, so it also applies to a directory login. When it is not allowed, the request is refused with "Password authentication is not allowed. Use the authorized authentication method instead."
  • The account must not be a portal-customer account: a portal customer is refused on this path. A portal customer gets a token as described in Get a token as a portal customer.

A login without a domain part that is a technician's is checked against the technician account's stored password. That check requires:

  • Password authentication allowed for the technician's own account. An account whose Allow password authentication check box is cleared has no stored password, so no password matches it, whatever the instance setting is.
  • An active technician account whose Person is not at the Inactive status.

The password grant also accepts a directory login, checked over LDAP:

  • A login in the form DOMAIN\name is checked against the directory of the Domain Credentials record for that domain.
  • A login without a domain part is checked against the directory when it is not a technician login whose password matches, and only when exactly one Domain Credentials record exists and some technician login already begins with that domain.
  • The check requires an active technician account whose login is DOMAIN\name, and binds to the directory with the typed password. On success, the token's user name is DOMAIN\name.

Get a token for an application

POST /token with grant_type=client_credentials, client_id, and client_secret returns a token that identifies the API application. client_id is the application's Application ID and client_secret is its Secret. Only an active application is accepted, and the supplied secret is compared with the stored one.

Get a token by single sign-on

POST /externalToken with grant_type=client_credentials and a validated OpenID Connect bearer token in the Authorization header, with no client_id or client_secret, returns a token for the person the single sign-on provider's claims name, taken from the lower-cased user-name claim. Single sign-on is OpenID Connect only, in four provider types: Custom, Microsoft, ADFS, and Okta. There is no SAML support.

The request is refused with one of these messages:

  • "Authorization header is not specified."
  • "Unable to sign in because the specified token is invalid."
  • "Unable to sign in because the specified SSO provider configuration is not recognized."
  • "You are not allowed to sign in to Alloy Navigator with your <provider> account '<user name>'."

A token that lacks the provider's user-name or full-name claim is rejected with no message.

Get a token as a portal customer

A request to /token or /externalToken that also carries the header Api-Client: Helpdesk has its credentials validated against portal-customer rules rather than technician rules. This is how the Self Service mobile app gets a token from the same endpoint as a technician integration.

As with a technician, a customer account without a stored password matches no password. When the password check fails, the portal rules fall back to a directory check, which accepts an active account, technician or customer, named DOMAIN\<login> that the directory finds. When that directory is a sign-in provider for the portal that does not require an existing account, the check imports the account instead.

The token request body

A token request accepts a form-encoded body or a JSON body. A JSON body is converted to grant_type, username, password, client_id, and client_secret only; any other JSON property is dropped. A request with an unsupported content type is rejected with 400 and an explanatory body. A multipart/form-data body is rejected.

For complete token requests and bearer-header usage, see Examples.

The token response

A token is a bearer token, valid for eight hours; present it in the Authorization header on later requests. Tokens from both endpoints have the same lifetime.

A successful token response carries access_token, token_type (bearer), and expires_in. It does not carry a refresh token, and it does not use the response envelope, so a client cannot branch on success here. A refused grant does not use the envelope either. The answers /token gives:

Request to /token Answer
Unrecognized grant_type {"error": "unsupported_grant_type"}
Wrong technician login or password {"error": "invalid_grant"}
Wrong application ID or secret An OAuth error answer; the client is rejected.
The credential check fails with an error A body with Success set to false and ErrorText holding the error's message followed by its inner error's message. An error whose message is "Invalid authorization specification" ends as a plain rejection instead.

The current user

The identity behind a token depends on how it was obtained:

Endpoint grant_type Credentials Resulting identity
/token password technician login and password that technician
/token client_credentials client_id + client_secret the API application
/externalToken client_credentials a validated OpenID Connect bearer token; no client ID or secret the person the single sign-on provider's claims name

A call made with a technician's token is subject to the same data filtering as that technician's Web App session.