Signing¶

oci.signer.load_private_key_from_file(filename, pass_phrase=None)¶

oci.signer.load_private_key(secret, pass_phrase)¶

Loads a private key that may use a pass_phrase.

Tries to correct or diagnose common errors:

provided pass_phrase but didn’t need one
provided a public key

class oci.signer.Signer(tenancy, user, fingerprint, private_key_file_location, pass_phrase=None, private_key_content=None)¶

A requests auth instance that can be reused across requests. This signer is intended to be used when signing requests for a given user and it requires that user’s ID, their private key and cerificate fingerprint.

The private key can be sourced from a file (private_key_file_location) or the PEM string can be provided directly (private_key_content).

The headers to be signed by this signer are not customizable.

You can manually sign calls by creating an instance of the signer, and providing it as the auth argument to Requests functions:

import requests
from oci import Signer

auth = Signer(...)
resp = requests.get("https://...", auth=auth)

Resource Principals Signer¶

On an instance that has Resource Principals enabled, a signer can be retrieved using oci.auth.signers.get_resource_principals_signer. The returned resource principals signer can then be used when initializing a client. If the instance is not configured for Resource Principals this call will raise an EnvironmentError exception.

resource_principals_signer = oci.auth.signers.get_resource_principals_signer()
# A populated config is not needed when using a Resource Principals signer
db_client = oci.database.DatabaseClient({}, signer=resource_principals_signer)

OKE Workload Auth Signer¶

The OKE Workload Auth Signer is a signer that grants an entire workload (an application running on Kubernetes clusters) access to OCI resources and services using the OKE Workload Identity. It can be retrieved by oci.auth.signers.get_oke_workload_identity_resource_principal_signer. The retrieved signer can then be used when initializing a client.

The default path for retrieving the kubernetes service account token is /var/run/secrets/kubernetes.io/serviceaccount/token. If you have a different kubernetes service account token path, use the service_account_token_path parameter while retrieving the signer. If you want to directly pass in your kubernetes service account token, use the service_account_token parameter while retrieving the signer.

oke_workload_signer = oci.auth.signers.get_oke_workload_identity_resource_principal_signer()

# If you have a kubernetes service account token path different from the default path then:
# token_path = "path_to_your_token_file"
# oke_workload_signer = oci.auth.signers.get_oke_workload_identity_resource_principal_signer(service_account_token_path=token_path)

# If you want to directly pass in the kubernetes service account token then:
# token_string = "your_token_string"
# oke_workload_signer = oci.auth.signers.get_oke_workload_identity_resource_principal_signer(service_account_token=token_string)

# A populated config is not needed when using the OKE Workload Auth signer
container_engine_client = oci.container_engine.ContainerEngineClient({}, signer=oke_workload_signer)

Additional Signers¶

class oci.auth.signers.SecurityTokenSigner(token, private_key, generic_headers=['date', '(request-target)', 'host'], body_headers=['content-length', 'content-type', 'x-content-sha256'])¶

The base signer for signing requests where the API key is a token (e.g. instance principals, service-to-service auth) rather representing the details for a specific user.

This class expects caller to provide the token and the private key whose corresponding public key was provided when requesting the token. The headers to sign are also customizable but they default to:

date, (request-target), host as generic headers on each request

content-length, content-type and x-content-sha256 on as additional headers requests with bodies

Methods

__init__(token, private_key[, …]) Initialize self.

__init__(token, private_key, generic_headers=['date', '(request-target)', 'host'], body_headers=['content-length', 'content-type', 'x-content-sha256'])¶: Initialize self. See help(type(self)) for accurate signature.

class oci.auth.signers.X509FederationClientBasedSecurityTokenSigner(federation_client, generic_headers=['date', '(request-target)', 'host'], body_headers=['content-length', 'content-type', 'x-content-sha256'])¶

A SecurityTokenSigner where the token and private key are sourced from a provided X509FederationClient. The token is retrieved via the client’s get_security_token() method, and the private key is retrieved by reading it from the session_key_supplier in the client.

The headers to sign are also customizable but they default to:

date, (request-target), host as generic headers on each request

content-length, content-type and x-content-sha256 on as additional headers requests with bodies

Methods

`__init__`(federation_client[, …])	Initialize self.
`refresh_security_token`()	Refresh the security token

__init__(federation_client, generic_headers=['date', '(request-target)', 'host'], body_headers=['content-length', 'content-type', 'x-content-sha256'])¶: Initialize self. See help(type(self)) for accurate signature.

refresh_security_token()¶: Refresh the security token

class oci.auth.signers.InstancePrincipalsSecurityTokenSigner(**kwargs)¶

