Package io.ably.lib.rest

Class Auth.AuthOptions

java.lang.Object
io.ably.lib.rest.Auth.AuthOptions
Direct Known Subclasses:
ClientOptions
Enclosing class:
Auth
public static class Auth.AuthOptions extends Object
Passes authentication-specific properties in authentication requests to Ably. Properties set using AuthOptions are used instead of the default values set when the client library is instantiated, as opposed to being merged with them.

  • Field Details

    • authCallback

      public Auth.TokenCallback authCallback
      Called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed Auth.TokenRequest; a Auth.TokenDetails (in JSON format); an Ably JWT. See the authentication documentation for details of the Ably Auth.TokenRequest format and associated API calls.

      This callback is invoked on a background thread.

      Spec: RSA4a, RSA4, TO3j5, AO2b

    • authUrl

      public String authUrl
      A URL that the library may use to obtain a token string (in plain text format), or a signed Auth.TokenRequest or Auth.TokenDetails (in JSON format) from.

      Spec: RSA4a, RSA4, RSA8c, TO3j6, AO2c

    • authMethod

      public String authMethod
      The HTTP verb to use for any request made to the authUrl, either GET or POST. The default value is GET.

      Spec: RSA8c, TO3j7, AO2d

    • key

      public String key
      The full API key string, as obtained from the Ably dashboard. Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably Auth.TokenRequest. Read more about Basic authentication.

      Spec: RSA11, RSA14, TO3j1, AO2a

    • token

      public String token
      An authenticated token. This can either be a Auth.TokenDetails object, a Auth.TokenRequest object, or token string (obtained from the token property of a Auth.TokenDetails component of an Ably Auth.TokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that enables the client library to renew the token automatically when the previous one expires, such as authUrl or authCallback. Read more about Token authentication.

      Spec: RSA4a, RSA4, TO3j2

    • tokenDetails

      public Auth.TokenDetails tokenDetails
      An authenticated Auth.TokenDetails object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that enables the client library to renew the token automatically when the previous one expires, such as authUrl or authCallback. Use this option if you wish to use Token authentication. Read more about Token authentication.

      Spec: RSA4a, RSA4, TO3j2

    • authHeaders

      public Param[] authHeaders
      A set of key-value pair headers to be added to any request made to the authUrl. Useful when an application requires these to be added to validate the request or implement the response. If the authHeaders object contains an authorization key, then withCredentials is set on the XHR request.

      Spec: RSA8c3, TO3j8, AO2e

    • authParams

      public Param[] authParams
      A set of key-value pair params to be added to any request made to the authUrl. When the authMethod is GET, query params are added to the URL, whereas when authMethod is POST, the params are sent as URL encoded form data. Useful when an application requires these to be added to validate the request or implement the response.

      Spec: RSA8c3, RSA8c1, TO3j9, AO2f

    • queryTime

      public boolean queryTime
      If true, the library queries the Ably servers for the current time when issuing Auth.TokenRequest instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably Auth.TokenRequest, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon. The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request. The default is false.

      Spec: RSA9d, TO3j10, AO2a

    • useTokenAuth

      public boolean useTokenAuth
      When true, forces token authentication to be used by the library. If a clientId is not specified in the ClientOptions or Auth.TokenParams, then the Ably Token issued is anonymous.

      Spec: RSA4, RSA14, TO3j4

  • Constructor Details

    • AuthOptions

      public AuthOptions()
      Default constructor

    • AuthOptions

      public AuthOptions(String key) throws AblyException
      Convenience constructor, to create an AuthOptions based on the key string obtained from the application dashboard.
      Parameters:
      key - the full key string as obtained from the dashboard
      Throws:
      AblyException