io.ably.lib.rest

Class Auth

java.lang.Object

io.ably.lib.rest.Auth

public class Auth
extends java.lang.Object

Token-generation and authentication operations for the Ably API. See the Ably Authentication documentation for details of the authentication methods available. Creates Ably Auth.TokenRequest objects and obtains Ably Tokens from Ably to subsequently issue to less trusted clients.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Auth.AuthMethod Authentication methods
static class	Auth.AuthOptions Passes authentication-specific properties in authentication requests to Ably.
static interface	Auth.AuthUpdateResult An interface providing update result for onAuthUpdated
static interface	Auth.RenewAuthResult An interface providing completion callbackk for renewAuth
static interface	Auth.TokenCallback An interface implemented by a callback that provides either tokens, or signed token requests, in response to a request with given token params.
static class	Auth.TokenDetails Contains an Ably Token and its associated metadata.
static class	Auth.TokenParams Defines the properties of an Ably Token.
static class	Auth.TokenRequest Contains the properties of a request for a token to Ably.

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	clientId A client ID, used for identifying this client when publishing messages or for presence purposes.
static java.lang.String	WILDCARD_CLIENTID

Method Summary

Modifier and Type	Method and Description
void	assertAuthorizationHeader(boolean forceRenew) Get the Authorization header, forcing the creation of a new token if requested
Auth.TokenDetails	assertValidToken()
Auth.TokenDetails	authorise(Auth.TokenParams params, Auth.AuthOptions options) Deprecated.
Auth.TokenDetails	authorize(Auth.TokenParams params, Auth.AuthOptions options) Instructs the library to get a new token immediately.
java.lang.String	checkClientId(BaseMessage msg, boolean allowNullClientId, boolean connected) Verify that a message, possibly containing a clientId, is compatible with Auth.clientId if it is set
void	clearCachedServerTime() For testing purposes we need method to clear cached timeDelta
Auth.TokenRequest	createTokenRequest(Auth.TokenParams params, Auth.AuthOptions options) Creates and signs an Ably Auth.TokenRequest based on the specified (or if none specified, the client library stored) Auth.TokenParams and Auth.AuthOptions.
Auth.AuthMethod	getAuthMethod() Get the authentication method for this library instance.
Auth.AuthOptions	getAuthOptions() Get (a copy of) auth options currently set in this Auth.
java.lang.String	getAuthorizationHeader()
Param[]	getAuthParams() Get query params representing the current authentication method and credentials.
java.lang.String	getBasicCredentials() Get the credentials for HTTP basic auth, if available.
java.lang.String	getEncodedToken()
Auth.TokenDetails	getTokenDetails()
void	onAuthError(ErrorInfo err)
Auth.TokenDetails	renew() Deprecated. Because the method returns early before renew() completes and does not provide a completion handler for callers. Please use renewAuth(io.ably.lib.rest.Auth.RenewAuthResult) instead
void	renewAuth(Auth.RenewAuthResult result) Renew auth credentials.
Auth.TokenDetails	requestToken(Auth.TokenParams params, Auth.AuthOptions tokenOptions) Calls the requestToken REST API endpoint to obtain an Ably Token according to the specified Auth.TokenParams and Auth.AuthOptions.
long	serverTimestamp() Using time delta obtained before guess current server time
void	setClientId(java.lang.String clientId) Set the clientId, after first initialisation in the construction of the library therefore an existing null value is significant - it means that ClientOptions.clientId was null
static long	timestamp()

Methods inherited from class java.lang.Object

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

Field Detail

clientId

public java.lang.String clientId

A client ID, used for identifying this client when publishing messages or for presence purposes. The clientId can be any non-empty string, except it cannot contain a *. This option is primarily intended to be used in situations where the library is instantiated with a key. Note that a clientId may also be implicit in a token used to instantiate the library. An error is raised if a clientId specified here conflicts with the clientId implicit in the token. Find out more about identified clients.

Spec: RSA7, RSC17, RSA12

WILDCARD_CLIENTID

public static final java.lang.String WILDCARD_CLIENTID

See Also:

Constant Field Values

Method Detail

authorize

public Auth.TokenDetails authorize(Auth.TokenParams params,
                                   Auth.AuthOptions options)
                            throws AblyException

Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token has been obtained. Also stores any Auth.TokenParams and Auth.AuthOptions passed in as the new defaults, to be used for all subsequent implicit or explicit token requests. Any Auth.TokenParams and Auth.AuthOptions objects passed in entirely replace, as opposed to being merged with, the current client library saved values.

Spec: RSA10

Parameters:

params - A Auth.TokenParams object.

options - An Auth.AuthOptions object.

Returns:

A Auth.TokenDetails object.

Throws:

AblyException

authorise

@Deprecated
public Auth.TokenDetails authorise(Auth.TokenParams params,
                                               Auth.AuthOptions options)
                                        throws AblyException

