Cognito_with_Github_identity_provider.md

Cognito with Github

ref: github-cognito-openid-wrapper

Why does Cognito not support federation with OAuth? Because OAuth provides no standard way of requesting user identity data. (see the background section for more details).

So in order to use Github as an Identity provider, we introduce a wrapper to make Github OAuth API comply with OIDC User Pool IdP authentication flow used by Cognito.

The OIDC User Pool required four endpoints, which are:

• Authorization - used to start the authorisation process (spec) -> we will use Github default endpoint
• Token - used to exchange an authorisation code for an access and ID token (spec) -> Wrap this
• UserInfo - used to exchange an access token for information about the user (spec) -> Wrap this
• jwks - used to describe the keys used to sign ID tokens (implied by spec) -> This will be left as dummy endpoint.

1: Setup

We will need to:

• Create a Cognito User Pool (instructions).
• Configure App Integration for your User Pool (instructions). Note down the domain name.
• Create a GitHub OAuth App (instructions, with the following settings:
  • Authorization callback URL: https://<Your Cognito Domain>/oauth2/idpresponse
  • Note down the Client ID and secret

(If you use GitHub Enterprise, you need the API & Login URL. This is usually https://<GitHub Enterprise Host>/api/v3 and https://<GitHub Enterprise Host>, modify those value at config.py)

2: Deploy lambda and API Gateway

Source code for wrapper of /token and /userinfo lambda function

Detail about lambda deployment and API Gateway config can be found in de_lambda_auth_funcs.py

3: Finalise Cognito configuration

• Configure the OIDC integration in AWS console for Cognito (described below, but following these instructions). The following settings are required:
  • Client ID: The GitHub Client ID above
  • Authorize scope: openid read:user user:email
  • Issuer: https://<Your API Gateway DNS name>/${Stage_Name}
  • If you have deployed the web app: Run discovery (big blue button next to Issuer).
  • If you have deployed the lambda/Gateway: For some reason, Cognito is unable to do OpenID Discovery. You will need to configure the endpoints manually. They are:
    • Authorization endpoint: https://github.com/login/oauth/authorize
    • Token endpoint: https://<Your API Gateway DNS name>/${Stage_Name}/token
    • Userinfo endpoint: https://<Your API Gateway DNS name>/${Stage_Name}/userinfo
    • JWKS uri, we just put a dummy endpoint here: https://<Your API Gateway DNS name>/${Stage_Name}/token

• Configure the Attribute Mapping in the AWS console:

• Ensure that your new provider is enabled under Enabled Identity Providers on the App Client Settings screen under App Integration.

*For more details please read the docs at github-cognito-openid-wrapper details