Credentials - e6data Docs

TutorialApplies to: Unified engine deployments

Use SQL to define how Laminar authenticates to a service. This page covers all five credential providers and all 31 supported authentication methods. Choose the method that matches your environment; you do not need to create every example. A credential stores an authentication definition and secret references. It does not grant remote permissions. Acquired keys and tokens are separate from the saved definition.

Before you start

Read Secrets first. Copy examples into Workbench and run the statements in order in the same session. Stop if a statement fails and inspect its output. Use unused learn_ names and replace example IDs, paths, regions, and URLs with values for your environment. Examples with learn_files://... require an operator-configured file secret provider named learn_files. Its mapping must contain the named input and supply the format described below. Replace that reference with an actual provider reference or a local secret name if you use another secret store. No file is uploaded by this SQL.

Referenced input	Required content
`aws_bundle`	AWS JSON key bundle
`aws_access_key`, `aws_secret_key`, `aws_session_token`	Individual AWS key and session-token values
`subject_token`, `assertion`	A valid token or assertion for the configured trust relationship
`gcp_service_account`, `gcp_authorized_user`, `gcp_external_account`	Complete Google credential JSON of the matching type
`azure_client_secret`, `oauth_client_secret`	The application’s client secret
`certificate`, `certificate_base64`, `certificate_pem`, `private_key`, `certificate_password`, `private_key_password`	Certificate/key bytes, encoding, and passwords matching the selected format
`azure_account_key`, `azure_sas`	An Azure storage account key or SAS token
`bearer_token`	Raw token text

File paths and runtime identities belong to the credential-service host, not the browser. Cloud roles, trust policies, identity bindings, and permissions must already exist. A consumer must support the kind of credential you select.

Choose a provider

Provider	Methods covered here
AWS	Saved keys, default chain, environment, profile, container, instance role, IRSA, Pod Identity, workload identity, web identity, AssumeRole
Google Cloud	Default chain, application default, attached identity, service account, authorized user, external account, workload identity, impersonation
Azure	Default chain, managed identity, workload identity, client secret, certificate, assertion, developer tools, shared key, SAS
Bearer	Saved token
OAuth 2.0	Fixed endpoint (`client_credentials`) and consumer-supplied endpoint (`saved`)

OPTIONS contains public settings. SECRETS contains references, not secret plaintext. source names another credential. Source credentials must already exist and must not form a cycle.

AWS

All methods except saved require region. Saved credentials provide keys; region and endpoint settings for their consumer belong on that consumer.

Saved AWS keys

Use an existing JSON key bundle from a secret provider. It must contain aws_access_key_id and aws_secret_access_key. Optional fields are aws_session_token and expires_at_unix_millis. Short key aliases such as access_key_id are also accepted.

CREATE CREDENTIAL learn_aws_saved USING aws
OPTIONS (
  'authentication' = 'saved'
)
SECRETS (
  'credential' = 'learn_files://aws_bundle'
);

Alternatively, supply separate references. Include session_token for temporary keys; omit it for long-lived keys. Do not combine these fields with a bundle.

CREATE CREDENTIAL learn_aws_keys USING aws
OPTIONS (
  'authentication' = 'saved'
)
SECRETS (
  'access_key_id' = 'learn_files://aws_access_key',
  'secret_access_key' = 'learn_files://aws_secret_key',
  'session_token' = 'learn_files://aws_session_token'
);

An optional expires_at_unix_millis option sets an expiry for saved material. It does not renew keys. Replace expired values or use a method that obtains fresh credentials.

Default AWS credential chain

Use the AWS SDK credential sources available on the host. An optional profile selects a host profile.

CREATE CREDENTIAL learn_aws_default_chain USING aws
OPTIONS (
  'authentication' = 'default_chain',
  'region' = 'us-east-1'
);

Environment credentials

Set AWS credential environment variables on the credential-service host before using this method.

CREATE CREDENTIAL learn_aws_environment USING aws
OPTIONS (
  'authentication' = 'environment',
  'region' = 'us-east-1'
);

