iOS - AWS MobileHub sign in with developer authenticated provider

I'm trying to understand how to sign in with a developer authenticated identity using AWS mobilehub's iOS SDK as recently AWS changed this SDK and I cannot find any documentation on this. The sample app fails to shed any light on this.

I have a REST API to retrieve the cognito ID and Token but I'm not sure what to do with them once I have this.

AWS has the following different classes that futher complicate the issue:

AWSCredentialsProvider, AWSCognitoCredentialsProvider (No longer available in new SDK), AWSSignInProvider, AWSAbstractCognitoIdentityProvider (no longer available in new SDK)

There's now something called AWSAbstractCognitoIdentityProviderHelper..

These are handled by the AWSIdentityManager which is part of AWSMobileHubHelper.framework however AWSIdentityManager doesn't let you set the credentials provider so I don't understand how I am meant to interact with it in this regard.

Any tutorials, documentation, etc. would be much appreciated

Your question exposes certain terminology problems:

• When you say developer I am not sure you mean the same thing that AWS means.
  • AWS use the term "developer" (as in "developer identities") to mean
    externally maintained pools as opposed to privately maintained. AWS has it's own product (Cognito User Pools) which you can privately maintain as an AWS service. AWS does not consider user pools to be a developer identity provider (but in practice, it is simply a fully implement renamed version of a developer identity provider).
• Regarding maintaining tokens
  • The iOS SDK maintains the tokens you need for access to AWSServices. You should use the Mobile Hub, (it has a much nicer object and interface design than the SDK). But regardless of whether you use mobile-hub-helper or the SDK directly, you never have to manage a token (the SDK does it for you). The documentation (almost cruelly) obscures this fact (and yes, it is lagging behind the SDK).

3 ways to use Cognito

You must understand that there are 3 different interface apis.

