Skip to content

Authentication.md

Latest commit

 

History

History
161 lines (121 loc) · 11 KB

Authentication.md

File metadata and controls

161 lines (121 loc) · 11 KB

Authentication

Table of Contents

Authenticators

This library requires credentials to authenticate with IBM Cloudant. These credentials may be:

  • IBM Cloud IAM credentials (with authentication types CONTAINER, VPC, IAMASSUME and IAM)
  • Username and password credentials (with authentication types COUCHDB_SESSION and BASIC)
Authentication type Recommended for AUTH_TYPE Description
IAM Trusted Profiles (compute resource container) Cloudant
(SDK running in IBM Cloud Containers, including Serverless)		 CONTAINER Obtains a compute resource (CR) token from the container.
Exchanges the CR token for an IAM access_token.
Adds an Authorization header to each HTTP request with the access_token bearer.
Automatically renews the access token when needed.
IAM Trusted Profiles (compute resource VPC) Cloudant
(SDK running in IBM Cloud VPC)		 VPC Obtains an identity token from the VPC instance metadata.
Exchanges the identity token for an IAM access_token.
Adds an Authorization header to each HTTP request with the access_token bearer.
Automatically renews the access token when needed.
IAM Trusted Profiles (assume identity) Cloudant IAMASSUME Exchanges an IAM API key for an IAM access_token (same as IAM auth type).
Uses that initial token to obtain a second access_token from IAM with the assumed identity information.
Adds an Authorization header to each HTTP request with the access_token bearer.
Automatically renews the access token when needed.
IAM API key Cloudant IAM Exchanges an IAM API key for an IAM access_token.
Adds an Authorization header to each HTTP request with the access_token bearer.
Automatically renews the access token when needed.
Session cookie Cloudant
(legacy credentials & instances without IAM)

Apache CouchDB		 COUCHDB_SESSION Exchanges credentials with /_session endpoint to retrieve a cookie.
Adds Cookie header and content to each HTTP request.
Automatically renews session when needed.
Bearer token Apache CouchDB
(using JWT authentication)		 BEARERTOKEN Adds an Authorization header to each HTTP request with the bearer token.
No token management or renewal.
Also compatible with IAM access tokens managed independently of the SDK.
Basic Apache CouchDB
(if cookies are not enabled)		 BASIC Adds an Authorization header to each HTTP request with the base64 encoded basic credentials.
None - NOAUTH Note that this authentication type only works for operations against a database allowing access for unauthenticated users.

The default authentication type for the SDK is CONTAINER unless supplying APIKEY configuration, which changes the default authentication type to IAM.

Authentication with environment variables

The default service name is CLOUDANT so these examples use CLOUDANT_ prefixed names.

Any custom service name prefix is valid, provided it matches the name used to instantiate the SDK client and applied to all configuration options.

IAM API key authentication

For Cloudant IAM API key authentication, set the following environmental variables by amending the values with your own service credentials. There is no need to set CLOUDANT_AUTH_TYPE to IAM because it is the default when supplying an APIKEY.

CLOUDANT_URL=https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
CLOUDANT_APIKEY=a1b2c3d4e5f6f1g4h7j3k6l9m2p5q8s1t4v7x0z3 # use your own IAM API key

IAM Trusted profile (container) authentication

For Cloudant IAM Trusted profile compute resource container authentication, set the following environmental variables, amending with your own correct values. There is no need to set CLOUDANT_AUTH_TYPE to CONTAINER because it is the default.

CLOUDANT_URL=https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
CLOUDANT_IAM_PROFILE_ID=Profile-00000000-0000-0000-0000-000000000000 # use your own IAM Profile ID

Alternatives to CLOUDANT_IAM_PROFILE_ID:

  • CLOUDANT_IAM_PROFILE_NAME

IAM Trusted profile (VPC) authentication

For Cloudant IAM Trusted profile compute resource vpc authentication, set the following environmental variables, amending with your own correct values.

CLOUDANT_AUTH_TYPE=VPC
CLOUDANT_URL=https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
CLOUDANT_IAM_PROFILE_ID=Profile-00000000-0000-0000-0000-000000000000 # use your own IAM Profile ID

Alternatives to CLOUDANT_IAM_PROFILE_ID:

  • CLOUDANT_IAM_PROFILE_CRN
  • No profile information (uses the default trusted profile linked to the compute resource)

IAM Trusted profile (assume identity) authentication

For Cloudant IAM Trusted profile assume authentication, set the following environmental variables, amending with your own correct values.

CLOUDANT_AUTH_TYPE=IAMASSUME
CLOUDANT_URL=https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
CLOUDANT_IAM_PROFILE_ID=Profile-00000000-0000-0000-0000-000000000000 # use your own IAM Profile ID

Alternatives to CLOUDANT_IAM_PROFILE_ID:

  • CLOUDANT_IAM_PROFILE_CRN
  • CLOUDANT_IAM_PROFILE_NAME and CLOUDANT_IAM_ACCOUNT_ID (ID of the account that contains the named trusted profile)

Session cookie authentication

For COUCHDB_SESSION authentication, set the following environmental variables amending with your own service credentials.

CLOUDANT_AUTH_TYPE=COUCHDB_SESSION
CLOUDANT_URL=https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
CLOUDANT_USERNAME=username # replace with your Cloudant legacy username
CLOUDANT_PASSWORD=password # replace with your Cloudant legacy password or API key (not IAM)

Bearer token authentication

Preferably use IAM authentication methods to automatically manage bearer tokens.

For bearer token authentication, set the following environmental variables, amending with your own correct values.

CLOUDANT_AUTH_TYPE=BEARERTOKEN
CLOUDANT_URL=https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
CLOUDANT_BEARER_TOKEN=A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c # replace with your bearer token

Basic authentication

Preferably use session cookie authentication instead.

To use basic HTTP authentication set the following environmental variables, amending with your own correct values.

CLOUDANT_AUTH_TYPE=BASIC
CLOUDANT_URL=https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
CLOUDANT_USERNAME=username # replace with your Cloudant legacy username
CLOUDANT_PASSWORD=password # replace with your Cloudant legacy password or API key (not IAM)

Authentication with external configuration

For more information about using an external configuration file, see the related documentation in Cloudant API docs, or the general SDK usage information.

Programmatic authentication

To learn more about how to use programmatic authentication, see the related documentation in the Cloudant API docs or in the Python SDK Core document about authentication.