Named profile

Install the analytics profile on that host. SDK-supported SSO, process, and role profiles require their own tools and valid login state.

CREATE CREDENTIAL learn_aws_profile USING aws
OPTIONS (
  'authentication' = 'profile',
  'region' = 'us-east-1',
  'profile' = 'analytics'
);

Container credentials

Use a runtime with a configured container credential endpoint, such as an ECS task role. ECS is Amazon Elastic Container Service.

CREATE CREDENTIAL learn_aws_container USING aws
OPTIONS (
  'authentication' = 'container',
  'region' = 'us-east-1'
);

EC2 instance role

Attach an IAM role to the EC2 instance and make its metadata service available.

CREATE CREDENTIAL learn_aws_instance_role USING aws
OPTIONS (
  'authentication' = 'instance_role',
  'region' = 'us-east-1'
);

IRSA

IRSA associates an EKS Kubernetes service account with an IAM role. Configure the role trust and injected token-file/role environment before use.

CREATE CREDENTIAL learn_aws_irsa USING aws
OPTIONS (
  'authentication' = 'irsa',
  'region' = 'us-east-1'
);

EKS Pod Identity

Configure the EKS Pod Identity association and runtime credential endpoint. This method obtains container credentials; it does not create the association.

CREATE CREDENTIAL learn_aws_pod_identity USING aws
OPTIONS (
  'authentication' = 'pod_identity',
  'region' = 'us-east-1'
);

AWS workload identity

Let the runtime choose IRSA when its token-file environment is present, then container identity, otherwise an instance role.

CREATE CREDENTIAL learn_aws_workload_identity USING aws
OPTIONS (
  'authentication' = 'workload_identity',
  'region' = 'us-east-1'
);

For explicit IRSA, provide both role_arn and token_file. Do not provide only one:

CREATE CREDENTIAL learn_aws_irsa_explicit USING aws
OPTIONS (
  'authentication' = 'irsa',
  'region' = 'us-east-1',
  'role_arn' = 'arn:aws:iam::123456789012:role/LessonReader',
  'token_file' = '/var/run/secrets/eks.amazonaws.com/serviceaccount/token'
);

Web identity

Exchange a web identity token for an AWS role session. The role must trust that token issuer and audience. Choose exactly one source: a token file, a subject_token secret, or a named token-producing credential.

CREATE CREDENTIAL learn_aws_web_identity USING aws
OPTIONS (
  'authentication' = 'web_identity',
  'region' = 'us-east-1',
  'role_arn' = 'arn:aws:iam::123456789012:role/LessonReader',
  'token_file' = '/run/identity/token'
);

The secret-reference variant uses the same role, without token_file:

CREATE CREDENTIAL learn_aws_web_secret USING aws
OPTIONS (
  'authentication' = 'web_identity',
  'region' = 'us-east-1',
  'role_arn' = 'arn:aws:iam::123456789012:role/LessonReader'
)
SECRETS (
  'subject_token' = 'learn_files://subject_token'
);

For a named Google source, first create learn_gcp_attached from the Google section. Set the audience expected by the AWS trust policy. Laminar requests an ID token from that source.

CREATE CREDENTIAL learn_aws_web_source USING aws
OPTIONS (
  'authentication' = 'web_identity',
  'region' = 'us-east-1',
  'role_arn' = 'arn:aws:iam::123456789012:role/LessonReader',
  'source' = 'learn_gcp_attached',
  'audience' = '<trusted-audience>'
);

Assume an IAM role

First create learn_aws_default_chain above. Its identity must be allowed to assume this role, and the target role must trust it. The source must provide AWS credentials.

CREATE CREDENTIAL learn_aws_assume_role USING aws
OPTIONS (
  'authentication' = 'assume_role',
  'region' = 'us-east-1',
  'source' = 'learn_aws_default_chain',
  'role_arn' = 'arn:aws:iam::123456789012:role/LessonReader',
  'session_name' = 'learn-laminar',
  'duration_seconds' = '3600'
);

