Document awsconfiguration.json format and usage

[mutablealligator]

Is your feature request related to a problem? Please describe. https://github.com/aws-amplify/aws-sdk-ios/issues/1216

Describe the solution you'd like Documentation that explains the format of the awsconfiguration.json and usage on both iOS and Android

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

Additional context Add any other context or screenshots about the feature request here.

[Diegolotr99]

PLEASE , Document awsconfiguration.json format, usage, all possible regular key - values

[jsrofrimfram]

What would need to be added to awsconfiguration.json to enable uploading of logs to CloudWatch from iOS app?

[Ankish]

How do we add for different targets and schemes within it?

[mauerbac]

This is now documented here https://docs.amplify.aws/cli/usage/files#aws-exportsjs-file

[jules15]

@mauerbac No it's not! The link you gave is to "folder structure", and while it contains a section for amplifyconfiguration.json, it has no description of the contents. Please re-open this issue.

[mauerbac]

Sorry about that @jules15 . @brene @drochetti , we still need to provide a description of how that file operates. Is that something you can help with ?

[jules15]

@mauerbac If I already knew, why would I be using this forum to ask?

[mauerbac]

I was asking my colleagues @brene and @drochetti to help with that.

[renebrandel]

I'm curious to understand what level of detail is required here and why it's of importance.

Given that it's an auto-generated file, we usually don't recommend our customers to manually provide an amplifyconfiguration.json. Just curious to learn more about your scenario, so I can provide the best info here.

[jules15]

Let me explain my use case: Let's imagine you're an iOS/Android developer coming to a project where the AWS resources have already been provisioned for you. You may not even have any AWS credentials yourself. You are given the requisite information you need, identity pool ID, user pool ID, etc and told to use them in your iOS/Android app. In this case, running the amplify command-line seems unnecessary, since the resources are already provisioned. You just need a suitable amplifyconfiguration.json and awsconfiguration.json file. But these file formats aren't documented, so working out how to craft them is a real chore. Alternatively, you can set up the necessary config in code, but this isn't well documented either.

