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.signer.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.signer.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)

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
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
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/v1) 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.
  • 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)

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_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.

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.
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).
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).

X509 Certificate Federation Client

class oci.auth.federation_client.X509FederationClient(**kwargs)
__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_RETRY_STRATEGY is also available and will be used 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.

class oci.auth.session_key_supplier.SessionKeySupplier(key_size=2048)
__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.