Optional options include external_id, a JSON session policy, and comma-separated policy_arns. They restrict or qualify the session; they do not create permissions. duration_seconds accepts 900–43200, subject to the remote role limits. Web identity also accepts a session name and duration.

Google Cloud

Google credentials obtain tokens through the Google SDK. Optional common options include space-separated scopes, quota_project_id, and universe_domain. The consumer may request its own token scope. A scope describes requested access; it does not grant IAM permissions.

Default Google credential chain

Use the Google SDK Application Default Credentials available on the host.

CREATE CREDENTIAL learn_gcp_default_chain USING gcp
OPTIONS (
  'authentication' = 'default_chain'
);

Application Default Credentials

This explicit method also uses Application Default Credentials (ADC). Set up the host identity or ADC file before use.

CREATE CREDENTIAL learn_gcp_application_default USING gcp
OPTIONS (
  'authentication' = 'application_default'
);

Attached compute identity

Use the runtime metadata identity, including an attached compute service account or GKE metadata. Do not supply a credential document for this method.

CREATE CREDENTIAL learn_gcp_attached USING gcp
OPTIONS (
  'authentication' = 'attached_identity'
);

Service account document

Supply a complete service-account JSON document from a secret provider. The service account needs permission on the intended service.

CREATE CREDENTIAL learn_gcp_service_account USING gcp
OPTIONS (
  'authentication' = 'service_account'
)
SECRETS (
  'credential' = 'learn_files://gcp_service_account'
);

Authorized-user document

Supply a complete authorized-user JSON document, including its refresh-token material. It is a different format from a service-account document.

CREATE CREDENTIAL learn_gcp_authorized_user USING gcp
OPTIONS (
  'authentication' = 'authorized_user'
)
SECRETS (
  'credential' = 'learn_files://gcp_authorized_user'
);

External-account federation

Supply a valid external-account document. Its workload identity pool, provider trust, subject-token source, and remote permissions must already be configured.

CREATE CREDENTIAL learn_gcp_external_account USING gcp
OPTIONS (
  'authentication' = 'external_account'
)
SECRETS (
  'credential' = 'learn_files://gcp_external_account'
);

Google workload identity federation

This method also uses an external-account document. It is different from using the attached GKE metadata identity.

CREATE CREDENTIAL learn_gcp_workload_identity USING gcp
OPTIONS (
  'authentication' = 'workload_identity'
)
SECRETS (
  'credential' = 'learn_files://gcp_external_account'
);

For any of these four document methods, choose either a credential secret or a credential_file, not both. A service-account file variant is:

CREATE CREDENTIAL learn_gcp_service_file USING gcp
OPTIONS (
  'authentication' = 'service_account',
  'credential_file' = '/run/credentials/google-service-account.json'
);

For federation from another named credential, keep the external-account document and add source. AWS sources also need aws_region. Create the AWS default-chain source first:

CREATE CREDENTIAL learn_gcp_from_aws USING gcp
OPTIONS (
  'authentication' = 'external_account',
  'source' = 'learn_aws_default_chain',
  'aws_region' = 'us-east-1'
)
SECRETS (
  'credential' = 'learn_files://gcp_external_account'
);

A Google or Azure token source uses source_audience instead of aws_region. A bearer source supplies its saved token. Use a document whose subject-token type and trust match the source. For example, after creating learn_gcp_attached:

CREATE CREDENTIAL learn_gcp_from_google USING gcp
OPTIONS (
  'authentication' = 'workload_identity',
  'source' = 'learn_gcp_attached',
  'source_audience' = '<trusted-source-audience>'
)
SECRETS (
  'credential' = 'learn_files://gcp_external_account'
);

Impersonate a service account

Create learn_gcp_application_default first. That source identity must be allowed to impersonate the target service account. Replace the example principal with your service account.

CREATE CREDENTIAL learn_gcp_impersonation USING gcp
OPTIONS (
  'authentication' = 'impersonate_service_account',
  'source' = 'learn_gcp_application_default',
  'target_principal' = '[email protected]',
  'lifetime_seconds' = '3600'
);

