Filesystem-Based Setup

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

This page describes how to configure the Alation Agent machine to use IAM Roles Anywhere with a filesystem-based private key. The private key and client certificate are stored as PEM files on the Agent machine’s filesystem.

Important

Before following the steps on this topic, complete Steps 1 through 4 on the Integrate Agent with Secrets Manager Using IAM Roles Anywhere.

Step 1: Set Up the Alation Agent Machine

This step is performed on the Alation Agent machine

  1. Use SSH to connect to the Alation Agent machine.

  2. Check if the .aws directory exists under /etc/hydra/auth/. If not, create it:

    sudo mkdir -p /etc/hydra/auth/.aws

  3. Copy the client certificate and private key into the .aws directory:

    sudo cp <path-to-client-certificate> /etc/hydra/auth/.aws/client.crt
sudo cp <path-to-client-private-key> /etc/hydra/auth/.aws/client_private.key

    Replace <path-to-client-certificate> and <path-to-client-private-key> with the actual paths where the certificate and key files are located on the agent machine.

  4. Verify that all required files are present in /etc/hydra/auth/.aws/:

    sudo ls -la /etc/hydra/auth/.aws/

    You should see the following files:

    File

    Description

    client.crt

    The CA-signed client certificate

    client_private.key

    The client certificate’s private key

    If any of these files are missing, complete the previous steps before continuing.

  5. Create the AWS credentials file at /etc/hydra/auth/.aws/credentials:

    sudo vi /etc/hydra/auth/.aws/credentials

    Add the following content. The entire credential_process value must be on a single line (no line breaks):

    [<profile-name>]
credential_process = /usr/local/bin/aws_signing_helper credential-process --certificate /opt/alation/site/config/authserver/.aws/client.crt --private-key /opt/alation/site/config/authserver/.aws/client_private.key --trust-anchor-arn <trust-anchor-arn> --profile-arn <profile-arn> --role-arn <role-arn>

    Replace the following placeholders:

    Placeholder

    Description

    Example

    <profile-name>

    The profile name configured in the Alation UI authentication profile

    iam_roles_anywhere_profile

    <role-arn>

    The IAM Role ARN from Step 2

    arn:aws:iam::248135293344:role/AlationSecretsManagerAccess

    <trust-anchor-arn>

    The Trust Anchor ARN from Step 3

    arn:aws:rolesanywhere:us-east-1:248135293344:trust-anchor/bdd70097-...

    <profile-arn>

    The Roles Anywhere Profile ARN from Step 4

    arn:aws:rolesanywhere:us-east-1:248135293344:profile/71b7f5ac-...

    Important

    • The certificate and key paths inside the credentials file must use container paths (/opt/alation/site/config/authserver/.aws/...), not the host bind mount paths (/etc/hydra/auth/.aws/...). The Auth Service reads this file from within the container.

    • The aws_signing_helper binary path is /usr/local/bin/aws_signing_helper (pre-installed in the container), not a host path.

    • The credential_process value must be on a single line with no line breaks. Multi-line values will cause a parsing error.

  6. Apply the correct ownership and permissions to all files:

    # Directory — accessible only to root and alationdocker group
sudo chmod 750 /etc/hydra/auth/.aws

# Private key — most sensitive file, group read only
sudo chmod 640 /etc/hydra/auth/.aws/client_private.key

# Client certificate — group read only
sudo chmod 640 /etc/hydra/auth/.aws/client.crt

# Credentials file — group read only
sudo chmod 640 /etc/hydra/auth/.aws/credentials

# Set ownership (root user, alationdocker group)
sudo chown -R root:alationdocker /etc/hydra/auth/.aws

  7. Restart the Auth Service container to pick up the new configuration:

    sudo docker restart auth

Step 2: Create an Authentication Profile

This step is performed in Alation

To create an authentication profile for the Secrets Manager integration:

  1. Log in to your Alation instance as a Server Admin.

  2. Click the Admin Settings gear icon on top right to open the Admin Settings page.

  3. Click Authentication to open the Authentication tab. Locate the section Authentication Configuration Methods for External Systems.

  1. Next to See configurations for, click the drop-down menu and select the relevant Alation Agent.

  2. Click Add Configuration, and then select AWS Secrets Manager as the method type. The Authentication Configuration Method page will open in a new browser tab.

  3. In Config Name, enter a unique name for the configuration. Save it for future reference when configuring the data source.

  4. Under Region, select the appropriate AWS region for the Secrets Manager service (the region under which your secrets are stored).

  5. Under Authentication Type, select IAM Roles Anywhere.

  6. Click Save. Alation attempts to create a connection, and if the connection is successful, the configuration is saved.

Now, you can use your integration with an OCF connector. See next: Configure Authentication with AWS Secrets Manager for a Data Source.

Troubleshooting

Error: Untrusted certificate. Insufficient certificate

Cause: AWS does not trust the client certificate. This can happen when:

  • The client certificate was not signed by the CA registered in the trust anchor.

  • The CA certificate was regenerated after the trust anchor was created.

  • The client certificate is missing the Digital Signature key usage extension.

Fix:

  1. Verify the certificate chain:

    openssl verify -CAfile ca.crt client.crt
# Expected: client.crt: OK

  2. Verify the client certificate has the required key usage:

    openssl x509 -in client.crt -text -noout | grep -A1 "Key Usage"
# Expected: Digital Signature

  3. If the CA was regenerated, update the trust anchor in the AWS console with the new CA certificate and re-sign the client certificate.

Error: Incorrect basic constraints for CA certificate

Cause: The CA certificate is missing Basic Constraints: CA:TRUE or is not X.509 Version 3.

Fix: Regenerate the CA certificate with the correct extensions (see the Certificate Requirements section on the parent page). After regenerating the CA certificate, you must also re-sign the client certificate and update the trust anchor in AWS.

Error: syntax error: unexpected newline

Cause: The credential_process line in the credentials file contains line breaks.

Fix: Ensure the credential_process value in the credentials file is on a single line with no line breaks.

Error: Expected a profile or property definition

Cause: The credentials file has formatting issues, typically line breaks in the credential_process value.

Fix: Open the credentials file and ensure the credential_process value is on a single line. Remove any line breaks or line continuation characters.

Error: AccessDeniedException when accessing Secrets Manager

Cause: The IAM role does not have sufficient permissions for Secrets Manager, or the Roles Anywhere session policy is too restrictive.

Fix:

  1. Verify the IAM role has the required Secrets Manager permissions.

  2. If using session policies on the Roles Anywhere profile, ensure they allow the required Secrets Manager actions.

  3. Verify the secret’s resource policy (if any) allows access from the assumed role.