Skip to content

Commit ecf0747

Browse files
christiangdachristiangda
committed
docs: refresh project documentation
1 parent 394d6f8 commit ecf0747

12 files changed

Lines changed: 1125 additions & 448 deletions

‎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

‎docs/AWS-SAM-Template.md‎

Lines changed: 130 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,132 @@
11
# AWS SAM Template
22

3-
This project use [AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html), a tool for creating serverless applications. This facilitates the creation of serverless applications that can be deployed to [AWS Lambda](https://aws.amazon.com/lambda/) and others different resources using [AWS CloudFormation.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).
4-
5-
## Resources
6-
7-
The file [template.yaml](https://github.com/slashdevops/idp-scim-sync/blob/main/template.yaml) after being transformed by the [AWS SAM package command](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-package.html) in `packaged.yaml` creates the following resources:
8-
9-
| # | Type | CloudFormation Logical ID |
10-
| --- | --------------------------- | ------------------------------------------ |
11-
| 1 | AWS::SecretsManager::Secret | AWSGWSServiceAccountFileSecret |
12-
| 2 | AWS::SecretsManager::Secret | AWSGWSUserEmailSecret |
13-
| 3 | AWS::SecretsManager::Secret | AWSSCIMAccessTokenSecret |
14-
| 4 | AWS::SecretsManager::Secret | AWSSCIMEndpointSecret |
15-
| 5 | AWS::S3::Bucket | Bucket |
16-
| 6 | AWS::S3::BucketPolicy | BucketPolicy |
17-
| 7 | AWS::KMS::Key | KMSKey |
18-
| 8 | AWS::KMS::Alias | KMSKeyAlias |
19-
| 9 | AWS::Lambda::Function | LambdaFunction |
20-
| 10 | AWS::Logs::LogGroup | LambdaFunctionLogGroup |
21-
| 11 | AWS::IAM::Role | LambdaFunctionRole |
22-
| 12 | AWS::Events::Rule | LambdaFunctionSyncScheduledEvent |
23-
| 13 | AWS::Lambda::Permission | LambdaFunctionSyncScheduledEventPermission |
3+
This project uses [AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html) to define the Lambda-based deployment of `idp-scim-sync`. The source template is [template.yaml](../template.yaml).
4+
5+
## What The Template Does
6+
7+
The template deploys the main `idpscim` program as a scheduled Lambda function that synchronizes Google Workspace groups and users into AWS IAM Identity Center through the SCIM API.
8+
9+
At a high level, the template does the following:
10+
11+
- Creates the Lambda function and schedules it with EventBridge.
12+
- Stores sensitive credentials in Secrets Manager.
13+
- Creates an encrypted S3 bucket for the sync state file.
14+
- Creates the IAM role and permissions required by the Lambda function.
15+
- Creates the CloudWatch log group used by the function.
16+
- Adds metadata required to publish the application to the AWS Serverless Application Repository.
17+
18+
## Build And Publish Metadata
19+
20+
The template includes two important metadata blocks:
21+
22+
| Metadata | Purpose |
23+
| --- | --- |
24+
| `AWS::Serverless::Function` `BuildMethod: makefile` | Tells `sam build` to invoke `build-LambdaFunction` from [Makefile](../Makefile) |
25+
| `AWS::ServerlessRepo::Application` | Provides the public application metadata used by the AWS Serverless Application Repository |
26+
27+
This means the SAM build for this project is not a generic Go Lambda build. It is repository-specific and intentionally compiles [cmd/idpscim/main.go](../cmd/idpscim/main.go) into a `bootstrap` binary.
28+
29+
## Parameters
30+
31+
The template parameters are grouped into three practical areas.
32+
33+
### Runtime And Sync Behavior
34+
35+
| Parameter | Purpose | Default |
36+
| --- | --- | --- |
37+
| `ScheduleExpression` | EventBridge schedule for the Lambda execution | `rate(15 minutes)` |
38+
| `SyncMethod` | Sync strategy implemented by the application | `groups` |
39+
| `SyncUserFields` | Optional user attributes to synchronize | empty |
40+
| `GWSGroupsFilter` | Google Workspace group filter | empty |
41+
| `LogLevel` | Application log level | `info` |
42+
| `LogFormat` | Application log format | `json` |
43+
| `MemorySize` | Lambda memory allocation | `256` |
44+
| `Timeout` | Lambda timeout in seconds | `300` |
45+
| `Runtime` | Lambda runtime | `provided.al2023` |
46+
| `Architecture` | Lambda CPU architecture | `arm64` |
47+
| `LambdaFunctionHandler` | Lambda handler entrypoint | `bootstrap` |
48+
| `LambdaFunctionName` | Lambda function name | `idp-scim-sync` |
49+
| `LogGroupName` | CloudWatch log group name | `/aws/lambda/idp-scim-sync` |
50+
| `LogGroupRetentionDays` | CloudWatch log retention | `7` |
51+
| `RoleNameSuffix` | Optional suffix to avoid IAM role name collisions | empty |
52+
53+
### State File Storage
54+
55+
| Parameter | Purpose | Default |
56+
| --- | --- | --- |
57+
| `BucketNamePrefix` | Prefix used to build the state bucket name | `idp-scim-sync-state` |
58+
| `BucketKey` | S3 object key for the saved sync state | `data/state.json` |
59+
60+
The final bucket name is assembled as:
61+
62+
```text
63+
<BucketNamePrefix>-<AWS Account ID>-<AWS Region>
64+
```
65+
66+
### Credentials And Secret Names
67+
68+
| Parameter | Purpose | Default |
69+
| --- | --- | --- |
70+
| `GWSServiceAccountFile` | Google Workspace service account JSON contents | none |
71+
| `GWSServiceAccountFileSecretName` | Secret name for that JSON | `IDPSCIM_GWSServiceAccountFile` |
72+
| `GWSUserEmail` | Delegated Google Workspace user email | none |
73+
| `GWSUserEmailSecretName` | Secret name for that email | `IDPSCIM_GWSUserEmail` |
74+
| `SCIMEndpoint` | AWS IAM Identity Center SCIM endpoint | none |
75+
| `SCIMEndpointSecretName` | Secret name for the SCIM endpoint | `IDPSCIM_SCIMEndpoint` |
76+
| `SCIMAccessToken` | AWS IAM Identity Center SCIM access token | none |
77+
| `SCIMAccessTokenSecretName` | Secret name for the SCIM token | `IDPSCIM_SCIMAccessToken` |
78+
79+
The sensitive input values are stored in Secrets Manager, and the Lambda function receives the secret names through environment variables. The function then resolves the actual secret values at runtime.
80+
81+
## Resources Created
82+
83+
After packaging and deployment, the template creates the following resources:
84+
85+
| # | Type | Logical ID | Purpose |
86+
| --- | --- | --- | --- |
87+
| 1 | `AWS::Serverless::Function` | `LambdaFunction` | Runs the sync logic from `idpscim` |
88+
| 2 | `AWS::IAM::Role` | `LambdaFunctionRole` | Grants Lambda access to Secrets Manager, S3, KMS, logs, and X-Ray |
89+
| 3 | `AWS::SecretsManager::Secret` | `AWSGWSServiceAccountFileSecret` | Stores Google Workspace credentials |
90+
| 4 | `AWS::SecretsManager::Secret` | `AWSGWSUserEmailSecret` | Stores the delegated Google Workspace email |
91+
| 5 | `AWS::SecretsManager::Secret` | `AWSSCIMEndpointSecret` | Stores the AWS SCIM endpoint |
92+
| 6 | `AWS::SecretsManager::Secret` | `AWSSCIMAccessTokenSecret` | Stores the AWS SCIM token |
93+
| 7 | `AWS::KMS::Key` | `KMSKey` | Encrypts the S3 state bucket |
94+
| 8 | `AWS::KMS::Alias` | `KMSKeyAlias` | Stable alias for the KMS key |
95+
| 9 | `AWS::S3::Bucket` | `Bucket` | Stores the sync state file |
96+
| 10 | `AWS::S3::BucketPolicy` | `BucketPolicy` | Restricts access to the state bucket and enforces TLS |
97+
| 11 | `AWS::Logs::LogGroup` | `LambdaFunctionLogGroup` | Stores Lambda logs |
98+
99+
The scheduled trigger is defined inside the `AWS::Serverless::Function` as a SAM `Schedule` event, which expands into the EventBridge rule and the matching Lambda invoke permission during transformation.
100+
101+
## Lambda Environment
102+
103+
The Lambda function receives configuration through environment variables mapped from template parameters and created secret names.
104+
105+
Important environment variables include:
106+
107+
- `IDPSCIM_LOG_LEVEL`
108+
- `IDPSCIM_LOG_FORMAT`
109+
- `IDPSCIM_SYNC_METHOD`
110+
- `IDPSCIM_SYNC_USER_FIELDS`
111+
- `IDPSCIM_GWS_GROUPS_FILTER`
112+
- `IDPSCIM_AWS_S3_BUCKET_NAME`
113+
- `IDPSCIM_AWS_S3_BUCKET_KEY`
114+
- `IDPSCIM_GWS_USER_EMAIL_SECRET_NAME`
115+
- `IDPSCIM_GWS_SERVICE_ACCOUNT_FILE_SECRET_NAME`
116+
- `IDPSCIM_AWS_SCIM_ENDPOINT_SECRET_NAME`
117+
- `IDPSCIM_AWS_SCIM_ACCESS_TOKEN_SECRET_NAME`
118+
119+
## Outputs
120+
121+
The template exports two useful outputs:
122+
123+
| Output | Description |
124+
| --- | --- |
125+
| `LambdaFunctionArn` | ARN of the deployed Lambda function |
126+
| `LambdaFunctionName` | Name of the deployed Lambda function |
127+
128+
## Related Documentation
129+
130+
- [AWS-SAM.md](AWS-SAM.md) for deployment, update, and publish workflows
131+
- [Configuration.md](Configuration.md) for application configuration behavior
132+
- [README.md](../README.md) for high-level usage guidance

0 commit comments

Comments
 (0)