Alternatively, omit source to use ADC, or supply a document through credential or credential_file. Named sources may be GCP or bearer credentials. Optional delegates is a comma-separated service-account chain. lifetime_seconds accepts 1–43200; the service may impose tighter limits. metadata_endpoint is only for attached_identity. ID-token support depends on the underlying Google method; authorized-user and external-account documents may require service-account impersonation for that use.

Azure

Identity methods obtain tokens. Shared keys and SAS provide storage-specific access. Optional token settings include scopes or resource. Choose cloud as public, government, or china, or set a custom HTTPS authority_host; do not set both. The target endpoint and token scope must match the cloud.

Default Azure credential chain

Use the production chain on the credential-service host: federated token file, environment client secret, then managed identity. This is separate from developer-tool login.

CREATE CREDENTIAL learn_azure_default USING azure
OPTIONS (
  'authentication' = 'default_chain'
);

Managed identity

Use a system-assigned identity attached to the runtime. Its metadata service and remote permissions must be available.

CREATE CREDENTIAL learn_azure_managed USING azure
OPTIONS (
  'authentication' = 'managed_identity'
);

For a user-assigned identity, choose exactly one of client_id, object_id, or resource_id. For example:

CREATE CREDENTIAL learn_azure_user_assigned USING azure
OPTIONS (
  'authentication' = 'managed_identity',
  'client_id' = '<managed-identity-client-id>'
);

Azure workload identity

Configure the federated application and token file, such as AKS workload identity. Values can come from options or the standard runtime environment. This example makes them explicit.

CREATE CREDENTIAL learn_azure_workload USING azure
OPTIONS (
  'authentication' = 'workload_identity',
  'tenant_id' = '<tenant-id>',
  'client_id' = '<application-id>',
  'token_file' = '/var/run/secrets/azure/tokens/azure-identity-token'
);

Application client secret

Register the application and grant it access first. Supply its directory tenant ID, application client ID, and client-secret reference.

CREATE CREDENTIAL learn_azure_client_secret USING azure
OPTIONS (
  'authentication' = 'client_secret',
  'tenant_id' = '<tenant-id>',
  'client_id' = '<application-id>'
)
SECRETS (
  'client_secret' = 'learn_files://azure_client_secret'
);

Application certificate

Register the public certificate with the application. The default format is raw pkcs12. The secret must contain matching certificate and key material. Include the password reference only when the certificate requires it.

CREATE CREDENTIAL learn_azure_certificate USING azure
OPTIONS (
  'authentication' = 'client_certificate',
  'tenant_id' = '<tenant-id>',
  'client_id' = '<application-id>',
  'certificate_format' = 'pkcs12'
)
SECRETS (
  'certificate' = 'learn_files://certificate',
  'certificate_password' = 'learn_files://certificate_password'
);

For base64-encoded PKCS#12, use this variant. Add certificate_password if needed:

CREATE CREDENTIAL learn_azure_certificate_base64 USING azure
OPTIONS (
  'authentication' = 'client_certificate',
  'tenant_id' = '<tenant-id>',
  'client_id' = '<application-id>',
  'certificate_format' = 'base64-pkcs12'
)
SECRETS (
  'certificate' = 'learn_files://certificate_base64'
);

PEM certificates require a separate private_key reference. Add private_key_password only for an encrypted private key:

CREATE CREDENTIAL learn_azure_certificate_pem USING azure
OPTIONS (
  'authentication' = 'client_certificate',
  'tenant_id' = '<tenant-id>',
  'client_id' = '<application-id>',
  'certificate_format' = 'pem'
)
SECRETS (
  'certificate' = 'learn_files://certificate_pem',
  'private_key' = 'learn_files://private_key',
  'private_key_password' = 'learn_files://private_key_password'
);

Client assertion

Supply a valid assertion trusted by the target application. Choose an assertion secret or a named source, never both. A saved assertion may expire and need replacement.