1. COGNITO API and up to date API documentation (the RESTFUL interaction)
2. iOS SDK and out of date SDK documentation (the SDK is not RESTFUL, it has ton's of state).
3. Mobile Hub Helper (MHH) SDK - MHH is documented (a little) by the hub, and pretty well in the .h files used to produce appledoc documentation.

With respect to Identity and SignIn/Authentication (the topics of this question) aws-mobile-hub-helper (hereafter MHH) has an elegant design and works well. I would recommend anyone using Cognito start with the Mobile Hub site (or at least with aws-mobile-hub-helper). The MHH is basically a wrapper to the SDK and helps clarify and separate the issues of persistent federated identity and credentials/authorization for AWS services from issues of Identity, authentication and attributes/claims for that Identity.

• Identity in MHH has only 1 class AWSIdentityManager.
• SignIn in MHH has one protocol, AWSSignInProvider, and two implementations of that protocol (plus one I made):
  1. AWSGoogleSignInProvider: OpenID-Connect/OAuth implementation of AWSSignInProvider for Google+
  2. AWSFacebookSignInProvider: An OAuth/Proprietary implementation of AWSSignInProvider for Facebook
  3. AWSCUPIdPSignInProvider: OpenID-Connect/OAuth implementation of AWSSignInProvider for Amazon AWS Cognito Your User Pools service (this is available on a forked repository)

The mobile-hub-helper is documented only in the .h files. These can be processed into documentation by appledocs, and the comments there are pretty good if you had an overview of the class structure (which does not exist but I will attempt to provide).

SDK Authentication Flow

The authentication flow documented by AWS, is an oversimplification and does not aid in understanding how the authentication is accomplished using the SDK and Mobile Hub Helper. The following diagrams attempt to convey how identity authentication(login) and authorization(credentials) to use AWS Services (like S3, and DynamoDB) works.

Understanding Cognito

• Understanding Cognito is initially confusing for a variety of
  reasons: Authentication, Authorization and Identity Management in a
  distributed system is complex. There are many parties with different roles and elaborate prescribed interactions with keys, tokens and
  signatures. The end user, the relying party (RP) the Identity
  Provider (IdP) the resource being used (RS) and the resource owner
  (RO). This terminology is used by the OpenId Connect and OAuth2.0
  standards documents. For reasons that will become clear, this
  terminology is not consistently used by AWS. But they concepts and
  the entities are all there when using Cognito.
  • There are some good OpenID connect overviews online (ex: http://nordicapis.com/api-security-oauth-openid-connect-depth/ ) and a review of those will help.
• Cognito allows non-OpenID Connect Identity Providers, this is an advantage (ex: allowing the OAuth/Proprietary Facebook identity API) but it also means that Cognito is playing a “federating”
  role. This role is outside the scope of OpenID Connect standards
  documents (Update 1: Lately I have begun to wonder whether the Cognito Credentials Provider is really the RP (Relying Party) which then issues credentials for AWS Services. But the main point here is that OpenId Connect does not prescribe the way that Identities from different IdP's could be combined.), Amazon are essentially inventing the role, and in doing so have had some naming challenges.

Cognito Naming

• Cognito is a single name created by AWS to cover many functionalities and roles.

  1. There is the RESTFUL web API to Cognito, but there is also the
     Cognito SDK. The SDK calls and the API messages are not named the
     same, and SDK calls make multiple and conditional API calls.
  2. Cognito can federate identity providers. It can persist and
     association betwene authenticated users from different identity
     providers (So it can remember your google+ and your facebook
     identities and associated them with a single Cognito identityId.)
  3. Cognito can provide persistent identityId (which, if anonymous, follow an iOS device using keychain data) for users as well as authenticated users. These are stored in what is called an Identity Pool (NOT to be confused with a User Pool). Your app receives the same identityId for a user on different devices for authenticated users. Unauthenticated (Guest) identityId’s follow a single device.
  4. Cognito can store (known as “Sync”) state data IdentityId’s (on the AWS server), which works for authenticated and unauthenticated users.
  5. Cognito has a AWSCredentialsProvider (a source for AWS Credentials for using AWS Services (Cognito but also S3, DynamoDB, etc)
  6. Cognito can create an OpenID Connect server called a User Pool, which can be used by Cognito Identity to Authenticate users.
  7. Cognito is new, but AWS Federated Identities and AWS Identity Management and AWS Credentials are not, so there are lots of classes with overlapping responsibility. And the naming conventions are confusing (consider the name AWSCognitoIdentityCognitoIdentityProvider! ). The use of the “cognito” brand name for userpools, really is a nightmare. An AWSCognitoIdentity thing is Cognito Federated Identity CFI but an AWSCognitoIdentityProvider thing is a thing like userpools an authentication provider also called an identity provider.

• SDK class names are confusing. But with few exceptions, classes starting with AWSCognitoIdentity (but NOT AWSCognitoIdentityProvider) are about the credentialsProvider/IdentityProvider, classes starting with AWSCognitoIdentityProvider relate to Oauth/Open Id Connect providers and other distributed identity providers (facebook).

Glossary/Synonyms

These terms are used loosely throughout the AWS documentation and marketing material. This is an attempt to sort out the terminology by grouping terms that are used interchangeably by AWS.

• Identity provider, authentication provider, Login provider, federated identity provider(s)
• Amazon Cognito, Cognito credentials provider, cognito identity (all seem to refer to the same class/process)
• Cognito user pool, Cognito Your User Pools, user pool. CUP is an identity provider aka authentication provider
• Cognito identity pool, pool, cognito pool, identity pool. Occasionally called an identity provider (which seems incorrect) but it is never called an authentication provider
• Developer identity, developer authenticated identities, developer provider, developer identity provider, all used to refer to private external Identity Providers.
• Identity is a term often misused in Cognito documentation. It is important to understand there are two different kinds of identity that Cognito manages. identityId (which should be in lower case) is the persistent unique name that Cognito associates with credentials and uses to federate different Identity providers, and Identity (upper case) which is an authenticated identifier from an Identity Provider.
• identityId Identity ID, id (as in get-id), identity, identityId
• Identity
• Federation means multiple things.
• Web identity federation - an earlier way of federating identity at AWS
• Cognito federated identities
• BYOI (bring your own idenity) where a user may use google, facebook or another identity provider (perhaps a developer provided identity) usually through OpenId-Connect.

IdentityId Behaviors

• An identity id looks something like this: us-east-1:982396fs-841e-3cdd-9r43-e7ac41bhbcb28
• The identityId is maintained on an iOS device in a keychain entry. For an unauthenticated IdentityId it remains the same until you clear the keychain (This can be done in simulator by Simulator -> Reset Content and Settings…). At that point that IdentityId is abandoned. It is not disabled, it is just never used again.

• When the user authenticates, authenticating disables the unauthenticated identityId (the identityId will be permanently marked with DISABLED in the Logins array in the identityPool entry. You can see this in the Cognito console.) that is currently on the device. There is one exception: If this is the first time the authentication takes place for this Identity then the unauthenticated identityId is not abandoned but is associated with the Identity and used as the authenticated identityID going forward.

• Merging multiple Identities (meaning usernames not IdentityId’s) from different Identity providers abandons (disables) one of the identityId's, and associates both Identities with the other identityId. Disabled Id’s get created whenever this happens. These abandoned identityId's are marked with DISABLED in the Logins array in the cognito identityPool.

• In practice this process creates a reasonable use of unique identityIds with disabled ones only getting created when a user authenticates on a new device (It can be bothersome in testing as it creates a barrage of disabled and unused identityId’s as the tester logs out and in multiple times with multiple id’s). But in practice the common use case would not create this barrage of disabled identityIds. A user would:

• Connect – get an unauthenticated id - authenticate – and use the same ID. No abandoned id is created.

• Connect on another device – here he/she would momentarily get a new unauthenticated id – and when he/she authenticated and got the identityId for his/her identity, that unauthenticated id would be disabled and abandoned.
• Each merging of identities from two identity providers would also create a disabled and abandoned identityId.

AWSIdentityProviderManager

• AWSIdentityProviderManager is the protocol that manages federated AWSIdentityProviders

• In mobile-hub-helper AWSIdentityManager is the AWSIdentityProviderManager

  • All it needs to do is return to credentials provider a logins dictionary, with providers name and ID Token. AWSIdentityManager only returns the providername and token for a single identity provider. It simply gets the name and token from the AWSSignInProvider and returns. (There is a fork with a modification that adds the ability to return all of the current logged in providers in the logins dictionary.)

  • As modified AWSIdentityManager maintains an NSDictionary called cachedLogins. Each new login adds an login (an identity provider name and id token) to the cache. Then logins always returns the whole loginCache. This is what supports identity merging.

• When the credentials provider calls it’s associated AWSIdentityProviderManager logins method, and finds a list of logins instead of just one it will merge the identityId's for those logins in it’s database and disable the identityId of one of them. How does it know which ID goes with which login? The ID Token contains an encoded decryptable (paste the token into https://jwt.io to see for yourself) set of claims, one of which is the identity (ex: username)

• Note: Even though you have an identityId that has multiple related logins, in Mobile Hub Helper you are only ever authenticated by one AWSSignInProvider. Credentials get associated with the merged identityId, but in mobile-hub-helper access to that identityId is always via the active AWSSignInProvider (authentication provider) even if you are logged with multiple identity providers. Your app can keep track of all of the AWSSignInProviders and access them independently of AWSIdentityManager, but from AWSIdentityManagers point of view you are logged in with one of them. In practice this has little impact (until you try to get "claims" like imageURL from different providers for instance).

About Merging Identities

• Currently the AWSIdentityManager does not support identity merging. I have a forked repository https://github.com/BruceBuckland/aws-mobilehub-helper-ios from the github repository that adds that capability, and adds a Cognito User Pools Identity Provider AWSSignInProvider (AWSCUPIdPSignInProvider.swift).

• You can probably think of all sorts of gotcha’s when merging identities.

• What if I try to merge two identities from the same provider (wouldn’t the dictionary keys be the same?)

• What if I try to merge two identities, each of which has a different identity from the same provider associated with it (and again they would create two entities with the same keys).

• Cognito manages this beautifully and rejects attempts to merge
  identites that cannot be merged. The rejection happens at login time (when you would try get credentials, the credentials provider will reject the logins dictionary that contains an un-mergeable identityId)

Where Cognito buries its data

• Cognito stores a keychain on the device that contains the last identityId that was used. This is used by the credentialsProvider/identityProvider object upon a call to credentialsProvider.credentials (iOS SDK name) to re-use an existing identity (for example unauthenticated) and avoid creating unused identities unless the user truly is not going to log in or resume.

• Mobile-Hub-Helper’s AWSSignInProvider’s and AWSIdentityManager store an indication of an open session state in NSUserDefaults. These are used to re-start the session if the app is terminated and restarted.

• AWSSignInProvider’s store NSUserDefaults too, and sometimes in the iOS Keychain, for their own internal purposes (like retaining easy persistent access to a username or imageURL or token)