Amplify-cli: Clarify usage of privacy.authRoleName and privacy.unAuthRoleName in api-params.json (REST api)

[ksokol]

Which Category is your question related to?
api

Amplify CLI Version
4.25.0

What AWS Services are you utilizing?
API Gateway

Provide additional details e.g. code snippets
What is the purpose of privacy.authRoleName and privacy.unAuthRoleName in the api-params.json?
How do these values affect the api gateway when using multiple environments?

I can not find any usage of these properties in apigw-cloudformation-template-default.json.ejs. Are they used at all?

[prompt]$ amplify add api
? Please select from one of the below mentioned services: REST
? Provide a friendly name for your resource to be used as a label for this category in the project: testapi
? Provide a path (e.g., /book/{isbn}): /items
? Choose a Lambda source Create a new Lambda function
? Provide a friendly name for your resource to be used as a label for this category in the project: testlambda
? Provide the AWS Lambda function name: testlambda
? Choose the runtime that you want to use: NodeJS
? Choose the function template that you want to use: Hello World
? Do you want to access other resources in this project from your Lambda function? No
? Do you want to invoke this function on a recurring schedule? No
? Do you want to configure Lambda layers for this function? No
? Do you want to edit the local lambda function now? No
Successfully added resource testlambda locally.

[prompt]$ cat amplify/backend/api/testapi/api-params.json 
{
    "paths": [
        {
            "name": "/items",
            "lambdaFunction": "testlambda",
            "privacy": {
                "open": true
            }
        }
    ],
    "resourceName": "testapi",
    "apiName": "testapi",
    "functionArns": [
        {
            "lambdaFunction": "testlambda"
        }
    ],
    "privacy": {
        "auth": 0,
        "unauth": 0,
        "authRoleName": "amplify-demo-live-165557-authRole",
        "unAuthRoleName": "amplify-demo-live-165557-unauthRole"
    },
    "dependsOn": [
        {
            "category": "function",
            "resourceName": "testlambda",
            "attributes": [
                "Name",
                "Arn"
            ]
        }
    ]
}

[akshbhu]

Hi @ksokol

These Roles are attached to AWS resource allowing them communicate with other services and can be of type authenticated and unauthenticated role (for the user user that didn't signup in your app) based on the usecase. Each group of users (auth and unauth) has an IAM Role which basically is the permission that each group has. (Maybe you dont want the same privileges for unauth users).

When you use aws-amplify/cli the permissions are configured for you automatically for each resource by attaching IAM policies (permissions configuration) to each role.

you can find more here: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html

you can find the use of AuthRoleName here: https://github.com/aws-amplify/amplify-cli/blob/46351a17dcc3067ace51673f403efb7be2e31228/packages/amplify-category-api/resources/awscloudformation/cloudformation-templates/apigw-cloudformation-template-default.json.ejs#L37

[ksokol]

That does not answer my questions.

What is the purpose of privacy.authRoleName and privacy.unAuthRoleName in the api-params.json because neither I do see any use of it in the apigw-cloudformation-template-default.json.ejs nor in the final cloudformation template in the api rest category folder in my project. Are they used at all?

How do these two values values affect the api gateway when using multiple environments? Let say I want to merge testing branch into production branch and the values got overwritten with the values from testing. How does it affect the production environment? Do I have a cross connection between the roles from the test environment and the production rest api?

Apparently, the api-params.json file doesn't matter at all because Amplify doesn't complain during a push when the api-params.json file is missing (deleted it right before a push, just to see want happens).

Searching for the authRoleName and unAuthRoleName value in my project, it shows up in team-provider-info.json and backend/amplify-meta.json. That makes sence. But I don't understand why the authRoleName and unAuthRoleName values are hardcoded in the api-params.json of every rest api caterogy.

[akshbhu]

Hi @ksokol

Okay I understand your question. Let me answer based on your question above:

So these values privacy.authRoleName and privacy.unAuthRoleName are not used as such as it is related to bookkeeping in file api-params.json but it wont affect any operations. We only use privacy.auth and privacy.unauth value to fill the cloudformation template as I marked in the above answer.

These values are specific to environment, so when you switch environment , it creates new roles based on the new environment. The file api-params.json is specific to that environment and it doesnt have any cross connection between environments.

As an Example :

    "privacy": {
        "auth": 1,
        "unauth": 1,
        "authRoleName": "amplify-issue4984-dev-110636-authRole",
        "unAuthRoleName": "amplify-issue4984-dev-110636-unauthRole"
    }

As you can see it contains the name of environment as dev so when you switched the environment , it will have a different environment based on the env name.

Purpose of api-params.json file is it remembers the state when you select the parameters in amplify add api. So when you do amplify update api it remembers your old state like lambda function and restrict api access based on settings you selected for auth and unauth api access as shown below:

"paths": [
        {
            "name": "/items",
            "lambdaFunction": "testlambda",
            "privacy": {
                "protected": true,
                "auth": [
                    "/POST",
                    "/GET",
                    "/PUT",
                    "/PATCH",
                    "/DELETE"
                ],
                "unauth": [
                    "/GET"
                ]
            }
        }
    ]

Amplify wont complain while deleting this file but when you do amplify update api, it wont remember the previous settings you selected while doing amplify update api as I mentioned above.

Let me know if this clarifies your questions?

[ksokol]

Hi @akshbhu

Thank you for your clarification.