CREATE CREDENTIAL learn_azure_assertion USING azure
OPTIONS (
  'authentication' = 'client_assertion',
  'tenant_id' = '<tenant-id>',
  'client_id' = '<application-id>'
)
SECRETS (
  'assertion' = 'learn_files://assertion'
);

A named source can be an Azure, Google, or bearer credential. First create the source and configure the application trust. This Google example requests an ID token for api://AzureADTokenExchange:

CREATE CREDENTIAL learn_azure_assertion_source USING azure
OPTIONS (
  'authentication' = 'client_assertion',
  'tenant_id' = '<tenant-id>',
  'client_id' = '<application-id>',
  'source' = 'learn_gcp_attached'
);

Developer tools

Use the explicit Azure SDK developer-tool chain. Supported tools and a valid login must already be available on the credential-service host. Browser login does not supply this identity.

CREATE CREDENTIAL learn_azure_developer USING azure
OPTIONS (
  'authentication' = 'developer_tools'
);

Storage shared key

Use an Azure Blob storage account name and a reference to its account key. This credential is storage-specific, not a bearer token for a catalog API.

CREATE CREDENTIAL learn_azure_shared_key USING azure
OPTIONS (
  'authentication' = 'shared_key',
  'account_name' = '<storage-account>'
)
SECRETS (
  'account_key' = 'learn_files://azure_account_key'
);

Storage SAS token

A shared access signature (SAS) limits storage access by permissions, target, and often time. Supply a token that matches the intended storage consumer.

CREATE CREDENTIAL learn_azure_sas USING azure
OPTIONS (
  'authentication' = 'sas',
  'account_name' = '<storage-account>'
)
SECRETS (
  'sas_token' = 'learn_files://azure_sas'
);

SAS expiry is read from se in the token and/or an earlier expires_at_unix_millis option. The earliest applicable expiry wins. Saving a SAS definition does not renew it. Shared keys also accept an optional configured expiry. Remove expired material or rotate its secret source.

Bearer token

A bearer token is sent as the service access token. Its secret must be raw token text, not a JSON wrapper.

CREATE CREDENTIAL learn_bearer USING bearer
OPTIONS (
  'authentication' = 'saved'
)
SECRETS (
  'token' = 'learn_files://bearer_token'
);

The saved method does not perform an OAuth exchange or refresh that token. Rotate the referenced secret when its token changes.

OAuth 2.0

OAuth client credentials exchange a client ID and secret for an access token. The application, grant, and permissions must already exist. These methods do not implement an interactive browser sign-in.

Fixed token endpoint

Choose client_credentials when this credential fixes the token endpoint. Replace the client ID, HTTPS endpoint, and scopes with values accepted by the token service.

CREATE CREDENTIAL learn_oauth_fixed USING oauth2
OPTIONS (
  'authentication' = 'client_credentials',
  'client_id' = '<client-id>',
  'token_endpoint' = 'https://identity.example.com/oauth/token',
  'scopes' = 'catalog.read'
)
SECRETS (
  'client_secret' = 'learn_files://oauth_client_secret'
);

Optional audience and resource identify the token target where supported. Scopes are space-separated. If a consuming catalog also supplies an endpoint, it must match the fixed endpoint.

Use the consumer token endpoint

Choose saved for the form option called Use target token endpoint. The consuming catalog supplies the token endpoint. Despite its name, this method stores a client definition, not a ready-made bearer token.

CREATE CREDENTIAL learn_oauth_target USING oauth2
OPTIONS (
  'authentication' = 'saved',
  'client_id' = '<client-id>'
)
SECRETS (
  'client_secret' = 'learn_files://oauth_client_secret'
);

The consumer must supply an appropriate endpoint for the token exchange. Obtained OAuth tokens can be renewed through the provider while the client secret and permissions remain valid. This is different from replacing a saved bearer token.

Inspect and use a credential

After creating a chosen example, inspect its definition. These commands return configuration and secret references, not acquired keys or tokens.

SHOW CREDENTIALS;
DESCRIBE CREDENTIAL learn_bearer;