This use case was anticipated by Amazon when the client app is react-native (see: "Create or re-use existing backend" https://docs.amplify.aws/lib/auth/start/q/platform/js). But the AWS documentation for iOS/Android documentation doesn't have a corresponding section.

[renebrandel]

@jules15 - the corresponding sections on Android & iOS are actively worked on. ETA next week. Even in the JS version, we don't recommend you to create your own custom aws-exports.js file but rather populate the content within the function itself.

[jules15]

In the age of devops -- and heightened security -- Amplify's approach seems all wrong. We have specialists for provisioning AWS resources -- my company doesn't want developers to even have AWS accounts or to provision resources themselves. Quite the opposite. It's classic division-of-responsibility. If you're a one-person shop, it's different. Beefing up documentation for the "Create or re-use existing backend" use-case would certainly be welcome -- another approach would be to let a devops generate the necessary files from the AWS console/CLI for hand-off to developers. Just a thought.

[renebrandel]

@jules15 - we recognize the concern and we're actually looking into multiple ways to address your concerns. #1 is the documentation gap where the libraries can reference your existing resources. #2 where we'll enable you to import existing resources through the CLI https://github.com/aws-amplify/amplify-cli/issues/3977 especially for your scenario (auth), we'll then generate the config files through the imported reference.

[barrl]

I want to amplify (haha) the need for documenting this config file. Like @jules15, I want to define my system configuration in files and not by using a special tool--this is in keeping with the modern philosophy of "infrastructure is code."

And, I don't want to take a dependency in my workflow on a tool like amplify, which in fact requires npm, which I certainly don't want to take a dependency on. Just trying to install and setup npm has already given me some headaches. If I could simply figure out the basic format of the JSON file, I'd be leagues ahead.

[renebrandel]

Thanks @barrl @jules15 for this feedback! We're actively working on this now! #2097 is going to be our first crack at the problem. Can you provide some feedback on that approach?

[barrl]

@renebrandel That does look good. I'm glad to see an example of the JSON configuration. In my case, I wasn't using the Pinpoint service in particular, so for me it would be most useful if this kind of example were discoverable as part of the basic setup instructions, and showed an example of configuring the basic services like S3 and auth. But any example at all is a great help!

[LaszloDev]

In our case we define our resources manually by cloud formation template, and not use Amplify, thats why from my understanding I can't use Amplify for the awsconfiguration.json generation.

I did found in the documentation some parts that helped me and they referred to "Use existing AWS resources": Auth: https://docs.amplify.aws/lib/auth/existing-resources/q/platform/ios GraphQL: https://docs.amplify.aws/lib/graphqlapi/existing-resources/q/platform/ios

Update: The manual Auth part in the config is working with our Cognito UserPool and we could login, will test the GraphQL config with our AppSync backend next.

Also when on the AppSync AWS Console when selecting iOS at 'Integrate with your app' you will get your config ready to use. But it does have a different structure then the Amplify generated one.

Not sure if thats what you guys are talking about, but focussing more on the documentation of how to use Amplify just as a "frontend/client SDK" would be much appreciated, as not everyone uses it als to generate the backend resources.

[rromanchuk]

There really needs to be two distinct places for communication between aws-ios-sdk users and amplify users

ps Can you also please remove all references to Info.plist in the error messages when amplifyconfiguration.json is missing. I've been looking for a complete list of those plist keys for years and its just going to cause confusion https://github.com/aws-amplify/aws-sdk-ios/search?q=awsconfiguration.json+Info.plist&unscoped_q=awsconfiguration.json+Info.plist

https://www.google.com/search?q=awsconfiguration.json+Info.plis&oq=awsconfiguration.json+Info.plis&aqs=chrome..69i57j69i60l3.4618j0j1&sourceid=chrome&ie=UTF-8

pss these null set keys need to be documented

"IdentityManager": {
                    "Default": {}
                },

pss half my battle is just figuring out how to instantiate services and their dependencies, which just involves a lot of reading the source and trial and error. You can see how wild it

   func setupCognitoCredentials() {

        let devAuth = DeveloperAuthenticatedIdentityProvider(regionType: C.AWS.cognitoRegion.aws_regionTypeValue(), identityPoolId: C.AWS.cognitoPool, useEnhancedFlow: true, identityProviderManager: nil)

        let credentialsProvider = AWSCognitoCredentialsProvider(regionType: C.AWS.cognitoRegion.aws_regionTypeValue(), identityProvider: devAuth)

        // Set the default service configuration to the cognito pool region
        let configuration = AWSServiceConfiguration(region: C.AWS.cognitoRegion.aws_regionTypeValue(), credentialsProvider: credentialsProvider)
        AWSServiceManager.default().defaultServiceConfiguration = configuration

        let poolConfig = AWSCognitoIdentityUserPoolConfiguration(clientId: C.AWS.cognitoClientId, clientSecret: C.AWS.cognitoClientId, poolId: C.AWS.cognitoUSERPool)
        AWSCognitoIdentityUserPool.register(with: configuration, userPoolConfiguration: poolConfig, forKey: "UserPool")
        let mc = AWSMobileClient(regionType: C.AWS.cognitoRegion.aws_regionTypeValue(), identityProvider: devAuth)

        mc.initialize { (user, error) in
            guard let user = user, error == nil else {
                log.error(error!)
                return
            }
            log.debug("userState: \(user.rawValue)")
        }

        // Setup the service for challenge chats
        let chatsConfiguration = AWSServiceConfiguration(region: C.AWS.chatRegion.aws_regionTypeValue(), credentialsProvider: credentialsProvider)!
        let mapperConfig = AWSDynamoDBObjectMapperConfiguration()
        AWSDynamoDBObjectMapper.register(with: chatsConfiguration, objectMapperConfiguration: mapperConfig, forKey: C.AWS.chatTable)

        // Setup the services for direct messages
        let dmConfiguration = AWSServiceConfiguration(region: C.AWS.dmRegion.aws_regionTypeValue(), credentialsProvider: credentialsProvider)!
        AWSDynamoDBObjectMapper.register(with: dmConfiguration, objectMapperConfiguration: mapperConfig, forKey: C.AWS.dmTable)

        let ucConfiguration = AWSServiceConfiguration(region: C.AWS.userConversationTableRegion.aws_regionTypeValue(), credentialsProvider: credentialsProvider)!
        AWSDynamoDBObjectMapper.register(with: ucConfiguration, objectMapperConfiguration: mapperConfig, forKey: C.AWS.userConversationTable)

        // Setup transfer utility for profile uploads
        let profileTransferConf = AWSS3TransferUtilityConfiguration()
        profileTransferConf.isAccelerateModeEnabled = true
        profileTransferConf.retryLimit = 15
        profileTransferConf.bucket = C.AWS.profileBucket

        let profilePhotosConfig = AWSServiceConfiguration(region: C.AWS.profileRegion.aws_regionTypeValue(), credentialsProvider: credentialsProvider)
        AWSS3TransferUtility.register(with: profilePhotosConfig!, transferUtilityConfiguration: profileTransferConf, forKey: C.AWS.profileBucket)

        // Setup the service configuration

        // Setup transfer utility for checkin uploads
        let checkinsConfig = AWSServiceConfiguration(region: C.AWS.checkInRegion.aws_regionTypeValue(), credentialsProvider: credentialsProvider)
        let checkinConf = AWSS3TransferUtilityConfiguration()
        checkinConf.isAccelerateModeEnabled = true
        checkinConf.retryLimit = 15
        checkinConf.bucket = C.AWS.checkInBucket

        AWSS3TransferUtility.register(with: checkinsConfig!, transferUtilityConfiguration: checkinConf, forKey: C.AWS.checkInBucket)
        _ = UploadManager.shared
    }

[renebrandel]

hi folks - a quick update from our side on the original issue. Thank you all for reporting your use cases and scenarios. We've now added dedicated sections around how to use existing resources here: JS: https://docs.amplify.aws/lib/client-configuration/configuring-amplify-categories/q/platform/js Android: https://docs.amplify.aws/lib/project-setup/use-existing-resources/q/platform/android iOS: https://docs.amplify.aws/lib/project-setup/use-existing-resources/q/platform/ios

[renebrandel]

Those sites will link you to the right format of amplifyconfiguration.json for iOS & Android and/or aws-exports.js on JS.

[MohamadSoufan]

Hello,

Can we get this issue re-opened? The documents listed by @renebrandel propose a GREAT documentation for the JavaScript solution, however, for iOS, it is still very difficult to know the possible keys and values for the awsconfiguration.json and amplifyconfiguration.json files. I know those files are auto-generated by Amplify CLI. However, in my use case, I am using AWS CDK to provision resources and I just need to setup my iOS client app to consume those CDK resources, by manually filling out those 2 files!

my current work around is to generate a side Amplify project by Amplify CLI and mimic my CDK configuration and watch what the cli will generate in these files. It is a time consuming process

A great solution would be a Typescript file with 2 types AwsConfiguration and AmplifyConfiguration with some good comments explaining every property and commit that to this Github repo for example!

Thanks

[renebrandel]

hi @MohamadSoufan - we've also added a section in each category about their specific configuration:

Example: https://docs.amplify.aws/lib/auth/existing-resources/q/platform/android

LMK if this helps. It is currently not on our roadmap to use a typescript file for Android / iOS resource configurations.

[MohamadSoufan]

Hey @renebrandel - This definitely helps. I swear this documentation websites keep changing on me! I can't believe I didn't see this before However, is it part of the roadmap to add similar documentation for the awsconfiguration.json file since this document only addresses the amplifyconfiguration.json file?

Thanks

[n13]

hi @MohamadSoufan - we've also added a section in each category about their specific configuration:

Example: https://docs.amplify.aws/lib/auth/existing-resources/q/platform/android

LMK if this helps. It is currently not on our roadmap to use a typescript file for Android / iOS resource configurations.

It took me forever to find this - it would be really great to mention this right in the beginning of the "flutter tutorial"

I spent 3 days trying to make this work, I ended up creating an amplify backend we don't need, just to see the config file format - which didn't work either since creating an amplify backend and assorted setup steps are hours worth of work...

also the docs should be in the flutter section as well, as flutter, ios, and android are all the same (at least I hope so, otherwise flutter can't even work...). Flutter is currently missing this documentation completely. @renebrandel

The best solution would be to use the same file format for all platforms including JS - after all, this config file only describes the backend that will be used, and the backend is the same regardless of the client accessing it.

As it is we can probably live with a different one for our web app (JS) and flutter app. Just as long as it is well documented.

Amplify packages are needed to access our lambdas, but we don' thave an amplify backend so the documentation was extremely confusing.

[SomnathS09]

https://docs.amplify.aws/lib/auth/existing-resources/q/platform/android is now 404 - Not found, please update this so that we adding existing resources can get Idea about what to put in.

[n13]

https://docs.amplify.aws/lib/auth/existing-resources/q/platform/android is now 404 - Not found, please update this so that we adding existing resources can get Idea about what to put in.

I would simply recommend everyone to not use amplify.

Use another service that has good documentation and libraries on all platforms.

The amount of time I've wasted on this is embarrassing. It works now but I will switch to a different service.

[SomnathS09]

@n13 and all here is the updated link that shows inside amplifyconfiguration.json: https://docs.amplify.aws/lib/auth/getting-started/q/platform/android/#set-up-backend-resources

[aZrael936]

I have been spending insane amount of time to implement google federated Signin in my SwiftUI app. Why do you guys make it so difficult