Cognito includes user pool and identity pool. User pool is used to verify users and manage users' data. Identity pool is used to allocate identity to verified users or guest to access other aws services and manage identities.
create cognito idp object
To access user pool, we need to create a cognito idp object.
To verify users and access the user's data, access key id and secret key is not required. The web apis which is used to verify users and access the user's data are protected by client id and client secret, another form of credentials and use access token to identity users when we access the user's data. It includes, Sign Up, Confirm Sign Up, Initiate Auth, Respond To Auth Challenge, Change Password, Forgot Password, Confirm Forgot Password, Get User, Set User Settings, Update User Attributes, Get User Attribute Verification Code, Verify User Attribute, Delete User, Delete User Attributes, Resend Confirmation Code. Client id will be generated when we initial an app client in cognito user pool and client secret will be generated if we enable "Generate a client secret" option. Using a client secret is recommended.
To use client secret, we use compute secret hash node to calculate the secret hash with client id, client secret and username and provide the secret hash to the request.
Access key id and secret key are required if we want to use the cognito idp object to manage users or user pools. We can get access key id and secret key from pre-created IAM user or get allocated from cognito identity pool.
Enable "Access key - Programmatic access" when we create the IAM user to generate access key id and secret key for the IAM user. The access key id and secret key will be generated when we finish creating the IAM user. We can copy it or download it as a CSV file.
verify user
User account can be used to identity and track a valid player in our game. To make sure the player owns the user account, we have to verify the users.
sign up
Sign up is used to create a user account. We need to enable "Self-registraction" when we create the user pool or change it after the user pool is created.
We need to provide client id, secret hash(if client secret is generated for the app client in user pool), username, password and required user attributes.
This node will send password in plain text, please make sure the user is using trust network.
We can set the required user attributes when we create the user pool. It's not changeable after the user pool is created.
If we enabled "Email only" or "SMS only" in "User account recovery" when we create the user pool, "email" or "phone_number" will be automatically set as required user attribute.
We can also add custom user attributes when we are creating the user pool or after we create the user pool.
After a user account is signed up, a verification message will be sent via email or SMS. We can set which one we prefer when we are creating the user pool or after we create the user pool.
After the player receives the verification message, we need to call confirm sign up with client id, secret hash(if client secret is generated for the app client in user pool), username, confirmation code to finish the sign up process.
If the user didn't receive the confirmation code message, we can call resend confirmation code with client id, secret hash(if client secret is generated for the app client in user pool), username.
If there is no custom triggers set for sign up process, sign up process will be ended after confirm sign up returns.
forgot password
Users may forget their password when they login our game. We can use forgot password node with client id, secret hash(if client secret is generated for the app client in user pool), username to help the user reset his password.
After finish calling forgot password node, the user will receive a message with a confirmation code. Then, we need to call confirm forgot password with client id, secret hash(if client secret is generated for the app client in user pool), username, confirmation code, new password to finish reseting the password.
If the user didn't receive the confirmation code message, we can call resend confirmation code with client id, secret hash(if client secret is generated for the app client in user pool), username as same as sign up.
This node will send password in plain text as same as sign up, please make sure the user is using trust network.
auth flow
An auth flow is a flow to get tokens which will represent the user who is playing the game is verified. In aws cognito, the tokens are access token which can be used to access the user's password, attributes, device info and so on, id token which can be use to generate access key id and secret key from cognito identity pool, refresh token which can be used to refresh above two tokens.
plain text login
Plain text login is not recommended to be used as an option from client. So, let's ignore it.
srp login
Srp, secure remote password protocol, is a protocol which is used to prevent sending plain text password into public network. It's recommended to be used in all public app. We can enable srp login by adding "ALLOW_USER_SRP_AUTH" in authentication flows when or after we create the user pool.
Srp helper is an object which will help us calculate all values during srp login. We need to create it before we start an srp login process. Srp helper will be used during the whole login process, so, we'd better save it as a variable during the login.
SRP_A is generated from a random big number in client to tell server how to decrypt the encrypted password. So, each time we start a new login process, we should compute a new SRP_A.
To start an srp login process, we need to call initiate auth with USER_SRP_AUTH as auth flow, auth parameters, client id.
In auth parameters, we need to provide USERNAME, SRP_A, DEVICE_KEY(if we enabled device tracking), SECRET_HASH(if client secret is generated for the app client in user pool).
Initiate Auth will response a challenge request with a "Challenge Name". We need to call "Respond to Auth Challenge" to react the challenge request base on the "Challenge Name" we get, unless we get a "Not Set" in "Challenge Name". Challenge request will be requested with session, challenge parameters. After a success respond to auth challenge, there might be another challenge request or more one after another. Once the auth flow is finished, it will return a challenge with "Not Set" in "Challenge Name" and authentication result.
In "user srp auth" flow, a "Password Verifier" challenge will be requested with "SRP_B", "SALT", "SECRET_BLOCK", "USER_ID_FOR_SRP" in challenge parameters. "USER_ID_FOR_SRP" should be used as username during the auth flow from here. We need to compute a password signature with these values to response the auth challenge. The group key should be the second part of the user pool id split by "_", the key should be the username and the password should be the password of the user.
To response the password verifier challenge, we need to call respond to auth challenge node with "Password Verifier" as challenge name, session, client id, challenge responses.
In challenge responses, we need to provide PASSWORD_CLAIM_SIGNATURE(the result of compute password claim signature node), PASSWORD_CLAIM_SECRET_BLOCK(the secret block from the last initiate auth or respond to auth challenge), TIMESTAMP(the Timestamp of compute password claim signature node), USERNAME, DEVICE_KEY(if we enabled device tracking), SECRET_HASH(if client secret is generated for the app client in user pool).
After a successful login, authentication result will be returned in the last initial auth or respond to auth challenge node with access token, refresh token, id token, new device metadata(if we enabled device tracking and login from a new device). We can save the refresh token with device metadata and device random password in a save game slot to skip this login process in the future.
refresh token login
Users don't want to login again every time he get back to the game. Refresh token can help them skip annoying, repeatedly and unnecessary login process.
Refresh token auth is enabled by default when we create the user pool. We can also set expiration for refresh token, access token and id token. When access token or id token is expired, we can use refresh token to refresh it. So, refresh token expiration should be longer than access token and id token.
We need to call initiate auth with REFRESH_TOKEN_AUTH as auth flow, auth parameters, client id to start refresh token login process.
In auth parameters, we need to provide REFRESH_TOKEN, SECRET_HASH(if client secret is generated for the app client in user pool), DEVICE_KEY(if we enabled device tracking).
After a successful login, authentication result will be returned in the last initial auth or respond to auth challenge node with access token, id token. Refresh token and new device metadata won't be included.
sign out
There are two ways to sign out, revoke token and global sign out.
revoke token
Revoke token is used to disable a refresh token. After calling revoke token, the refresh token is invalid and can't be used in refresh token auth. We can call revoke token with refresh token, client id, client secret(if client secret is generated for the app client in user pool).
global sign out
If we want to completely sign out the user and disable all his tokens and client objects created with the access token, we can call global sign out with access token.
change password
Users may want to change his password after login. We can use change password node with previous password, proposed password, access token to help the user change his password.
Compare with forgot password, change password can only be done after we get access token and the user need to remember his previous password. Change password will send password in plain text as same as sign up and forget password, please make sure the user is changing his password in trust network.
get user
After login, we can call get user with access token to get the user's username, attributes and his mfa settings.
manage user
We can store users' attributes, custom attributes and device info, mfa preference in cognito. To manage these datas in cognito, we need to use cognito idp object with access key id and secret key credentials with access token.
device tracking
Device tracking is used to make sure the player is login from a trusted device and prevent refresh token is used in untrusted device. It can be enabled after we create the user pool.
After device tracking is enabled, new device metadata will be returned after the first time success login. It contains device key and group device key.
After we getting the device key and device group key, we need to generate a random password for it and a password verifier to confirm the device.
Device key, device group key and the random password will represent the device. So, we need to save the device key, device group key and random password from compute password verifier locally to login in the future. We can just save it with unreal save game function.
After we generate the random password for the device, we need to call confirm device with access token, device key, device secret verifier config with return value and salt from compute password verifier node as password verifier and salt, a device name which can be specified by the user to help him remember the device.
After confirm the device, we need to call update device status with access key, device key, remembered as device remembered status to remember the device. We can also use this node to forget a device by changing the remembered in device remembered status to not remembered.
After remember the device, if we login with known device key, a device srp auth challenge will be requested with session. To respond device srp auth challenge, we need to create srp helper as srp login.
Then, compute srp a as well.
After that, we need to call respond to auth challenge with "Device SRP Auth" as challenge name, session, client id, challenge responses.
In challenge responses, we need to provide USERNAME, SRP_A, DEVICE_KEY, SECRET_HASH(if client secret is generated for the app client in user pool).
After device srp auth challenge, device password verifier challenge will be requested with session, srp b, salt, secret block. To respond device password verifier challenge, we need to call compute password claim signature similar with srp login, but with device group key as group key, device key as key and device password as password.
To response the device password verifier challenge, we need to call respond to auth challenge node with "Device Password Verified" as challenge name, session, client id, challenge responses which is similar with srp login as well.
In challenge responses, we need to provide PASSWORD_CLAIM_SIGNATURE(the result of compute password claim signature node), PASSWORD_CLAIM_SECRET_BLOCK(the secret block from the last initiate auth or respond to auth challenge), TIMESTAMP(the Timestamp of compute password claim signature node), USERNAME, DEVICE_KEY, SECRET_HASH(if client secret is generated for the app client in user pool) as same as srp login.
After enabled device tracking, refresh token will be bound with device key. If you don't provide device key in refresh token login, the login process will be failed.
With access token, device tracking and cognito idp object with access key id and secret key credentials, we can also use forget device node with device key to forget a device with device key, use get device node with device key to get device info including device key, device attributes, when it's created, when it's last modified and when it's last used to login, and use list devices to list all devices the user had used with their infos.
mfa
Mfa, also known as multi-factor authentication, is another protection for user accounts. User's password may be stolen by peeping at the screen. But mfa will provide a mfa code, a random number, which will be changed each time we requested or every 30 seconds. There are two mfa methods, sms message and authenticator apps.
We can setup mfa when we create the user pool or after we create the user pool.
sms message mfa
Sms message mfa will change the mfa code every time we request it. (It will charge you sms fee, which will be 0.00581 usd at least. So, it's not recommended, let's ignore it.)
authenticator apps mfa
Authenticator apps mfa will change mfa code every 30 seconds. Authenticator apps is a type of apps, for example Google Authenticator.
To help users set up authenticator apps mfa, we need to call associate software token with access token.
To help users set up authenticator apps mfa, we need to call associate software token with access token. Or if you forced required mfa, the first time a new user login will return a mfa setup, then we need to call associate software token with session from the last initiate auth or respond to auth challenge.
After that, we need to construct a otpauth url with a brief name, issuer, username, secret code(from associate software token result). In form of "otpauth://totp/<brief name>:<username>?secret=<secret code>&issuer=<issuer>". The brief name is used to help the user what's this mfa code, the issuer is used to tell user who gave you this mfa code. They are just strings which is used to help user remember. So, you can enter whatever you like or you can just use same string for brief name and issuer.
Then, we need to transmit the otpauth url to user's authenticator app. We can ask the user to enter it manually, but we prefer a convenient way. So, we can use qr code. There are a lot of qr code generate sites and display it in web browser in user widget. We will use one of them here. The others should be similar.
After the user scan the qr code we display in a authenticator app, the authenticator app will generate the first mfa code. Then we call verifier software token with access token and the mfa code from the authenticator app. Or if we forced required mfa, the first time a new user login will return a mfa setup, then we need to call associate software token with session from the last initiate auth or respond to auth challenge and the mfa code from the authenticator app.
If we forced required mfa, we need to respond the mfa setup auth challenge with "mfa setup" as challenge name, session(from verify software token's result), client id, challenge responses.
In challenge responses, we need to provide username, DEVICE_KEY(if we enabled device tracking), SECRET_HASH(if client secret is generated for the app client in user pool).
We can call set user mfa preference with access token to set which mfa method the user prefer.
After setting up authenticator app mfa for the user, every time the user login, there will be a software token mfa challenge requested. To response the password verifier challenge, we need to call respond to auth challenge node with "software token mfa" as challenge name, session, client id, challenge responses.
In challenge responses, we need to provide SOFTWARE_TOKEN_MFA_CODE(from authenticator app), USERNAME, DEVICE_KEY(if we enabled device tracking), SECRET_HASH(if client secret is generated for the app client in user pool).
user attributes
User attributes are attributes saving in cognito users' account to help cognito works, for example, phone number and email is required if you want to send confirmation code to users, and you can add custom attributes too.
We can set which attributes are required for sign up request when you create the user pool.
We can create custom attribute when you create the user pool.
We can set attribute read and write permissions when we create the user pool and after we create the user pool.
To modify the user attributes of the user, we can call update user attributes with user attributes, access token.
We can setup attribute verification if we don't want users change their attributes by mistake when we create the user pool and after we create the user pool.
If we have setup attribute verification, users will get a verification message with the verification code for all attributes he changed. We need to call verify user attribute with access token, attribute name, code for all attributes.
manage user pool
It's not recommended to manage our user pool in the game. So, let's ignore it.
create cognito identity object
To access identity pool, we need to create a cognito identity object.
To allocate identity for users, access key id and secret key is not required. The web apis which is used to allocate identity are not protected by any kind of credentials and id token to identity users when we allocate identity. So, we need to use these nodes carefully. It includes, Get Credentials For Identity, Get Id, Get OpenId Token, Unlink Identity.
We can set what unauthenticated users can do and what authenticated users can do when we create the identity pool and after we create the identity pool by setting IAM role for them. Then we can edit the policy of the IAM role to adjust what they can do.
allocate identity
After login, id token will be provided. We can use get id node with identity pool id, logins to get identity from id token.
We can get identity pool id after we create the identity pool.
In Logins, we need to specify the provider with id token as a pair.
We can specify 0 pair to get id as a guest if we have enabled "Enable access to unauthenticated identities" when we create the identity pool and after we create the identity pool. We can also specify multiple pairs to get id if we have set up multiple authentication providers.
Each provider has their unique provider name.
For cognito user pool, the provider name should be in form of "cognito-idp.<region>.amazonaws.com/<user pool id>".
We will get identity id from get id result.
We can unlink a provider from the identity by calling unlink identity with the identity id(from get id result), logins(as same as get id), logins to remove.
We can call get credentials for identity with the identity id from the get id result, logins as same as get id to generate access key id, secret key, session token with expiration for other aws services.
manage identity pool
It's not recommended to manage our identity pool in the game. So, let's ignore it.