Use the name you actually created. A successful CREATE or DESCRIBE is not a remote authentication test. For a catalog that accepts bearer authentication, attach the bearer credential to auth. If its table files need separate AWS access, attach an AWS credential to storage. Create both credentials first. Replace the endpoint, warehouse, and region for your existing service:

CREATE CATALOG learn_access_catalog USING `iceberg-rest`
OPTIONS (
  'uri' = 'https://catalog.example.com',
  'warehouse' = 'retail',
  'auth.type' = 'bearer',
  's3.region' = 'us-east-1'
)
CREDENTIALS (
  'auth' = 'learn_bearer',
  'storage' = 'learn_aws_default_chain'
);

This is an example for that specific catalog and S3 storage combination. For OAuth or signed requests, use the corresponding catalog method and provider options. Storage credentials and metadata credentials can be different identities. A saved credential does not add support for a service connector that Laminar does not implement. Use an existing namespace and table in that catalog to check real access:

SHOW CATALOGS;
USE CATALOG learn_access_catalog;
SHOW NAMESPACES;
USE retail;
SHOW TABLES;
DESCRIBE TABLE orders;
SELECT * FROM orders LIMIT 5;

Replace retail and orders with actual names. Run each statement separately to inspect its result. Use a known non-empty table: listing metadata alone does not prove access to its files. The catalog connection reference lists the provider-specific settings.

Change one thing

If you created the named AWS profile example, select a second profile that already exists on the host:

ALTER CREDENTIAL learn_aws_profile
SET OPTIONS ('profile' = 'analytics_readonly');
DESCRIBE CREDENTIAL learn_aws_profile;

Expect the definition’s profile and revision to change. Rerun a consumer query to prove that the new profile has the intended access. Do not change a shared credential for this exercise. You can also replace one secret reference:

ALTER CREDENTIAL learn_bearer
SET SECRETS ('token' = 'learn_sm://retail/replacement-token');
DESCRIBE CREDENTIAL learn_bearer;

This example needs that actual provider alias and remote token. ALTER preserves the name and provider. It keeps options and secret roles not mentioned in the command. Use UNSET OPTIONS ('key') or UNSET SECRETS ('role') to remove fields that no longer apply, while leaving a valid definition. Changing the authentication method may require removing old fields in the same ALTER statement.

Check the result

You have a named credential with the expected provider, authentication method, source, and secret references. A real consumer read proves that the remote service accepts it. Saved configuration, acquired authentication, and authorized data access are separate checks.

Clean up

Remove lesson consumers before their credentials. If you created the sample catalog and bearer credential:

DROP CATALOG IF EXISTS learn_access_catalog;
DROP CREDENTIAL IF EXISTS learn_bearer;

Use DROP CREDENTIAL IF EXISTS for the other examples you actually created. Remove dependent credentials before their source credentials: for example, drop learn_aws_assume_role before learn_aws_default_chain. Then remove any lesson-only secrets. Credential deletion does not revoke a cloud key, delete an IAM role, or remove remote permissions. Keep shared resources in place.

Continue

Connect your data uses credentials to open catalogs. Secrets explains value storage, external references, versions, and rotation. Provider guides cover AWS, Google Cloud, Azure, and tokens and OAuth.

​Before you start

​Choose a provider

​AWS

​Saved AWS keys

​Default AWS credential chain

​Environment credentials

​Named profile

​Container credentials

​EC2 instance role

​IRSA

​EKS Pod Identity

​AWS workload identity

​Web identity

​Assume an IAM role

​Google Cloud

​Default Google credential chain

​Application Default Credentials

​Attached compute identity

​Service account document

​Authorized-user document

​External-account federation

​Google workload identity federation

​Impersonate a service account

​Azure

​Default Azure credential chain

​Managed identity

​Azure workload identity

​Application client secret

​Application certificate

​Client assertion

​Developer tools

​Storage shared key

​Storage SAS token

​Bearer token

​OAuth 2.0

​Fixed token endpoint

​Use the consumer token endpoint

​Inspect and use a credential

​Change one thing

​Check the result

​Clean up

​Continue