View a markdown version of this page

Configuring Workday Live Data Query connections - AWS Glue
Configuring Workday Live Data Query connections with the AWS CLI

Configuring Workday Live Data Query connections

Workday Live Data Query uses the OAuth 2.0 JWT bearer grant type (RFC 7523). AWS Glue creates a JSON Web Token (JWT) for your Workday Integration System User (ISU), signs it with your private key, and exchanges it at your Workday OAuth 2.0 token endpoint for a short-lived access token. AWS Glue requests a new access token when the current one expires, without user interaction. This grant type works well for automation because no user needs to sign in to Workday when the connection is created or used.

You store the OAuth 2.0 client ID, ISU user name, token endpoint, and private key in an AWS Secrets Manager secret. AWS Glue reads the secret but doesn't modify it. The ISU's security permissions in Workday determine which data AWS Glue can read.

Before you begin, collect the values listed in Configuring Workday Live Data Query. Workday displays the token endpoint, Integration System User, and client ID after your Workday administrator completes the Register API Client task. For more information, see Set Up Live Data Query ISU Authentication in Workday in the Workday documentation.

To configure a Workday Live Data Query connection:

  1. In AWS Secrets Manager, create a secret with the following key/value pairs. Follow the steps in Create an AWS Secrets Manager secret in the AWS Secrets Manager User Guide. Keep the secret name, secretName, for the next step.

    • wd.authn.clientId – Your OAuth 2.0 client ID.

    • wd.authn.isu – The user name of your Integration System User.

    • wd.authn.accessTokenEndpoint – Your Workday OAuth 2.0 token endpoint, for example https://host/ccx/oauth2/tenant/token.

    • wd.authn.privateKey – Your PEM-formatted private key, including the BEGIN and END PRIVATE KEY lines.

    Note

    The key names are reserved. Enter them exactly as shown. The private key must keep its line breaks. If you create the secret as JSON, encode each line break in the private key as \n.

  2. Create an IAM role that AWS Glue can assume, with permission to read secretName. Use the following trust policy:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "glue.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "123456789012"
                }
            }
        }
    ]
}

    Attach a permissions policy that allows secretsmanager:GetSecretValue on your secret. If you want to use this role for your AWS Glue jobs too, also attach the AWSGlueServiceRole managed policy. You can use the following policy statement:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "secretsmanager:GetSecretValue",
            "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:secretName-AbCdEf"
        }
    ]
}

  3. In the AWS Glue console, create the connection from AWS Glue Studio:

    1. In the navigation pane, choose Visual ETL, then choose Visual ETL to create a job.

    2. Under Sources, choose Workday Live Data Query.

    3. For the AWS Glue connection, choose an existing Workday Live Data Query connection or create a new one.

    4. On the Create Workday Live Data Query connection page, under Connection access, provide the following:

      • For Host, provide your Workday Data Service host name. This is usually the same host as your token endpoint, for example services1.wd12.myworkday.com.

      • For Port, provide 443.

      • (Optional) Select EnforceSSL to enforce SSL.

      • (Optional) For JDBC URL Parameters, provide additional Workday driver parameters as key1=value1;key2=value2. Leave this empty unless your Workday administrator gives you a specific setting.

      • For IAM Role ARN, choose the role from step 2.

    5. Under Authentication, for AWS Secret, choose Select secret from this account and choose secretName, or choose Manually enter secret ARN. The secret must contain wd.authn.accessTokenEndpoint, wd.authn.clientId, wd.authn.isu, and wd.authn.privateKey.

    6. (Optional) Choose Test connection. On success, the console shows Connection test successful.

    7. Choose Next.

    8. Enter a name for the connection and choose Create connection. Keep the connection name, connectionName, for the next step.

  4. Grant the IAM role associated with your AWS Glue job permission to read secretName. If your job uses a different role than the connection, also grant that role secretsmanager:GetSecretValue on secretName. The job role reads the secret directly; the connection's role doesn't cover it.

  5. If you want AWS Glue to connect to Workday from your VPC, configure network options for the connection with the AWS CLI or the AWS Glue API. For more information, see the following section. Also attach the following permissions policy to the IAM role:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeVpcs",
                "ec2:DescribeSubnets",
                "ec2:DescribeSecurityGroups",
                "ec2:CreateNetworkInterface",
                "ec2:DescribeNetworkInterfaces",
                "ec2:DeleteNetworkInterface"
            ],
            "Resource": "*"
        }
    ]
}

    The subnet must be able to reach AWS STS, AWS Secrets Manager, and your Workday Data Service host and token endpoint on port 443, for example through a NAT gateway.

  6. In your AWS Glue job, use connectionName. In a visual job, choose it in the Workday Live Data Query source node. In a script job, provide it as an Additional network connection in the job configuration.

