Add IAM Authentication for Cloudant

[christiancompton]

Previously Cloudant, IBM's branded CouchDB service switched from using username/password authentication to using IAM apikey authentication. For the time being, Cloudant provides both sets of credentials when users select Legacy and IAM credentials as opposed to IAM credentials.

End of life support from Cloudant for the legacy credentials has not yet been announced, but we should support service instances that are IAM-only. https://console.bluemix.net/docs/services/Cloudant/guides/iam.html#ibm-cloud-identity-and-access-management-iam-

[Andrew-Lees11]

IAM apikey authentication works similar to OAuth2 where you have an API key, you go to a third party source with that key and get a temporary access_token. You then use that token in your "Authorization" header with the prefix "Bearer " for all your requests.

The OAuth flow would be hard coded to IBM Cloudant and so shouldn't be implemented within Kitura-CouchDB.

However generic use of the bearer authentication header could be supported. A user could then use a different repo to get their access token, provide that to Kitura-CouchDB and this would be attached to requests to allow a user to work with IAM authentication.

[christiancompton]

@ricellis How would you recommend proceeding in terms of supporting IAM-only credentials? I understand the goal to keep this library CouchDB specific and environment agnostic.

Cloudant is shown in a lot of our examples, and right now there is no way users can use IAM-only credentials in Swift. There is a distinct lack of a different repo to get their access token for IBM IAM - right now every SDK owner needs to add their own authentication methods to their SDKs - that is what the Watson SDK :( .

@Andrew-Lees11 I am not convinced that this would be easy for users to do themselves . Even if we did document what the user would need to do with a bearer authentication headers, it still seems like substantial configuration is needed. Is there anyway we can make this more consumable for Cloudant? I don't see why the OAtuh flow could not be configurable, perhaps defaulting to cloudant but easily overwritten.

Maybe a library could be shared with https://github.com/cloudant/swift-cloudant.

[Andrew-Lees11]

@christiancompton
I agree that we shouldn't expect users to implement this themselves. We should probably have another repo similar to Kitura-CredentialsGoogle that handles the Cloudant authentication and plugs into CouchDB.

I will try and prototype the bearer authentication on this repo and make a temporary repo for the IAM login to demonstrate how I think these should interact.

[ricellis]

The approach we've taken in our other Cloudant client libraries is to accept an IAM API key and exchange it with the IAM service for a token and then pass that token to Cloudant's iam_session endpoint to exchange for an auth cookie (although the Authorization header works equally well - we just save passing a bigger payload on every request by using the cookie).
We haven't added this IAM support to swift-cloudant yet - using the common IAM support of the core Watson SDKs is likely what we'll do going forwards.