README

UserPoolIdentityProviderGithub CDK construct

This library bundles the GitHub OpenID Connect Wrapper for Cognito as a CDK construct, instead of the original SAM implementation.

The goal behind is to make it as easy to use GitHub as an identity provider as officially supported identity providers. Under the hood, it creates additional resources (a REST API and 5 Lambda functions) to connect Cognito to GitHub.

⚠️ Project status

At a first glance, the proposed construct is supposed to work. However, we ended up not using GitHub with Cognito and we cannot rightfully maintain a construct without using it. For this reason, we're archiving this repository. If anyone wants to maintain it, please open an issue. If you decide to use this construct (at your own risks), be aware that a new SSH key might be generated every time the Dockerfile is built which could lead to a very short interruption of service during deployment. A solution would be to generate the SSH key outside of CDK and pass it through the context for instance.

Install

npm

npm install --save cdk-user-pool-identity-provider-github

Go, Maven, NuGet, PyPI

Other package managers aren't supported yet, but they could be easily. Let us know your needs by opening an issue.

Usage

This construct works in a similar way than officially supported identity providers.

See API for a full reference.

Basic setup

If you already have a user pool with a client and a hosted UI with a custom domain, then you can simply do:

import { UserPoolIdentityProviderGithub } from 'cdk-user-pool-identity-provider-github';

new UserPoolIdentityProviderGithub(this, 'UserPoolIdentityProviderGithub', {
  userPool: myUserPool,
  clientId: 'myClientId',
  clientSecret: 'myClientSecret',
  cognitoHostedUiDomain: 'https://auth.domain.com',
});

Full setup

The following snippet does the following:

Create a user pool
Configure the hosted UI with a custom domain
Create a Github identity provider for the user pool
Create a user pool client with Cognito and Github as identity providers

import { DnsValidatedCertificate } as acm from '@aws-cdk/aws-certificatemanager';
import { UserPool } from '@aws-cdk/aws-cognito';
import { ARecord, RecordTarget } from '@aws-cdk/aws-route53';
import { UserPoolIdentityProviderGithub } from 'cdk-user-pool-identity-provider-github';

// Parameters
const userPoolDomainName = 'https://auth.domain.com';
const callbackUrls = ['https://www.domain.com'];
const logoutUrls = ['https://www.domain.com'];
const githubClientId = 'githubClientId';
const githubClientSecret = 'githubClientSecret';

// User pool
const userPool = new UserPool(stack, 'UserPool');

// Hosted UI with custom domain
const userPoolDomain = userPool.addDomain('UserPoolDomain', {
  customDomain: {
    certificate: new DnsValidatedCertificate(this, 'Certificate', {
      domainName: userPoolDomainName,
      hostedZone: props.hostedZone,
      region: 'us-east-1', // Cloudfront only checks this region for certificates.
    }),
    domainName: userPoolDomainName,
  },
});
new ARecord(this, 'CustomDomainAliasRecord', {
  zone: props.hostedZone,
  recordName: userPoolDomainName,
  target: RecordTarget.fromAlias({
    bind: () => ({
      hostedZoneId: 'Z2FDTNDATAQYW2', // CloudFront Zone ID
      dnsName: userPoolDomain.cloudFrontDomainName,
    }),
  }),
});

// Github identity provider
new UserPoolIdentityProviderGithub(this, 'UserPoolIdentityProviderGithub', {
  userPool,
  clientId: githubClientId,
  clientSecret: githubClientSecret,
  cognitoHostedUiDomain: userPoolDomainName,
});

// User pool client
const userPoolClient = userPool.addClient('UserPoolClient', {
  oAuth: {
    callbackUrls,
    logoutUrls,
  },
  supportedIdentityProviders: [
    cognito.UserPoolClientIdentityProvider.COGNITO,
    cognito.UserPoolClientIdentityProvider.custom('Github'),
  ],
});
userPoolClient.node.addDependency(userPoolIdentityProviderGithub);

Contributing

Feedback and pull requests are more than welcome 🤗

This project uses the projen project generator. Learn how to use it for CDK constructs here.

Please use conventional commits to ease automated versioning and changelog generation.

Note that the github-cognito-openid-wrapper version is defined here. To benefit from newer versions, please update the git tag in the Dockerfile.

License

This code is distributed under MIT license, that you can read here.

It also redistributes code from GitHub OpenID Connect Wrapper for Cognito, distributed under BSD 3-Clause license, that you can read here.

Usage no npm install needed!