Skip to content

Commit 7ce96f1

Browse files
christiangdachristiangda
authored
Merge pull request #504 from slashdevops/chore/clean-code
Update dependencies and refresh project documentation
2 parents 4c3c7e4 + c941a5c commit 7ce96f1

18 files changed

Lines changed: 1179 additions & 472 deletions

‎.claude/settings.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(git checkout:*)",
5+
"Bash(git reset:*)",
6+
"Bash(./build/idpscimcli --help)",
7+
"Bash(./build/idpscim --help)"
8+
]
9+
}
10+
}

‎.github/copilot-instructions.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,13 @@ make build # Verify build
4646
make test # Run tests
4747
```
4848

49-
If you are intentionally modernizing syntax or APIs for Go 1.26+, run `go fix ./...` manually as a separate step.
50-
51-
Always keep `README.md` and `docs/` updated for any architectural changes, new commands/flags, removed flags, new packages, or changes to the development workflow. This includes command usage examples, flag tables, and CLI reference sections.
49+
## Pre-PR Checklist
50+
51+
- never use the `main` branch for development. Always create a new feature branch from `main` for your changes.
52+
- ensure your branch is up to date with `main` before creating a pull request
53+
- write clear and descriptive commit messages that explain the purpose of each change
54+
- ensure all tests pass locally before pushing your changes
55+
- ask the version is going to be released as a patch, minor, or major update and ensure the change log reflects this
56+
- update the `docs/Whats-New.md` file with a summary of the change, including the motivation and impact and the version it will be released in
57+
- ensure the PR description is clear and concise, providing context for reviewers and linking to any relevant issues or documentation
58+
- update the `README.md` file if the change affects usage instructions, configuration, or any other user-facing documentation

‎.vscode/settings.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
"amzn",
55
"awsconf",
66
"AWSCURRENT",
7+
"AWSGWS",
8+
"awslabs",
79
"AWSS",
810
"AWSSCIM",
911
"Babs",
@@ -46,6 +48,7 @@
4648
"hashcode",
4749
"hashicorp",
4850
"httpretrier",
51+
"httpx",
4952
"idpid",
5053
"idpscim",
5154
"idpscimcli",
@@ -77,6 +80,7 @@
7780
"sirupsen",
7881
"slashdevops",
7982
"softprops",
83+
"ssosync",
8084
"stackset",
8185
"stretchr",
8286
"stscreds",

‎README.md‎

Lines changed: 56 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,11 @@ For a detailed list of new features, improvements, and bug fixes in each release
3030

3131
This project is compatible with the latest AWS Lambda runtimes. Since version `v0.0.19`, it uses the `provided.al2` runtime and `arm64` architecture.
3232

33-
| Version Range | AWS Lambda Runtime | Architecture | Deprecation Date |
34-
| -------------------- | ------------------ | ------------------ | ---------------- |
35-
| `<= v0.0.18` | Go 1.x | amd64 (Intel) | 2023-12-31 |
33+
| Version Range | AWS Lambda Runtime | Architecture | Deprecation Date |
34+
| ---------------------- | ------------------ | ------------------ | ---------------- |
35+
| `<= v0.0.18` | Go 1.x | amd64 (Intel) | 2023-12-31 |
3636
| `>= v0.0.19 < v0.31.0` | provided.al2 | arm64 (Graviton 2) | 2026-06-30 |
37-
| `>= v0.31.0` | provided.al2023 | arm64 (Graviton 2) | 2029-06-30 |
37+
| `>= v0.31.0` | provided.al2023 | arm64 (Graviton 2) | 2029-06-30 |
3838

3939
## ⚙️ How It Works
4040

@@ -48,6 +48,40 @@ For more details on the resources created by the CloudFormation template, please
4848

4949
> **Note:** If this is your first time implementing AWS IAM Identity Center, please read [Using SSO](docs/Using-SSO.md).
5050
51+
## Programs
52+
53+
This repository builds two binaries from the `cmd/` directory:
54+
55+
| Program | Source | Purpose |
56+
| ------- | ------ | ------- |
57+
| `idpscim` | `cmd/idpscim` | Main synchronization program that runs as the Lambda function, a local CLI, or a container command |
58+
| `idpscimcli` | `cmd/idpscimcli` | Helper CLI used to inspect AWS SCIM and Google Workspace data while validating configuration |
59+
60+
After `make build`, the binaries are available in `build/`:
61+
62+
```bash
63+
./build/idpscim --help
64+
./build/idpscimcli --help
65+
```
66+
67+
## Documentation Map
68+
69+
The repository documentation is organized as follows:
70+
71+
| Document | Purpose |
72+
| ------- | ------- |
73+
| [docs/idpscim.md](docs/idpscim.md) | Main program reference for the `idpscim` sync executable |
74+
| [docs/idpscimcli.md](docs/idpscimcli.md) | Command reference for the `idpscimcli` validation and inspection CLI |
75+
| [docs/Configuration.md](docs/Configuration.md) | Configuration sources, examples, and environment variable usage |
76+
| [docs/AWS-SAM.md](docs/AWS-SAM.md) | Source deployment, Serverless Application Repository update flow, and maintainer publishing workflow |
77+
| [docs/AWS-SAM-Template.md](docs/AWS-SAM-Template.md) | Template parameters, generated resources, and Lambda environment mapping |
78+
| [docs/Development.md](docs/Development.md) | Local development workflow, build steps, tests, and SAM-based cloud testing |
79+
| [docs/Using-SSO.md](docs/Using-SSO.md) | Practical rollout guidance for AWS IAM Identity Center and Google Workspace group design |
80+
| [docs/State-File-example.md](docs/State-File-example.md) | Example state file structure and notes about how sync state is stored |
81+
| [docs/Demo.md](docs/Demo.md) | Visual walkthrough screenshots of the sync process and resulting AWS and Google Workspace data |
82+
| [docs/Release.md](docs/Release.md) | Maintainer release flow based on semantic version tags and GitHub Actions |
83+
| [docs/Whats-New.md](docs/Whats-New.md) | Release notes and notable changes across versions |
84+
5185
## 🚀 Getting Started
5286

5387
The easiest way to deploy and use this project is through the [AWS Serverless Application Repository](https://serverlessrepo.aws.amazon.com/applications/us-east-1/889836709304/idp-scim-sync).
@@ -74,112 +108,53 @@ You have several options to use this project:
74108

75109
* **AWS Serverless Application Repository (Recommended)**
76110
* Deploy the application directly from the [AWS Serverless Application Repository](https://serverlessrepo.aws.amazon.com/applications/us-east-1/889836709304/idp-scim-sync).
111+
* To update an existing deployment to a newer published version, reuse the same original application name that you entered when you first deployed it. Do not use the generated `serverlessrepo-...` stack name. See [docs/AWS-SAM.md](docs/AWS-SAM.md) for the full update flow.
77112

78113
* **AWS SAM**
79114
* Build and deploy the Lambda function from your local machine.
80-
* **Requirements:**
81-
* [Git](https://git-scm.com/)
82-
* [Go](https://go.dev/learn/)
83-
* [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
84-
* **Commands:**
115+
* Quick start:
85116

86117
```bash
87-
# Set your AWS CLI profile and region
88118
export AWS_PROFILE=<profile_name>
89119
export AWS_REGION=<region>
90-
91-
# Validate the template
92-
sam validate
93-
94-
# Build the project
95-
sam build
96-
97-
# Deploy with a guided process
98-
sam deploy --guided --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM
120+
GIT_VERSION=dev sam build
121+
sam deploy --guided --stack-name idp-scim-sync --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM
99122
```
100123

124+
* For full validation, source deployment, publish, and update guidance, see [docs/AWS-SAM.md](docs/AWS-SAM.md) and [docs/AWS-SAM-Template.md](docs/AWS-SAM-Template.md).
125+
101126
### Locally
102127

103128
* **Build from Source**
104-
* **Requirements:**
105-
* [Git](https://git-scm.com/)
106-
* [Go](https://go.dev/learn/)
107-
* [Make](https://www.gnu.org/software/make/)
108-
* **Commands:**
129+
* Quick start:
109130

110131
```bash
111-
# Compile for your operating system
112132
make
113-
114-
# Cross-compile for Windows, macOS, and Linux
115-
make build-dist
133+
./build/idpscim --help
134+
./build/idpscimcli --help
116135
```
117136

137+
* **Run the programs**
138+
* **idpscim** runs the actual synchronization logic.
139+
* **idpscimcli** helps you validate your AWS SCIM and Google Workspace configuration before enabling automated sync.
140+
* See [docs/idpscim.md](docs/idpscim.md), [docs/idpscimcli.md](docs/idpscimcli.md), [docs/Configuration.md](docs/Configuration.md), and [docs/Development.md](docs/Development.md) for examples, flags, and the full local workflow.
141+
118142
* **Pre-built Binaries**
119143
* Download the binaries from the [GitHub Releases](https://github.com/slashdevops/idp-scim-sync/releases).
120144

121145
* **Container Image**
122146
* Pull the image from the [GitHub Container Registry](https://github.com/slashdevops/idp-scim-sync/pkgs/container/idp-scim-sync).
147+
* Container build and execution details are documented in [docs/idpscim.md](docs/idpscim.md), [docs/idpscimcli.md](docs/idpscimcli.md), and [docs/Development.md](docs/Development.md).
123148

124149
## Configurable User Fields
125150

126151
By default, all optional user attributes are synced from Google Workspace to AWS SSO SCIM. You can control which optional fields are included using the `sync_user_fields` configuration option.
127152

128-
**Available fields:**
129-
130-
| Field | Description |
131-
| ------------------- | --------------------------------------------------------------------------- |
132-
| `phoneNumbers` | User's phone numbers |
133-
| `addresses` | User's addresses (street, city, region, postal code, country) |
134-
| `title` | User's job title |
135-
| `preferredLanguage` | User's preferred language |
136-
| `locale` | User's locale |
137-
| `timezone` | User's timezone |
138-
| `nickName` | User's nickname |
139-
| `profileURL` | User's profile URL |
140-
| `userType` | User type attribute |
141-
| `enterpriseData` | Enterprise extension (employeeNumber, costCenter, organization, department, division, manager) |
142-
143-
**Required fields** (always synced, not configurable): `name`, `userName`, `displayName`, `emails`, `active`.
144-
145-
### Configuration Examples
146-
147-
**Config file (.idpscim.yaml):**
148-
149-
```yaml
150-
# Sync only phone numbers, addresses, and enterprise data
151-
sync_user_fields:
152-
- phoneNumbers
153-
- addresses
154-
- enterpriseData
155-
```
156-
157-
**Environment variable (Lambda / SAM):**
158-
159-
```bash
160-
IDPSCIM_SYNC_USER_FIELDS=phoneNumbers,addresses,enterpriseData
161-
```
162-
163-
**CLI flag:**
164-
165-
```bash
166-
idpscim --sync-user-fields phoneNumbers,addresses,enterpriseData
167-
```
168-
169-
**SAM template parameter:**
170-
171-
Set the `SyncUserFields` parameter when deploying:
172-
173-
```bash
174-
sam deploy --parameter-overrides SyncUserFields=phoneNumbers,addresses,enterpriseData
175-
```
153+
Supported optional fields include `phoneNumbers`, `addresses`, `title`, `preferredLanguage`, `locale`, `timezone`, `nickName`, `profileURL`, `userType`, and `enterpriseData`.
176154

177-
### Behavior Notes
155+
Required fields are always synchronized: `name`, `userName`, `displayName`, `emails`, and `active`.
178156

179-
* **Default (empty or not set):** When `sync_user_fields` is empty or not configured, all optional fields are synced. This preserves backward compatibility with existing deployments.
180-
* **Specifying fields:** Only the listed fields will be synced. For example, setting `sync_user_fields: [phoneNumbers]` will sync only phone numbers; addresses, enterprise data, and other optional attributes will not be sent to AWS SSO SCIM.
181-
* **Invalid field names:** If an invalid field name is provided, the application will fail at startup with a clear error message listing the unrecognized field.
182-
* **Changing on an existing deployment:** The first sync after modifying this configuration will detect all users as "changed" (due to hash differences) and update them in AWS SSO. This is expected behavior — it will clear the excluded fields from SCIM.
157+
For config file examples, environment variable usage, CLI flags, SAM parameter usage, and behavior notes, see [docs/Configuration.md](docs/Configuration.md) and [docs/idpscim.md](docs/idpscim.md).
183158

184159
## 📦 Repositories
185160

@@ -200,12 +175,6 @@ If you are coming from the [awslabs/ssosync](https://github.com/awslabs/ssosync)
200175
* This project only implements filtering for Google Workspace Groups, not Users.
201176
* This project supports selecting which optional user attributes to sync via `--sync-user-fields` (e.g., phone numbers, addresses, enterprise data).
202177
* The flag names are different.
203-
* Not all features of `ssosync` are implemented here, and they may not be in the future.
204-
205-
## 🧩 Components
206-
207-
* **idpscim**: A program for keeping AWS IAM Identity Center groups and users synced with your Google Workspace directory. See the [idpscim documentation](docs/idpscim.md) for more details.
208-
* **idpscimcli**: A command-line tool to check and validate some of the functionalities implemented in `idpscim`. See the [idpscimcli documentation](docs/idpscimcli.md) for more details.
209178

210179
## 📄 License
211180

‎SECURITY.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,23 @@
11
# Security Policy
22

33
This project is using [Github CodeQL](https://codeql.github.com/) tool to scan the code vulnerabilities and you can see the report in the pipeline
4-
[![CodeQL Analysis](https://github.com/slashdevops/idp-scim-sync/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/slashdevops/idp-scim-sync/actions/workflows/codeql-analysis.yml)
4+
[![CodeQL Analysis](https://github.com/slashdevops/idp-scim-sync/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/slashdevops/idp-scim-sync/actions/workflows/codeql.yml)
5+
6+
Since this project is always in development and updated to the last release of `go` and its dependencies, the vulnerabilities are always fixed in the last release, so we will support the last 1 major version and its patches.
57

68
## Supported Versions
79

810
| Version | Supported |
911
| ------- | ------------------ |
10-
| 0.1.x | :white_check_mark: |
11-
| 0.0.x | :white_check_mark: |
12+
| 0.44.x | :white_check_mark: |
13+
| 0.43.x | :x: |
14+
| 0.42.x | :x: |
15+
| 0.32.x | :x: |
16+
| 0.31.x | :x: |
17+
| 0.30.x | :x: |
18+
| 0.2.x | :x: |
19+
| 0.1.x | :x: |
20+
| 0.0.x | :x: |
1221

1322
## Reporting a Vulnerability
1423

0 commit comments

Comments
 (0)