<application_license_badge>

BC Gov Terraform Template

This repo provides a starting point for users who want to create valid Terraform modules stored in GitHub.

Third-Party Products/Libraries used and the licenses they are covered by

Project Status

• Development
• Production/Maintenance

Documentation

Requirements

Name	Version
aws	~> 4.0
keycloak	>= 2.0.0

Providers

Name	Version
aws	~> 4.0
external	n/a
keycloak	>= 2.0.0

Modules

Name	Source	Version
cloud_roles	github.com/BCDevOps/terraform-keycloak-role-group-simplification	n/a

Resources

Name	Type
aws_iam_policy.bcgov_perm_boundary	resource
aws_iam_role.admin_role	resource
aws_iam_role_policy_attachment.role-policy-attach	resource
aws_iam_saml_provider.default	resource
aws_caller_identity.aws_context	data source
external_external.saml_idp_descriptor	data source
keycloak_realm.kc-lz-sso-realm	data source

Inputs

Name	Description	Type	Default	Required
account_name	Name to identify the account.	string	n/a	yes
account_roles	Roles and associated policies for an account.	map(string)	n/a	yes
aws_saml_idp_name	Name for Keycloak IDP that will be created in AWS	string	"BCGovKeyCloak"	no
kc_base_url	Base URL of KeyCloak instance to interact with.	string	n/a	yes
kc_iam_auth_client_id	Client ID of client where KC roles corresponding to AWS roles will be created.	string	n/a	yes
kc_realm	KeyCloak realm where terraform client has been created and where users/groups to be created/manipulated exist.	string	n/a	yes
trusted_login_sources	A list of one or more URLs from which login is expected and permitted.	list(string)	[ "https://signin.aws.amazon.com/saml" ]	no

Outputs

Name	Description
roles	module outputs should be defined and documented here.

References

The steps here are partially based on those in this article:

Getting Started

Pre-requisites

KeyCloak

• realm-admin access to the KeyCloak realm where the configuration objects will be created

AWS

• admin-type access with access key to an AWS account where the SAML configuration objects will be created

Initial Steps

Prior to executing the automation code, there are a few steps (below) that must be completed manually.

• Create a KeyCloak OIDC client that will be used by Terraform to perform its automations. This should have the following values on the "Settings" tab:

  • Access-type: confidential
  • Standard Flow Enabled: Off
  • Implicit Flow Enabled: Off
  • Direct Access Grants Enabled: Off
  • Service Accounts Enabled: On

• Capture and save the Secret token from the Credentials tab of the client created above. It will be used as the keycloak access key by terraform.

• Grant the realm-admin or similar role to the service account you've just created via Clients -> -> Service Account Roles -> Client Roles

• retrieve the AWS-provided SAML metadata file here and save to your workstation.

• In the KeyCloak realm, create a new SAML client

• Import the AWS-provided SAML metadata file, which will pre-populate most to the client configuration value.

• Modify the Base URL field so it looks like: /auth/realms/<your_realm_name>/protocol/saml/clients/amazon-aws

• Modify the IDP Initiated SSO URL Name field so it has the value amazon-aws.

• Modify Name ID Format so it has the value persistent

• If you happen to have deployed aws-login before confoguing KeyCloak and AWS roles (which is fine) you can also edit the following with the url spit out by aws-login deployment:

• Valid Redirect URIs (add it to the default)
• Fine Grain SAML Endpoint Configuration -> Assertion Consumer Service Post Binding URL

• Save the client configuration
• In the "Scope" tab for the client you just created, set "Full Scope Allowed" to "Off"

You'll need the following values for the automation code:

• Client ID/GUID of the SAML client you created above (grab from URL)
• Service Account key from Client -> Crednetials tab of the Terraform automation client you created above
• The realm name
• The base url of the KeyCloak server

Getting Help or Reporting an Issue

To report bugs/issues/feature requests, please file an issue.

How to Contribute

If you would like to contribute, please see our CONTRIBUTING guidelines.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License

Copyright 2018 Province of British Columbia

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.