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:
- Password authentication for the instance, and the instance's list of available single sign-on services, are set on the API instance's Authentication tab in the Admin Center. See API Settings.
- Password authentication for one account is its Allow password authentication check box, in the Settings App and in the Admin Center. See Create and Maintain Technician Accounts and Create and Maintain Customer Accounts.
- API applications, with their Application ID and Secret, are created in the Settings App and in the Admin Center. See API Applications.
- Single sign-on providers are described in Authentication Methods.
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\nameis 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 isDOMAIN\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.
Related topics
- API Applications - create and manage the application accounts used for client-credentials authentication.
- API Settings - password authentication and single sign-on providers for the API instance.
- Objects and Fields