SASTokenAuth Class

CBS authentication using SAS tokens.

Inheritance

AMQPAuth

SASTokenAuth

CBSAuthMixin

SASTokenAuth

Constructor

SASTokenAuth(audience, uri, token, expires_in=None, expires_at=None, username=None, password=None, port=None, timeout=10, retry_policy=<uamqp.authentication.cbs_auth.TokenRetryPolicy object>, verify=None, token_type=b'servicebus.windows.net:sastoken', http_proxy=None, transport_type=TransportType.Amqp, encoding='UTF-8', **kwargs)

Parameters

Name	Description
audience Required	str or bytes The token audience field. For SAS tokens this is usually the URI.
uri Required	str The AMQP endpoint URI. This must be provided as a decoded string.
token Required	str or <xref:bytes.> The SAS token.
expires_in	timedelta The total remaining seconds until the token expires. Default value: None
expires_at	float The timestamp at which the SAS token will expire formatted as seconds since epoch. Default value: None
username	str The SAS token username, also referred to as the key name or policy name. This can optionally be encoded into the URI. Default value: None
password	str The SAS token password, also referred to as the key. This can optionally be encoded into the URI. Default value: None
port	int The TLS port - default for AMQP is 5671. Default value: None
timeout	float The timeout in seconds in which to negotiate the token. The default value is 10 seconds. Default value: 10
retry_policy	TokenRetryPolicy The retry policy for the PUT token request. The default retry policy has 3 retries.
verify	str The path to a user-defined certificate. Default value: None
token_type	bytes The type field of the token request. Default value is b"servicebus.windows.net:sastoken". Default value: b'servicebus.windows.net:sastoken'
http_proxy	dict HTTP proxy configuration. This should be a dictionary with the following keys present: 'proxy_hostname' and 'proxy_port'. Additional optional keys are 'username' and 'password'. Default value: None
transport_type	<xref:uamqp.TransportType> The transport protocol type - default is ~uamqp.TransportType.Amqp. ~uamqp.TransportType.AmqpOverWebsocket is applied when http_proxy is set or the transport type is explicitly requested. Default value: TransportType.Amqp
encoding	str The encoding to use if hostname is provided as a str. Default is 'UTF-8'. Default value: UTF-8

Keyword-Only Parameters

Name	Description
refresh_window	int The time in seconds before the token expiration time to start the process of token refresh. Default value is 10% of the remaining seconds until the token expires.

Methods

close	Close the authentication layer and cleanup all the authentication wrapper objects.
close_authenticator	Close the CBS auth channel and session.
create_authenticator	Create the AMQP session and the CBS channel with which to negotiate the token.
from_shared_access_key	Attempt to create a CBS token session using a Shared Access Key such as is used to connect to Azure services. time to start the process of token refresh. Default value is 10% of the remaining seconds until the token expires.
handle_token	This function is called periodically to check the status of the current token if there is one, and request a new one if needed. If the token request fails, it will be retried according to the retry policy. A token refresh will be attempted if the token will expire soon. This function will return a tuple of two booleans. The first represents whether the token authentication has not completed within it's given timeout window. The second indicates whether the token negotiation is still in progress.
set_io
set_tlsio	Setup the default underlying TLS IO layer. On Windows this is Schannel, on Linux and MacOS this is OpenSSL.
set_wsio	Setup the default underlying Web Socket IO layer.
update_token	If a username and password are present - attempt to use them to request a fresh SAS token.

close

Close the authentication layer and cleanup all the authentication wrapper objects.

close()

close_authenticator

Close the CBS auth channel and session.

close_authenticator()

create_authenticator

Create the AMQP session and the CBS channel with which to negotiate the token.

create_authenticator(connection, debug=False, **kwargs)

Parameters

Name	Description
connection Required	Connection The underlying AMQP connection on which to create the session.
debug	bool Whether to emit network trace logging events for the CBS session. Default is False. Logging events are set at INFO level. Default value: False

Returns

Type	Description
CBSTokenAuth

from_shared_access_key

Attempt to create a CBS token session using a Shared Access Key such as is used to connect to Azure services.

time to start the process of token refresh. Default value is 10% of the remaining seconds until the token expires.

from_shared_access_key(uri, key_name, shared_access_key, expiry=None, port=None, timeout=10, retry_policy=<uamqp.authentication.cbs_auth.TokenRetryPolicy object>, verify=None, http_proxy=None, transport_type=TransportType.Amqp, encoding='UTF-8', **kwargs)

Parameters

Name	Description
uri Required	str The AMQP endpoint URI. This must be provided as a decoded string.
key_name Required	str The SAS token username, also referred to as the key name or policy name.
shared_access_key Required	str The SAS token password, also referred to as the key.
expiry	int The lifetime in seconds for the generated token. Default is 1 hour. Default value: None
port	int The TLS port - default for AMQP is 5671. Default value: None
timeout	float The timeout in seconds in which to negotiate the token. The default value is 10 seconds. Default value: 10
retry_policy	TokenRetryPolicy The retry policy for the PUT token request. The default retry policy has 3 retries.
verify	str The path to a user-defined certificate. Default value: None
http_proxy	dict HTTP proxy configuration. This should be a dictionary with the following keys present: 'proxy_hostname' and 'proxy_port'. Additional optional keys are 'username' and 'password'. Default value: None
transport_type	<xref:uamqp.TransportType> The transport protocol type - default is ~uamqp.TransportType.Amqp. ~uamqp.TransportType.AmqpOverWebsocket is applied when http_proxy is set or the transport type is explicitly requested. Default value: TransportType.Amqp
encoding	str The encoding to use if hostname is provided as a str. Default is 'UTF-8'. Default value: UTF-8

Keyword-Only Parameters

Name	Description
refresh_window	int The time in seconds before the token expiration

handle_token

This function is called periodically to check the status of the current token if there is one, and request a new one if needed. If the token request fails, it will be retried according to the retry policy. A token refresh will be attempted if the token will expire soon.

This function will return a tuple of two booleans. The first represents whether the token authentication has not completed within it's given timeout window. The second indicates whether the token negotiation is still in progress.

handle_token()

Returns

Type	Description
tuple[bool, bool]

Exceptions

Type	Description
uamqp.errors.AuthenticationException if the token authentication fails.
uamqp.errors.TokenExpired if the token has expired and cannot berefreshed.

set_io

set_io(hostname, port, http_proxy, transport_type)

Parameters

Name	Description
hostname Required
port Required
http_proxy Required
transport_type Required

set_tlsio

Setup the default underlying TLS IO layer. On Windows this is Schannel, on Linux and MacOS this is OpenSSL.

set_tlsio(hostname, port)

Parameters

Name	Description
hostname Required	bytes The endpoint hostname.
port Required	int The TLS port.

set_wsio

Setup the default underlying Web Socket IO layer.

set_wsio(hostname, port, http_proxy)

Parameters

Name	Description
hostname Required	bytes The endpoint hostname.
port Required	int The WSS port.
http_proxy Required

update_token

If a username and password are present - attempt to use them to request a fresh SAS token.

update_token()