Amazon Cognito MFA and SSO with PhenixID Authentication Services

Warning

Please note, this document is using the legacy authenticators - in order to use the new protocol agnostic authenticators, you need to apply relevant modifications to the configuration examples outlined in this article.

Summary

This document will guide you through the steps to enable multi-factor authentication and Single-Sign On for AWS Cognito.

System Requirements

PhenixID Authentication Server 2.8.1 or higher
Keystore file (p12) to sign tokens
Amazon Cognito administrator account
Reverse proxy http server (such as Apache) set up in front of PhenixID Authentication Services

Instruction

Overview

This document will guide you through the steps to enable multi-factor authentication and Single-Sign on for AWS Cognito.

PhenixID Server acting as OpenID Connect Provider (OP)

Setup PhenixID Authentication Services as an OpenIDConnect Provider (OP) with Authorization Code Flow. See this article OpenID Provider. Configure the token endpoint to return both id_token and access_token to the RP.
Add these claims to the openID scope.

"scope_claims" : [ {
  "name" : "openid",
  "claims" : [ {
    "name" : "given_name",
    "item_property_name": "givenName"
  },{
    "name" : "email",
    "item_property_name": "mail"
  },{
    "name" : "family_name",
    "item_property_name": "sn"
  },{
    "name" : "preferred_username",
    "item_property_name": "username"
  },
  {
    "name" : "name",
    "item_property_name": "fullName"
  }
   ]
}]

Open Configuration Manager
Click on Advanced->Modules
Fetch the tenant value you are using from the authentication-api module. Example:

Go to your http reverse proxy server configuration and add the tenant value as a request header when calls are made to the token and userinfo endpoints. Example for Apache httpd:

<Location /api/authentication/userinfo>
RequestHeader set tenant "myTenant"
</Location>

<Location /api/authentication/collectJWT>
RequestHeader set tenant "myTenant"
</Location>

Extract the public certificate from the keystore used to sign jwt token. Save it in PEM format.
Construct JWKS json string for the extracted certificate, using this guide.
Take the resulting jwks json string and save it to a textfile named "keys". Place the textfile on your http reverse proxy server in the folder /oidc/<tenant_name> to be publicly accessible from any web browser.

Configure the file to be content-type=application/json.

Example (tenant name is t1):

https://integration.phenixid.se/oidc/t1/keys
Fetch the kid value from the jwks json string.
Open Configuration Manager
Advanced->Pipes-><id of your token endpoint pipe>
Find GenerateJWTTokenValve
Add kid as a parameter to the valve. Example:
Click Stage Changes and Commit changes
Construct OIDC .well-known discovery json data using this guide. Pick the jwks url from step 9 and set it as jwks_uri.
Save the resulting json to a file named openid-configuration.
Place the file on the http reverse proxy server.

Place it in the folder oidc/<tenant>/.well-known to be publicly accessible from any web browser.

Configure the file to be content-type=application/json.

Example (tenant name is t1):

https://integration.phenixid.se/oidc/t1/.well-known/openid-configuration

Configure AWS Cognito

Login to AWS Cognito as an administrator (for your domain)
Add external Identity Provider of type “OIDC”
Add required information. Values can be found in the .well-known (see above). client_id and client_password must be given to you by the PhenixID administrator. Example:
Add attribute mapping to your newly added OIDC provider.

Table of Contents