▪ Amazon Cognito MFA Application

Amazon Cognito MFA Application is a type of application you create in Biopass admin panel in order to link it to an Amazon Cognito user pool, so that after your user entered their Cognito username & password, they are directed to Biopass to authenticate with their face or other acceptable authenticators.

Amazon Cognito is a fully managed service provided by Amazon Web Services (AWS) that enables developers to add user sign-up, sign-in, and access control to their web and mobile applications. Your organisation may have already used Amazon Cognito for their users. You still can have values Biopass offers to add more security to the authentication of your users. You can benefit from advanced multi-factor authentication service, policy and access control offered by Biopass. To do so, you should first create an Amazon Cognito MFA Application, and link it to your user pool in Amazon Cognito.

As stated above, users after entering their Cognito username and password are directed to Biopass to authenticate with their face or other acceptable authenticators.

Login experience after adding Biopass security to your username-password login

1- Settings tab

Each Amazon Cognito MFA Application has two boxes of Settings; "Integration information" & "Allowed callback URLs".

1-1- "Integration information" box in Amazon Cognito MFA applications

In this box, the information you need to integrate this application with AWS Cognito is shown.

"Client ID"

This is the ID of this application in Biopass

"Issuer"

This link refers to the entity that issues and generates a security token. It is responsible for ensuring that the user's credentials are valid and that the access token can be trusted. AWS Cognito uses the Issuer information to verify the token's authenticity and grant access to protected resources.

"Client authentication" checkbox

Client authentication is the process by which the client application proves its identity to Biopass server before it is granted access to the protected resources on behalf of the resource owner.

Biopass defines several methods for client authentication, including:

Client ID and Secret: The client provides its client ID and a secret to Biopass, which is used to authenticate the client. This method is commonly used for web applications.

Public Key: The client presents its public key to Biopass as proof of identity. This method is commonly used for mobile and desktop applications.

JSON Web Token (JWT): The client presents a JWT to Biopass as proof of identity. This method is commonly used for APIs.

Client authentication is important for security reasons, as it ensures that only trusted clients are granted access to the protected resources. It also allows the authorization server to enforce access control policies and audit access to the resources.

"Client secret" field & "Rotate secret" button

As stated above, one of the secure methods of "Client authentication" is using Client ID and "Client secret". When "Client authentication" checkbox is ticked, "Client secret" field will appear. In case, you want to change the secret for security reasons, you can use "Rotate secret" button. After changing the secret you should update the stack created in AWS Cognito. You have two ways for doing it:

"Updating client secret in the AWS Cognito user pool using Command Line (CL)"

First installing the latest version of the AWS CLI on your machine. See the guide here.

Then find the stack in the AWS Cognito cloud formation. (Go to cloud formation and then type the client ID). When you find the stack, click on it and go to parameter tab and see previous secret there. (The secret name is written on top of the page or on stack info tab)

Afterwards type the following command (aws cloudformation update-stack command) in the command prompt:

aws cloud formation update-stack command

aws cloudformation update-stack --stack-name YourStackName--use-previous-template --parameters ParameterKey=ClientId,ParameterValue=YourClientId ParameterKey=Issuer,ParameterValue=YourClientIssuer ParameterKey=ClientSecret,ParameterValue=NewSecret ParameterKey=Region,ParameterValue=TheRegionLambdaFunction --capabilities CAPABILITY_NAMED_IAM

YourStackName should be replaced with the name of stack you found in the previous step
YourClientId should be replaced with the Client ID in the "Integration information" box
YourClientIssuer should be replaced with the issuer in the "Integration information" box
NewSecret should be replaced with the new secret generated in the "Integration information" box
TheRegionLambdaFunction should be replaced with the region in the "Integration information" box
Note: You can check the parameters of the stack and see that it is updated.

"Updating client secret in the AWS Cognito user pool using graphical interface (GUI)"

There are two ways to integrate However, integration is been automated for you when you want to integrate Amazon Cognito with Biopass, you go to Cognito integration tab and use "Deploy" button. See more details here

On the AWS page, you see the settings prepopulated in the fields. You can check and or rotate secret if needed. Bear in mind, in case you use "Rotate secret" and create a new secret, you should update your deployment in AWS.

1-2-"Allowed callback URLs" box in Amazon Cognito MFA applications

This box should contain all "Allowed callback URLs" set for applications in AWS Cognito user pool. When Biopass verifies user, it should redirect the user to the requested application URL. This is done only when the redirect URL is in the list of "Allowed callback URLs".

📘

Allowed callback URLs

An "Allowed Callback URL" is a setting used in web applications that implement OAuth authentication, which allows users to grant third-party applications access to their accounts on a given service without providing their login credentials.

When a user grants access to a third-party application, the OAuth protocol will redirect the user to the application's "callback URL" after the user has authenticated with the service. The "Allowed Callback URL" setting specifies which URLs the service should accept as valid callback URLs for a given application.

This setting is important for security reasons, as it helps to prevent unauthorized access to user accounts. By limiting the allowed callback URLs to only those that belong to trusted applications, the service can ensure that users are only granting access to their accounts to legitimate and trusted third-party applications.

In short, the "Allowed Callback URL" is a configuration option that helps ensure that the OAuth authentication process is secure and that users can trust the third-party applications they grant access to.

2-Groups

2-1- Registering Cognito users automatically in Biopass

When you create an Amazon Cognito Application, you should assign a group of users to this application, although this group may be empty.
When users enter their username and password, they are automatically registered in Biopass admin panel, added to the group, and are sent to self-enrolment to enrol their authenticators.
Afterwards, they should authenticate with their enrolled authenticator to log in. This happens only the first time users use Biopass. Afterwards they are automatically sent to Biopass universal login to use

Login experiennce for the first time after adding Biopass (Registering user in Biopass)

3-Cognito Integration tab

Under this tab, admin can integrate their Amazon Cognito user pool with Biopass or view previous integrations. There are two boxes under this tab:

3-1- Deployment box

In this box, you can see a short step by step guide on how to integrate Biopass with AWS Cognito. Using the button you are guided on deploying necessary functions in AWS to work with Biopass. To see a full guide about it please refer to this page.

🚧

Limitation on AWS Cognito user pools

Please be aware that unfortunately, in this version of Biopass, we do not support Cognito user pools which can use phone number as username. Likewise, Biopass does not support integrating with Cognito user pools which have case sensetive usernames.

3-2- Previous deployments box

In this box, you can see previous deployments you had on your AWS Cognito accounts. You may have integrated this application with more than one account and in each account more than one user pool. Each row of this box shows the ID of AWS Account, the date/time deployment was done, and also the user pool which at least a user has tried to log in from.

MFA Cognito trouble shooting

Rotate secret

Delete and re deploy