Configuring Workday Live Data Query connections with the AWS CLI

You can create connections using the AWS CLI. Replace the example values with your own.

Save your Workday credentials in a file named workday-ldq-secret.json:

{
    "wd.authn.clientId": "your-client-id",
    "wd.authn.isu": "your-isu-user-name",
    "wd.authn.accessTokenEndpoint": "https://your-workday-host/ccx/oauth2/your-tenant/token",
    "wd.authn.privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n-----END PRIVATE KEY-----"
}

Create the secret:

aws secretsmanager create-secret \
    --name workday-ldq-secret \
    --secret-string file://workday-ldq-secret.json \
    --region us-east-1

Save the connection definition in a file named workday-ldq-connection.json:

{
    "Name": "workday-ldq-conn1",
    "ConnectionType": "WORKDAYLDQ",
    "ConnectionProperties": {
        "HOST": "your-workday-data-service-host",
        "PORT": "443",
        "ROLE_ARN": "arn:aws:iam::123456789012:role/glue-role"
    },
    "AuthenticationConfiguration": {
        "AuthenticationType": "CUSTOM",
        "SecretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:workday-ldq-secret-AbCdEf"
    },
    "ValidateCredentials": true,
    "ValidateForComputeEnvironments": [
        "SPARK"
    ]
}

Create the connection:

aws glue create-connection \
    --connection-input file://workday-ldq-connection.json \
    --region us-east-1

On success, the command returns "CreateConnectionStatus": "READY". When ValidateCredentials is true, AWS Glue gets an access token from your Workday token endpoint and runs a test query against your Workday Data Service host before creating the connection. If the test fails, the connection isn't created and the error is returned. When ValidateCredentials is false, the connection is created without testing. We recommend that you set it to true.

To connect from your VPC, add PhysicalConnectionRequirements to the connection definition:

"PhysicalConnectionRequirements": {
    "SubnetId": "subnet-0123456789abcdef0",
    "SecurityGroupIdList": [
        "sg-0123456789abcdef0"
    ],
    "AvailabilityZone": "us-east-1a"
}

With network options, AWS Glue tests the connection from your subnet, and create-connection returns "CreateConnectionStatus": "IN_PROGRESS". The test can take several minutes. Check the status with the following command and read Status (READY on success):

aws glue get-connection \
    --name workday-ldq-conn1 \
    --region us-east-1

Jobs that use the connection run in your subnet. The security group must allow workers to communicate.

To use the same connection with Amazon Athena, add "ATHENA" to ValidateForComputeEnvironments and provide the Athena connection properties, such as a spill bucket. For more information, see Amazon Athena Workday Live Data Query connector in the Amazon Athena User Guide.

The following table describes the Workday Live Data Query connection properties.

Workday Live Data Query connection properties
Property Required Description
HOST Yes Your Workday Data Service host name.
PORT Yes The port number. Use 443.
ROLE_ARN Yes, for AWS Glue ETL The IAM role AWS Glue assumes to read your secret and, if you configure network options, to create network interfaces.
ENFORCE_SSL No Whether AWS Glue enforces SSL. The default is false. In the console, this is the EnforceSSL option. Connections to Workday on port 443 use TLS whether or not you set this.
JDBC_PARAMS No Additional Workday driver parameters as key1=value1;key2=value2. In the console, this is the JDBC URL Parameters field.