API poller authorization and authentication
Most REST APIs use forms of authorization and authentication to check the validity of requests and securing available data.
- Authentication proves the identity of a requestor. Many APIs require you to register as a user and include credentials in API requests to verify your identity. For example, to send requests to Azure APIs, you need to provide a Client ID and Client Secret to authenticate access. Authentication proves that you are who you say you are.
- Authorization allows certain actions against data stored in the API. For example, you can use standard Orion account credentials to send GET requests that retrieve data from the Orion API, but if you send a POST request to change data with a CREATE, READ, UPDATE, or DELETE database command, you need extra rights. To add a node with a CREATE command, your Orion account requires Node Management rights. Authorization verifies that an authenticated request can perform certain actions.
Supported authorization types include:
- No Authorization: No user names, passwords, or credentials are required for free, public APIs, also known as open APIs. For example, iTunes Search is an open API (© 2020 Apple Inc., available at affiliate.itunes.apple.com, obtained on September 1, 2020).
- Basic Authorization: Also called "Basic Auth," this method passes the username and password in request headers, sent via HTTPS and encoded with Base64 for security. Passwords are required with Basic Authorization.
- OAuth 2.0: Uses access tokens that the API server passes to an authentication server to grant access via public and private keys. To learn about Grant Type, Tenant ID, and other OAuth terms, see the next section, API credentials.
- Bearer Token: Also called "token authentication," this scheme uses access tokens to authenticate requests, in the form of text strings added to request headers (for example,
Authorization: Bearer <Your API Key>).
- API Key: The API key is a long string included in either the request URL or request header (for example,
Authorization: <Key> <Value>). Some APIs require both a public and private key -- the public key is usually included in the request, and the private key is treated like a password.
Starting in SAM 2020.2.1, you can chain multiple API requests to save a value from one request for use in subsequent requests, including authorization and authentication data. This can be useful for APIs that involve tokens, sessions, or endpoint discovery.
Review API documentation to determine what's required in requests. For example, requests sent to the SolarWinds Loggly API require an access token before a response is returned; the API uses the token to authenticate your identity. Additional tokens are then required to reach specific segments of data in subsequent requests; the API uses those details to verify what you can do to data.
The SolarWinds Pingdom API uses Bearer Token authorization so an API token must be included in each request, as shown in this example:
GET /checks HTTP/1.1 Host: api.pingdom.com Authorization: Bearer ofOhK18Ca6w4S_XmInGv0QPkqly-rbRBBoHsp_2FEH5QnIbH0VZhRPO3tlvrjMIKQ36Vap
Depending on the type of authorization used by an API, you may only need to provide simple credentials: a username and password. Some free APIs don't require any credentials. Sophisticated APIs, such as the Azure API, require a client ID, client secret, access token URL, and other details.
Some terms you may encounter include:
- Grant type: The method used by an application to get an access token that authenticates a request to an API endpoint.
- Tenant ID: A unique ID that represents the Azure AD directory where a registered application is stored.
- Client ID: A unique ID that is assigned to an application and service principal during initial provisioning.
- Client Secret: A unique set of characters known only to the application and authorization server.
- Access token URL: The web address of the API provider's authentication server, which exchange an authorization code for an access token.to confirm access to API data.
- Scope: The endpoints of data within an API for which an application can request access. The access token issued to the application will be limited to the scopes granted, including read or write access permissions. For example, to monitor
https://manage.office.comendpoints with the Microsoft 365 Admin Center API poller template, use the following scope:
For tips on locating Azure credentials such as Tenant IDs, see Find Microsoft Azure credentials.
Note the following details about API credentials:
- To configure credentials for an API poller, select an existing set of credentials or add credentials manually.
- Credentials sent to an API via an HTTP are not encrypted. They're sent in headers as plain text.
- For OAuth 2.0:
- SAM currently only supports the Client Credentials grant type.
- The Scope value may include multiple space-separated values.
- Many access tokens expire after a certain amount of time but some APIs offer "refresh tokens" with long lifespans. For example, SolarWinds DPA API tokens expire after 900 seconds but can be extended the API_ACCESS_TOKEN_EXPIRATION option.
See API provider documentation for details about credentials and required formats.
In addition to credentials, requests require API-specific permissions to access data. For example, Microsoft Graph permissions are granted via a consent process that uses a
resource.operation.constraint pattern, as shown here:
Reports.Read.Allgrants permission to read usage reports in the Microsoft Graph API.
ServiceHealth.Readgrants permission to read service health information in the Office 365 Management API.
The following figure shows Reports.Read.All permissions (Type: Application) configured in Azure for the Microsoft 365 Teams API poller template:
When configuring permissions in Azure, use Application instead of Delegate for Microsoft Graph and Office 365 Management APIs.
Excerpts and figures herein are attributed to © 2020 Microsoft Corp., available at docs.microsoft.com, obtained on November 9, 2020.