Deprecated.

Alias of authorize() (0.9 RSA10l)

Throws:

AblyException

requestToken

public Auth.TokenDetails requestToken(Auth.TokenParams params,
                                      Auth.AuthOptions tokenOptions)
                               throws AblyException

Calls the requestToken REST API endpoint to obtain an Ably Token according to the specified Auth.TokenParams and Auth.AuthOptions. Both Auth.TokenParams and Auth.AuthOptions are optional. When omitted or null, the default token parameters and authentication options for the client library are used, as specified in the ClientOptions when the client library was instantiated, or later updated with an explicit authorize request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably Auth.TokenRequest may be issued to clients in favor of a token, see Token Authentication explained.

Spec: RSA8e

Parameters:

params - : A Auth.TokenParams object.

tokenOptions - : An Auth.AuthOptions object.

Returns:

A Auth.TokenDetails object.

Throws:

AblyException

createTokenRequest

public Auth.TokenRequest createTokenRequest(Auth.TokenParams params,
                                            Auth.AuthOptions options)
                                     throws AblyException

Creates and signs an Ably Auth.TokenRequest based on the specified (or if none specified, the client library stored) Auth.TokenParams and Auth.AuthOptions. Note this can only be used when the API key value is available locally. Otherwise, the Ably Auth.TokenRequest must be obtained from the key owner. Use this to generate an Ably Auth.TokenRequest in order to implement an Ably Token request callback for use by other clients. Both Auth.TokenParams and Auth.AuthOptions are optional. When omitted or null, the default token parameters and authentication options for the client library are used, as specified in the ClientOptions when the client library was instantiated, or later updated with an explicit authorize request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably Auth.TokenRequest may be issued to clients in favor of a token, see Token Authentication explained.

Spec: RSA9

Parameters:

params - : A Auth.TokenParams object.

options - : An Auth.AuthOptions object.

Returns:

A Auth.TokenRequest object.

Throws:

AblyException

getAuthMethod

public Auth.AuthMethod getAuthMethod()

Get the authentication method for this library instance.

Returns:

getBasicCredentials

public java.lang.String getBasicCredentials()

Get the credentials for HTTP basic auth, if available.

Returns:

getAuthParams

public Param[] getAuthParams()
                      throws AblyException

Get query params representing the current authentication method and credentials.

Returns:

Throws:

AblyException

getAuthOptions

public Auth.AuthOptions getAuthOptions()

Get (a copy of) auth options currently set in this Auth.

renew

@Deprecated
public Auth.TokenDetails renew()
                                    throws AblyException

Deprecated. Because the method returns early before renew() completes and does not provide a completion handler for callers. Please use renewAuth(io.ably.lib.rest.Auth.RenewAuthResult) instead

Renew auth credentials. Will obtain a new token, even if we already have an apparently valid one. Authorization will use the parameters supplied on construction.

Throws:

AblyException

renewAuth

public void renewAuth(Auth.RenewAuthResult result)
               throws AblyException

Renew auth credentials. Will obtain a new token, even if we already have an apparently valid one. Authorization will use the parameters supplied on construction.

Parameters:

result - Asynchronous result the completion Please note that completion callback RenewAuthResult#onCompletion(boolean, TokenDetails, ErrorInfo) is called on a background thread.

Throws:

AblyException

onAuthError

public void onAuthError(ErrorInfo err)

timestamp

public static long timestamp()

getTokenDetails

public Auth.TokenDetails getTokenDetails()

getEncodedToken

public java.lang.String getEncodedToken()

assertValidToken

public Auth.TokenDetails assertValidToken()
                                   throws AblyException

Throws:

AblyException

assertAuthorizationHeader

public void assertAuthorizationHeader(boolean forceRenew)
                               throws AblyException

Get the Authorization header, forcing the creation of a new token if requested

Parameters:

forceRenew -

Throws:

AblyException

getAuthorizationHeader

public java.lang.String getAuthorizationHeader()

setClientId

public void setClientId(java.lang.String clientId)
                 throws AblyException

Set the clientId, after first initialisation in the construction of the library therefore an existing null value is significant - it means that ClientOptions.clientId was null

Parameters:

clientId -

Throws:

AblyException

checkClientId

public java.lang.String checkClientId(BaseMessage msg,
                                      boolean allowNullClientId,
                                      boolean connected)
                               throws AblyException

Verify that a message, possibly containing a clientId, is compatible with Auth.clientId if it is set

Parameters:

msg -

allowNullClientId - true if it is ok for there to be no resolved clientId

connected - true if connected; if false it is ok for the library to be unidentified

Returns:

the resolved clientId

Throws:

AblyException

serverTimestamp

public long serverTimestamp()

Using time delta obtained before guess current server time

clearCachedServerTime

public void clearCachedServerTime()

For testing purposes we need method to clear cached timeDelta