StandaloneAuthenticator (Java Application API for IBM Streams)
Date: 2020-08-07

com.ibm.streamsx.rest.internal

## Class StandaloneAuthenticator

- java.lang.Object
- - com.ibm.streamsx.rest.internal.StandaloneAuthenticator

- All Implemented Interfaces:
    java.util.function.Function<org.apache.http.client.fluent.Executor,java.lang.String>

      public class StandaloneAuthenticator
      extends java.lang.Object
      implements java.util.function.Function<org.apache.http.client.fluent.Executor,java.lang.String>

  Authenticator which uses the Cloud Pak for Data standalone configuration security service.

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `apply(org.apache.http.client.fluent.Executor executor)` Get the contents for an `Authentication` header.
    `com.google.gson.JsonObject` | `config(boolean verify)` Configure the authenticator and create service definition information.
    `static StandaloneAuthenticator` | `of(com.google.gson.JsonObject service)` Create an authenticator for a Cloud Pak for Data standalone configuration security service from a service definition.
    `static StandaloneAuthenticator` | `of(java.lang.String endpoint, java.lang.String userName, java.lang.String password)` Create an authenticator for a Cloud Pak for Data standalone configuration security service from an endpoint URL.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface java.util.function.Function

      `andThen, compose, identity`

- - ### Method Detail

    - #### of

          public static StandaloneAuthenticator of(java.lang.String endpoint,
                                                   java.lang.String userName,
                                                   java.lang.String password)

      Create an authenticator for a Cloud Pak for Data standalone configuration security service from an endpoint URL.

      Once created, the caller should use `config(boolean)` to configure the authentication, and `apply(org.apache.http.client.fluent.Executor)` to get the contents for an `Authentication` header.

      See `config(boolean)` for details on the JSON configuration service definition object.

      Parameters:
        `endpoint` - Resources URL for either Streams rest service or build service.
        `userName` - User name to authenticate as. Defaults to the environment variable `STREAMS_USERNAME` or the operating system identifier if not set.
        `password` - Password to authenticate with. Defaults to the environment variable `STREAMS_PASSWORD` if not set.
      Returns:
        An instance of StandaloneAuthenticator.

    - #### of

          public static StandaloneAuthenticator of(com.google.gson.JsonObject service)

      Create an authenticator for a Cloud Pak for Data standalone configuration security service from a service definition.

      Once created, the caller should use `apply(org.apache.http.client.fluent.Executor)` to get the contents for an `Authentication` header.

      Note that an authenticator created with this method may not be able to re-authenticate as it uses the token from the input service and does not have the user and password information to re-authenticate.

      Parameters:
        `service` - JSON service definition. See `config(boolean)` for details on the service definition object.
      Returns:
        An instance of StandaloneAuthenticator.

    - #### apply

          public java.lang.String apply(org.apache.http.client.fluent.Executor executor)

      Get the contents for an `Authentication` header.

      The authentication returned may only be valid for a short time, depending on the configuration of the security service. As such it is recommended not to retain and use this value over long periods and instead call apply() for each request.

      Specified by:
        `apply` in interface `java.util.function.Function<org.apache.http.client.fluent.Executor,java.lang.String>`
      Parameters:
        `executor` - The Executor to use to make REST requests to the security service, if required.
      Returns:
        Contents for an `Authentication` header or null;

    - #### config

          public com.google.gson.JsonObject config(boolean verify)
                                            throws java.io.IOException

      Configure the authenticator and create service definition information.

      The first time config() is called it contacts the endpoint it was created with to get information about the security service and other related service endpoints and creates a service definition. Later calls will return this saved service defition.

      The service definition is a JSON object of the form:

           {
             "type" : "streams",
             "externalClient" : "true",
             "service_token" : "...",
             "service_token_expire" : T,
             "connection_info" : {
               "serviceRestEndpoint" : "...",
               "serviceBuildEndpoint" : "..."
             }
           }

      where the token expiry time is in milliseconds from the UNIX Epoch, and the connection endpoints are URLs. Only service endpoints that were found are included, so if the required endpoint is not found here it must be determined some other way (eg. via an environment variable).

      The method may return null if there is no configured security service or the authenticator was unable to use it, or to find other services.

      Parameters:
        `verify` - Verify the TLS / SSL certificate for the request.
      Returns:
        A JSON service definition or `null`.
      Throws:
        `java.io.IOException`