Configuring the Authentication Methods for the REST Agent

To be able to access the target Web Service, the REST Agent must authenticate on that Web Service first. You specify which authentication method shall be used and the authentication parameters in the Web Services - REST Connection object, in the General section of the Web Service definition page. The following authentication methods are available:

• None

• Basic

• Bearer token

• Digest

• NTLM

• Kerberos

• OAuth

• AWS Signed URL

Authenticating the REST Agent Using the Basic, Digest and NTLM Methods

Although only the Username field is mandatory here, you may have to populate other fields depending on how your organization has configured the authentication mechanism.

• Username

  API username of the user with privileges to access the target Web Service.

• Password

  API password of the user with privileges to access the target Web Service.

• Host

  The host that the Connection object should connect to. Only required if the endpoint differs from the authentication host.

• Port

  Port to access the host. Only required if the endpoint differs from the authentication host.

• Realm

  The realm is the account location, which is similar to a domain. The realm is only required if the endpoint differs from the authentication host. Also, this field is optional if you have specified a host.

• Preemptive

  Select this option to activate preemptive authentication if you want to send the authentication information without waiting for the server to give an unauthorized response. This reduces some overhead, and may be required in cases where the server does not reply with an unauthorized response. You use preemptive authorization when you trust the endpoint enough to send authentication credentials somewhere without being asked for them.

  Note:

  This option is not available for Connection objects with the Digest authentication method.

Authenticating the REST Agent Using Kerberos

All Kerberos settings other than User and Password are set in the krb.ini (.conf) file. The Agent itself does not read this file directly, it uses the Kerberos classes of the JRE.

The algorithm to locate the krb5.conf file is the following:

• If the system property java.security.krb5.conf is set, its value is assumed to specify the path and file name.

• If that system property value is not set, the configuration file is looked for in the directory:

• <java-home>\conf\security (Windows)

• <java-home>/conf/security (Solaris and Linux)

• If the file is still not found, then an attempt is made to locate it as follows:

• /etc/krb5/krb5.conf (Solaris)

• c:\Windows\krb5.ini (Windows)

• /etc/krb5.conf (Linux)

• If the file is still not found, and the configuration information being searched for is not the default realm and KDC, then implementation-specific defaults are used. If, on the other hand, the configuration information being searched for is the default realm and KDC because they weren't specified in system properties, and the krb5.conf file is not found either, an exception is thrown.

• On Windows, if a krb5.conf file cannot be found or it does not contain settings for the default realm and its KDC, then the environment variables USERDNSDOMAIN and LOGONSERVER are used as the default realm and its KDC.

Authenticating the REST Agent Using OAuth

OAuth is a Microsoft's standard protocol that enables client applications (such as our Agent) to access data provided by a third-party API without exposing details like the username and password. There are two OAuth versions (1.0a and 2.0). The fields displayed to define parameters depend on the selected OAuth version.

As an administrator, you will have to require the following credentials from the team in charge of maintaining your OAuth instance.

• Client Key

  ID of the client application (our REST Agent) registered with the API provider, which in our case is the ID of the REST Agent in OAuth.

• Client Secret

  Shared secret known to both the REST Agent and the OAuth server. This is similar to an API key but, instead of sending the API key on every request to an API, the key is used to get the access Token Secret assigned to the REST Agent in OAuth.

• Token Secret (OAuth 1.0)

  Token assigned to the REST Agent to authenticate with the OAuth server.

• Authorization Token

  String that the OAuth client uses to make requests to the resource server.

• Signature Type

  Name of the signature method used to sign an OAuth request. The options are HMAC-SHA1, RSA-SHA1 and PLAINTEXT.

• Verifier (OAuth 1.0)

  Verification code received from the OAuth server after the authentication.

• Refresh URI (OAuth 2.0)

  Endpoint used for generating and refreshing OAuth 2.0 access tokens.

• Refresh Token (OAuth 2.0)

  Refresh tokens enable OAuth servers to use short lifetimes for access tokens. When an access token expires, the Agent can use the refresh token to automatically request a new access token. Here you enter the endpoint for the refresh server. If empty, the refresh token URL will be the same as the access token URL.

Authenticating the REST Agent Using a Bearer Token

Bearer Authorization is an HTTP authentication scheme where the client includes an access token in the Authorization header using the Bearer scheme, granting permission to access protected resources. The server validates the token for authorization.

A bearer token is a type of token used for authentication and authorization. It holds user credentials and indicates authorization for requests and access. The authenticated user gets the bearer token issued by the server and sends it to the server in the header of the request. The server verifies the received bearer token and controls user access based on it.

Bearer tokens are composed of a random string of characters. Enter the bearer token that your security team provides in the Token field.

Authenticating the REST Agent Using AWS Signed URL

An AWS signed URL is an Amazon's method to restrict access to documents, business data, media streams, or content that is intended for selected users. A signed URL includes additional information, for example, an expiration date and time.

• Signing Version

  The REST Agent supports the following signature versions: V2, V3 and V4. They are protocols for authenticating inbound API requests to AWS services. Authenticated requests require a signature that is created based on access keys (access key ID, secret access key).

• Access Key and Secret Access Key

  The Access Key/Secret Access Key pair build long-term credentials that are used to sign requests to the AWS API. Both are necessary to authenticate requests.