Web Services Authentication Methods

Web Services connectivity in GENESIS allows you to call REST services with various authentication mechanisms. When picking an authentication type, the choice is driven by the type of authentication that is supported by the REST service that you want to connect to.

GENESIS can connect to REST services supporting one of the following authentication types.

Authentication Type	Description
None	This is an option for REST services that allow anonymous access. It does not perform any authentication with the REST service.
Query String	This is a non-standard authentication mechanism that passes a username and a password in clear text in a query string. This authentication method is not secure and should be avoided.
Basic	This is the standard basic access authentication, where the Web Services Connector provides a username and a password in the Authorization header with each call. The credentials are passed as a Base64 encoded string, built by joining the username and password with a single colon (:). This authentication method should only be used with HTTPS connections, as the credentials are passed in clear text. Learn more
OAuth 1.0 or 1.0a	This is an older authentication protocol that is now superseded by OAuth 2.0. OAuth 1.0 is considered insecure and should be avoided. Learn more OAuth 1.0a is more secure but it has been obsoleted in favor of OAuth 2.0. Learn more
OAuth 2.0	This is an industry-standard protocol for authorization. The OAuth framework specifies several grant types for different use cases. Learn more GENESIS supports the following grant types: Authorization Code. The authorization code grant type is used by confidential and public clients to exchange an authorization code for an access token. After the user returns to the client via the redirect URL, the application gets the authorization code from the URL and uses it to request the access token. Client Credentials. The client credentials grant type is used by clients to obtain an access token outside of the context of a user. Resource Owner Password. The password grant type is a legacy way to exchange a user's credentials for an access token. Since the client component has to collect the user's password and send it to the authorization server, using this grant is no longer recommended.
New Technology LAN Manager (NTLM)	This is a Microsoft Windows specific authentication protocol that you can use to authenticate users and computers based on a challenge/response mechanism that proves to a server or domain controller that the user knows the password associated with an account.
JSON Web Token (JWT)	This method can be used for REST services that have a custom authentication flow (not OAuth 2.0), but the result of the authorization is a JWT. At minimum, the JWT must contain the exp (expiration time) claim, so that GENESIS can determine whether the token has expired or not. If the token does not contain this claim, GENESIS treats the token as expired and calls the web authentication method again before every call to the API. Learn more

Separate Credential Calls

Some REST APIs do not accept a credential directly. Instead, they require you to call one endpoint to obtain a short-lived token and then send that token with each subsequent call. A cross-site request forgery (CSRF) token and a continuation token both work this way.

A web method performs a single REST call. It cannot call one endpoint to obtain a token and then use that token in another call to the API. GENESIS obtains the token for you in only two of the authentication types:

OAuth 2.0, where GENESIS acquires the access token, sends it with each call, and refreshes it when it expires.
JSON Web Token (JWT), where you configure a web authentication method that returns the token, and GENESIS calls that method whenever it needs a new token. The returned token must be a JWT because GENESIS parses it to read its claims. Learn more

For any other scheme, build the call sequence outside the web method. Configure one web method that obtains the token and a second web method that uses it, and then chain them in a Bridging transaction, where the output dataset of the first activity supplies a parameter of the second. Learn more

A web method builds its result from the body of the response. Values that the API returns in a response header are not available in the method's result schema, and the Bridging web service activities do not expose them either. A token that the API returns only in a response header cannot be read this way.

Cookies

A REST method parameter can be sent to the API in a cookie: select Cookie as the parameter type, in the same way you would select an HTTP header or a query string parameter. This covers an API that expects a fixed value in a cookie, such as an API key.

What Web Services does not do is keep a session. Each call is made on its own connection, and any cookie the API sets in its response is discarded when the call ends, so a cookie returned by one call is not sent back on the next. An API that authenticates by issuing a session cookie and expecting it on subsequent calls therefore cannot be driven by Web Services alone.