A SecurityTokenSigner which uses a security token for an instance principal. This signer can also refresh its token as needed.

This signer is self-sufficient in that its internals know how to source the required information to request and use the token:

Using the metadata endpoint for the instance (http://169.254.169.254/opc/v2) we can discover the region the instance is in, its leaf certificate and any intermediate certificates (for requesting the token) and the tenancy (as) that is in the leaf certificate.
You can override the metadata endpoint by overriding the environment variable OCI_METADATA_BASE_URL with an endpoint of your choice
The signer leverages X509FederationClient so it can refresh the security token and also get the private key needed to sign requests (via the client’s session_key_supplier)

Methods

__init__(**kwargs) Initialize self.

This signer can be used as follows:

import oci

signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
identity_client = oci.identity.IdentityClient(config={}, signer=signer)
regions = identity_client.list_regions()

Parameters:

federation_endpoint (str) – (optional) Users of this class can specify an explicit federation_endpoint, representing the Auth Service endpoint from which to retrieve a security token. If it is not provided then we will construct an endpoint based on the region we read from the metadata endpoint for the instance
federation_client_cert_bundle_verify (str or Boolean) – (optional) If we need a specific cert bundle in order to perform verification against the federation endpoint, this parameter is the path to that bundle. Alternatively, False can be passed to disable verification.
federation_client_retry_strategy (obj) –
(optional): A retry strategy to apply to calls made by the X509FederationClient used by this class. This should be one of the strategies available in the retry module. A convenience DEFAULT_FEDERATION_CLIENT_RETRY_STRATEGY is also available and will be used by the X509FederationClient if no explicit retry strategy is specified.

The specifics of the default retry strategy are described here.

To have this operation explicitly not perform any retries, pass an instance of NoneRetryStrategy.
log_requests (bool) – (optional) log_request if set to True, will log the request url and response data when retrieving the certificate & corresponding private key (if there is one defined for this retriever) from UrlBasedCertificateRetriever, region, federation endpoint, and the response for receiving the token from the federation endpoint

__init__(**kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

class oci.auth.signers.InstancePrincipalsDelegationTokenSigner(**kwargs)¶

InstancePrincipalsDelegationTokenSigner extends the functionality of InstancePrincipalsSecurityTokenSigner. A delegation token allows the instance to assume the privileges of the user for which the token was created.

This signer can be used as follows:

import oci

signer = oci.auth.signers.InstancePrincipalsDelegationTokenSigner(delegation_token=delegation_token)
identity_client = oci.identity.IdentityClient(config={}, signer=signer)
regions = identity_client.list_regions()

Methods

`__init__`(**kwargs)	Initialize self.
`do_request_sign`(request[, …])	Signs the request with the opc-obo-token added to the request header

:param str delegation_token (required): This token allows an instance to assume the privileges of a specific user and act on-behalf-of that user.

Parameters:

federation_endpoint (str) – (optional) Users of this class can specify an explicit federation_endpoint, representing the Auth Service endpoint from which to retrieve a security token. If it is not provided then we will construct an endpoint based on the region we read from the metadata endpoint for the instance
federation_client_cert_bundle_verify (str or Boolean) – (optional) If we need a specific cert bundle in order to perform verification against the federation endpoint, this parameter is the path to that bundle. Alternatively, False can be passed to disable verification.
federation_client_retry_strategy (obj) –
(optional): A retry strategy to apply to calls made by the X509FederationClient used by this class. This should be one of the strategies available in the retry module. A convenience DEFAULT_RETRY_STRATEGY is also available and will be used by the X509FederationClient if no explicit retry strategy is specified.

The specifics of the default retry strategy are described here.

To have this operation explicitly not perform any retries, pass an instance of NoneRetryStrategy.

__init__(**kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

do_request_sign(request, enforce_content_headers=True)¶: Signs the request with the opc-obo-token added to the request header

class oci.auth.signers.ResourcePrincipalsFederationSigner(resource_principal_token_endpoint=None, resource_principal_session_token_endpoint=None, resource_principal_token_path_provider=None, retry_strategy=None, log_requests=None, generic_headers=None, **kwargs)¶

Methods

__init__([…])

param resource_principal_token_endpoint:
	The endpoint that can provide the resource principal token. This is

get_security_token() Returns the security token.

make_call(method, resource_path[, …]) Normally this would be part of the generated client.

refresh_security_token() Refresh the security token

__init__(resource_principal_token_endpoint=None, resource_principal_session_token_endpoint=None, resource_principal_token_path_provider=None, retry_strategy=None, log_requests=None, generic_headers=None, **kwargs)¶

Parameters:

resource_principal_token_endpoint – The endpoint that can provide the resource principal token. This is a service endpoint.
resource_principal_session_token_endpoint – The endpoint that can provide the resource principal session token. This will default to the auth federation endpoint if not provided.
resource_principal_token_path_provider – An object of a class which implements RptPathProviderInterface that can provide the path for resource principal token. If not set, use DefaultRptPathProvider to determine the path

get_security_token()¶: Returns the security token. If it is expired, refresh the token.

make_call(method, resource_path, path_params=None, header_params=None, body=None)¶: Normally this would be part of the generated client. In this case the endpoint for the Resource Principal Token is not part of the generated client, so we need the same behavior here.

refresh_security_token()¶: Refresh the security token

class oci.auth.signers.EphemeralResourcePrincipalSigner(session_token=None, private_key=None, private_key_passphrase=None, region=None, generic_headers=None, **kwargs)¶

Methods

`__init__`([session_token, private_key, …])	This signer takes the following parameters:
`get_claim`(claim)	Provide access to the claims on the session token
`get_security_token`()	Get the security token
`refresh_security_token`()	Refresh the security token

__init__(session_token=None, private_key=None, private_key_passphrase=None, region=None, generic_headers=None, **kwargs)¶

This signer takes the following parameters: - session_token - private_key - private_key_passphrase

These three parameters may be used in one of two modes. In the first mode, they contain the actual contents of the Resource Pricipals Session Token, private key (in PEM format) and the passphrase. This mode is only useful for short-lived programs.

In the second mode, if these parameters contain absolute paths, then those paths are taken as the on-filesystem location of the values in question. The signer may attempt to reload these values from the filesystem on receiving a 401 response from an OCI service. This mode is used in cases where the program executes in an environment where an external provider may inject updated tokens into the filesystem.

region: the canonical region name

This is utilised in locating the “local” endpoints of services.

get_claim(claim)¶: Provide access to the claims on the session token

get_security_token()¶: Get the security token

refresh_security_token()¶: Refresh the security token

X509 Certificate Retrievers¶

class oci.auth.certificate_retriever.UrlBasedCertificateRetriever(**kwargs)¶

A certificate retriever which reads PEM-format strings from URLs.

Parameters:

certificate_url (str) – The URL from which to retrieve a certificate. It is assumed that what we retrieve is the PEM-formatted string for the certificate. This is mandatory
private_key_url (str) – (optional) The URL from which to retrieve the private key corresponding to certificate_url (if any). It is assumed that what we retrieve is the PEM-formatted string for the private key.
passphrase (str) – (optional) The passphrase of the private key (if any).
retry_strategy (obj) – (optional) A retry strategy to use when retrieving the certificate and private key from the URLs provided to this class. This should be one of the strategies available in the retry module. By default this retriever will not perform any retries.
log_requests (bool) – (optional) log_request if set to True will log the request url and response data when retrieving the certificate & corresponding private key (if there is one defined for this retriever)

Methods

`__init__`(**kwargs)	Initialize self.
`get_certificate_and_private_key`()	Returns the certificate_and_private_key dictionary contained by this object
`get_certificate_as_certificate`()	Retrieves the certificate as a cryptography.x509.Certificate
`get_certificate_raw`()	Retrieves a string containing the certificate contents
`get_private_key`()	Retrieves the private key as a cryptography private key
`get_private_key_pem`()	Retrievea a string containing the PEM-encoded private key
`refresh`()	Refresh the token by making a call to Identity for a new token.

Note: This class is used internally, it is not recommended for user’s direct use.

__init__(**kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

get_certificate_and_private_key()¶: Returns the certificate_and_private_key dictionary contained by this object

get_certificate_as_certificate()¶: Retrieves the certificate as a cryptography.x509.Certificate

get_certificate_raw()¶: Retrieves a string containing the certificate contents

get_private_key()¶: Retrieves the private key as a cryptography private key

get_private_key_pem()¶: Retrievea a string containing the PEM-encoded private key

refresh()¶: Refresh the token by making a call to Identity for a new token. Returns the new token.

class oci.auth.certificate_retriever.PEMStringCertificateRetriever(**kwargs)¶

A certificate retriever which is provided PEM format strings directly. This retriever is non-refreshable, and calling refresh() is a no-op.

Parameters:	certificate_pem (str) – The PEM-formatted string of the certificate. This is mandatory. private_key_pem (optional) (str) – The PEM-formatted string of the private key corresponding to certificate_pem (if any). passphrase (optional) (str) – The passphrase of the private key (if any).

Methods

`__init__`(**kwargs)	Initialize self.
`get_certificate_and_private_key`()	Returns the certificate_and_private_key dictionary contained by this object
`get_certificate_as_certificate`()	Retrieves the certificate as a cryptography.x509.Certificate
`get_certificate_raw`()	Retrieves a string containing the certificate contents
`get_private_key`()	Retrieves the private key as a cryptography private key
`get_private_key_pem`()	Retrieve a a string containing the PEM-encoded private key
`refresh`()	Since these are just the string, there is no refresh as such.

Note: This class is used internally, it is not recommended for user’s direct use.

__init__(**kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

get_certificate_and_private_key()¶: Returns the certificate_and_private_key dictionary contained by this object

get_certificate_as_certificate()¶: Retrieves the certificate as a cryptography.x509.Certificate

get_certificate_raw()¶: Retrieves a string containing the certificate contents

get_private_key()¶: Retrieves the private key as a cryptography private key

get_private_key_pem()¶: Retrieve a a string containing the PEM-encoded private key

refresh()¶: Since these are just the string, there is no refresh as such. A new object should be created if the strings change

class oci.auth.certificate_retriever.FileBasedCertificateRetriever(**kwargs)¶

A specialization of PEMStringCertificateRetriever which reads certificates from a file. This retriever is non-refreshable, and calling refresh() is a no-op.

Parameters:

certificate_file_path (str) – The file path from which to retrieve a certificate. It is assumed that what we retrieve is the PEM-formatted string for the certificate. This is mandatory
private_key_pem_file_path (optional) (str) – The file path from which to retrieve the private key corresponding to certificate_file_path (if any). It is assumed that what we retrieve is the PEM-formatted string for the private key.
passphrase (optional) (str) – The passphrase of the private key (if any).

Methods

__init__(**kwargs) Initialize self.

Note: This class is used internally, it is not recommended for user’s direct use.

__init__(**kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

X509 Certificate Federation Client¶

class oci.auth.federation_client.X509FederationClient(**kwargs)¶

Methods

__init__(**kwargs) A client which can be used to retrieve a token from Auth Service.

__init__(**kwargs)¶

A client which can be used to retrieve a token from Auth Service. It needs the following supplied to it:

The endpoint for Auth Service

Our tenancy OCID

A session key supplier so that we can send its public key as part of the token request. The private key

in the session key supplier should be used to sign all requests made with the token - The certificate (via leaf_certificate_retriever) which will be used to sign the requests to Auth Service.

Optionally, intermediate certificates (if present) can be supplied as part of the request to Auth Service.

The client has knowledge of its last requested token and can re-request the token if it is expired (otherwise it will vend the last requested token if it is not expired).

Parameters:

federation_endpoint (str) – The Auth Service endpoint from which to retrieve the token.
tenancy_id (str) – The OCID of the tenancy whose resources will be interacted with by users of the token.
session_key_supplier (SessionKeySupplier) – A SessionKeySupplier that can vend a public and private key. The public key will be sent as part of the token request and the private key should be used to sign all requests made with the token vended by this client.
leaf_certificate_retriever (CertificateRetriever) – The certificate which will be used to sign requests to Auth Service.
intermediate_certificate_retrievers (list[CertificateRetriever]) – (optional) A list of retrievers which can be used to fetch intermediate certificates which can be sent as part of the Auth Service request. This is an optional parameter
cert_bundle_verify (str or Boolean) – (optional) If we need a specific cert bundle in order to perform verification against the federation endpoint, this parameter is the path to that bundle. Alternatively, False can be passed to disable verification.
retry_strategy (obj) –
(optional) A retry strategy to apply to calls made by this client. This should be one of the strategies available in the retry module. A convenience DEFAULT_FEDERATION_CLIENT_RETRY_STRATEGY is also available and will be used if no explicit retry strategy is specified.

The specifics of the retry strategy are described here.

To have this client explicitly not perform any retries, pass an instance of NoneRetryStrategy.
circuit_breaker_strategy (obj) –
(optional) The circuit_breaker_strategy to apply to calls made by this client. This should be one of the strategies available in the circuit_breaker module. A convenience DEFAULT_FEDERATION_CLIENT_CIRCUIT_BREAKER_STRATEGY is also available and will be used if no explicit retry strategy is specified.

To have this client explicitly not have any circuit breaker, pass an instance of NoCircuitBreakerStrategy.
log_requests (bool) – (optional)

log_request if set to True, will log the request url and response data when retrieving the token from the federation endpoint.

class oci.auth.session_key_supplier.SessionKeySupplier(key_size=2048)¶

Methods

__init__([key_size]) A supplier which vends public and private keys, and can refresh the keys it uses.

__init__(key_size=2048)¶

A supplier which vends public and private keys, and can refresh the keys it uses.

Parameters:	key_size (optional) (int) – The key size to use when generating private keys. Defaults to 2048 if not provided.