{"id":13818003,"url":"https://github.com/redhat-cop/group-sync-operator","last_synced_at":"2025-06-18T03:06:25.564Z","repository":{"id":37085840,"uuid":"258887702","full_name":"redhat-cop/group-sync-operator","owner":"redhat-cop","description":"Synchronizes groups from external providers into OpenShift","archived":false,"fork":false,"pushed_at":"2025-06-17T16:34:05.000Z","size":1011,"stargazers_count":119,"open_issues_count":59,"forks_count":60,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-06-17T17:42:30.251Z","etag":null,"topics":["container-cop","k8s-operator"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redhat-cop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-25T22:33:05.000Z","updated_at":"2025-06-14T18:53:48.000Z","dependencies_parsed_at":"2023-12-18T18:42:31.640Z","dependency_job_id":"db33a029-1175-4dc6-9eae-d0c24873044b","html_url":"https://github.com/redhat-cop/group-sync-operator","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/redhat-cop/group-sync-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fgroup-sync-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fgroup-sync-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fgroup-sync-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fgroup-sync-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redhat-cop","download_url":"https://codeload.github.com/redhat-cop/group-sync-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fgroup-sync-operator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260477921,"owners_count":23015064,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container-cop","k8s-operator"],"created_at":"2024-08-04T07:00:26.617Z","updated_at":"2025-06-18T03:06:20.551Z","avatar_url":"https://github.com/redhat-cop.png","language":"Go","funding_links":[],"categories":["Identity Management"],"sub_categories":[],"readme":"Group Sync Operator\n===================\n\n[![Build Status](https://github.com/redhat-cop/group-sync-operator/workflows/push/badge.svg?branch=master)](https://github.com/redhat-cop/group-sync-operator/actions?workflow=push)\n [![Docker Repository on Quay](https://quay.io/repository/redhat-cop/group-sync-operator/status \"Docker Repository on Quay\")](https://quay.io/repository/redhat-cop/group-sync-operator)\n\nSynchronizes groups from external providers into OpenShift\n\n## Overview\n\nThe OpenShift Container Platform contains functionality to synchronize groups found in external identity providers into the platform. Currently, the functionality that is included in OpenShift is limited to synchronizing LDAP only. This operator is designed to integrate with external providers in order to provide new solutions.\n\nGroup Synchronization is facilitated by creating a `GroupSync` resource. The following describes the high level schema for this resource:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: example-groupsync\nspec:\n  providers:\n    - \u003cOne or more providers to synchronize\u003e\n```\n\n## Deploying the Operator\n\nUse the following steps to deploy the operator to an OpenShift cluster\n\n1. Clone the project locally and changed into the project\n.\n.\n\n```shell\ngit clone https://github.com/redhat-cop/group-sync-operator.git\ncd group-sync-operator\n```\n\n2. Deploy the Operator\n\n```shell\nmake deploy IMG=quay.io/redhat-cop/group-sync-operator:latest\n```\n\n_Note:_ The `make deploy` command will execute the `manifests` target that will require additional build tools to be made available. This target can be skipped by including the `-o manifests` in the command above.\n\n## Authentication\n\nIn most cases, authentication details must be provided in order to communicate with providers. Authentication details are provider specific with regards to the required values. In supported providers, the secret can be referenced in the `credentialsSecret` by name and namespace where it has been created as shown below:\n\n```yaml\ncredentialsSecret:\n  name: \u003csecret_name\u003e\n  namespace: \u003csecret_namespace\u003e\n```\n\n## Providers\n\nIntegration with external systems is made possible through a set of pluggable external providers. The following providers are currently supported:\n\n* [Azure](https://azure.microsoft.com/)\n* [GitHub](https://github.com)\n* [GitLab](https://gitlab.com)\n* [LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)\n* [Keycloak](https://www.keycloak.org/)/[Red Hat Single Sign On](https://access.redhat.com/products/red-hat-single-sign-on)\n* [Okta](https://www.okta.com/)\n* [IBM Security Verify](https://docs.verify.ibm.com/verify)\n\nThe following sections describe the configuration options available for each provider\n\n### Azure\n\nGroups contained within Azure Active Directory can be synchronized into OpenShift. The following table describes the set of configuration options for the Azure provider:\n\n| Name | Description | Defaults | Required |\n| ----- | ---------- | -------- | ----- |\n| `authorityHost` | Azure Active Directory Endpoint | `https://login.microsoftonline.com` | No |\n| `baseGroups` | List of groups to start searching from instead of listing all groups in the directory | | No |\n| `credentialsSecret` | Name of the secret containing authentication details (See below) | | Yes |\n| `filter` | Graph API filter | | No |\n| `groups` | List of groups to filter against | | No |\n| `userNameAttributes` | Fields on a user record to use as the User Name | `userPrincipalName` | No |\n| `prune` | Prune Whether to prune groups that are no longer in Azure | `false` | No |\n\nThe following is an example of a minimal configuration that can be applied to integrate with a Azure provider:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: azure-groupsync\nspec:\n  providers:\n  - name: azure\n    azure:\n      credentialsSecret:\n        name: azure-group-sync\n        namespace: group-sync-operator\n```\n\n#### Authenticating to Azure\n\nAuthentication to Azure can be performed using Application Registration with access to query group information in Azure Active Directory.\n\nThe App Registration must be granted access to the following Microsoft Graph API's:\n\n* Group.Read.All\n* GroupMember.Read.All\n* User.Read.All\n\nA secret must be created in the same namespace that contains the `GroupSync` resource:\n\nThe following keys must be defined in the secret\n\n* `AZURE_TENANT_ID` - Tenant ID\n* `AZURE_CLIENT_ID` - Client ID\n* `AZURE_CLIENT_SECRET` - Client Secret\n\nThe secret can be created by executing the following command:\n\n```shell\noc create secret generic azure-group-sync --from-literal=AZURE_TENANT_ID=\u003cAZURE_TENANT_ID\u003e --from-literal=AZURE_CLIENT_ID=\u003cAZURE_CLIENT_ID\u003e --from-literal=AZURE_CLIENT_SECRET=\u003cAZURE_CLIENT_SECRET\u003e\n```\n\n### GitHub\n\nTeams stored within a GitHub organization can be synchronized into OpenShift. The following table describes the set of configuration options for the GitHub provider:\n\n| Name | Description | Defaults | Required |\n| ----- | ---------- | -------- | ----- |\n| `ca` | Reference to a resource containing a SSL certificate to use for communication (See below) | | No |\n| `caSecret` | **DEPRECATED** Reference to a secret containing a SSL certificate to use for communication (See below) | | No |\n| `credentialsSecret` | Reference to a secret containing authentication details (See below) | | Yes |\n| `insecure` | Ignore SSL verification | `false` | No |\n| `organization` | Organization to synchronize against | | Yes |\n| `teams` | List of teams to filter against | | No |\n| `url` | Base URL for the GitHub or GitHub Enterprise host (Must contain a trailing slash) | | No |\n| `prune` | Prune Whether to prune groups that are no longer in GitHub | `false` | No |\n\nThe following is an example of a minimal configuration that can be applied to integrate with a GitHub provider:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: github-groupsync\nspec:\n  providers:\n  - name: github\n    github:\n      organization: ocp\n      credentialsSecret:\n        name: github-group-sync\n        namespace: group-sync-operator\n```\n\n#### Authenticating to GitHub\n\nAuthentication to GitHub can be performed using an [OAuth Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) or as an [GitHub App](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps), using a secret key and appId.\nThe OAuth Personal Access Token needs to scope of `admin:org/read:org`.\nA secret must be created in the same namespace that contains the `GroupSync` resource:\n\n##### OAuth\n\nWhen using an OAuth token, the following key is required:\n\n* `token` - OAuth token\n\nThe secret can be created by executing the following command:\n\n```shell\noc create secret generic github-group-sync --from-literal=token=\u003ctoken\u003e\n```\n\n##### As a GitHub app\n\nWhen authenticating as a Github App, the following keys are required:\n\n* `privateKey` and `appId`\n\n###### First create a GitHub app\n\nIn GitHub, go to developer-settings -\u003e github apps.\n\n* Create a new app, it does not need webhook callbacks.\n* Generate a private-key and download it\n* Under \"permissions and events\", the app will need read-only access to the \"Members\" permission in the \"Organization\" section. NOTE: If you enable `mapByScimId`, this permissions needs to be _Read \u0026 Write_, though the operator only does read-only operations. The reason for this is the use of the v4 graphql api-endpoint.\n* Take note of the \"App ID\" as you need it for later.\n* Install the app to your organization.\n\n###### Create the secret\n\nThe secret can be created by executing the following command:\n\n```shell\noc create secret generic github-group-sync --from-literal=appId=\u003ctheAppId\u003e --from-file=privateKey=\u003c/path/to/thefile\u003e\n```\n\n### GitLab\n\nGroups stored within a GitLab can be synchronized into OpenShift. The following table describes the set of configuration options for the GitLab provider:\n\n| Name | Description | Defaults | Required |\n| ----- | ---------- | -------- | ----- |\n| `ca` | Reference to a resource containing a SSL certificate to use for communication (See below) | | No |\n| `caSecret` | **DEPRECATED** Reference to a secret containing a SSL certificate to use for communication (See below) | | No |\n| `credentialsSecret` | Reference to a secret containing authentication details (See below) | | Yes |\n| `insecure` | Ignore SSL verification | `false` | No |\n| `groups` | List of groups to filter against | | No |\n| `prune` | Prune Whether to prune groups that are no longer in GitLab | `false` | No |\n| `scope` | Scope for group synchronization. Options are `one` for one level or `sub` to include subgroups | `sub` | No |\n| `url` | Base URL for the GitLab instance | `https://gitlab.com` | No |\n\nThe following is an example of a minimal configuration that can be applied to integrate with a GitHub provider:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: gitlab-groupsync\nspec:\n  providers:\n  - name: gitlab\n    gitlab:\n      credentialsSecret:\n        name: gitlab-group-sync\n        namespace: group-sync-operator\n```\n\n#### Authenticating to GitLab\n\nAuthentication to GitLab can be performed using a [Token](https://docs.gitlab.com/ee/security/token_overview.html) or a Username and Password (Note: 2FA not supported). A secret must be created in the same namespace that contains the `GroupSync` resource:\n\nWhen using an OAuth token, the following token types are supported:\n\n* Personal Access Token\n* OAuth Token\n* Job Token\n\n the following key is required:\n\n* `token` - OAuth token\n\nOptionally, the `tokenType` key can be specified to indicate the type of token being provided from the following values:\n\n* OAuth - `oauth`\n* Personal Access Token - `personal`\n* Job Token - `job`\n\nIf no `tokenType` is provided, `oauth` is used by default\n\nThe secret can be created by executing the following command:\n\n```shell\noc create secret generic gitlab-group-sync --from-literal=token=\u003ctoken\u003e\n```\n\nTo specify a token type, such as a Personal Access Token, the following command can be executed:\n\n```shell\noc create secret generic gitlab-group-sync --from-literal=token=\u003ctoken\u003e --from-literal=tokenType=personal\n``` \n\nThe following keys are required for username and password:\n\n* `username` - Username for authenticating with GitLab\n* `password` - Password for authenticating with GitLab\n\nThe secret can be created by executing the following command:\n\n```shell\noc create secret generic gitlab-group-sync --from-literal=username=\u003cusername\u003e --from-literal=password=\u003cpassword\u003e\n```\n\n### LDAP\n\nGroups stored within an [LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) server can be synchronized into OpenShift. The LDAP provider implements the included features of the [Syncing LDAP groups](https://docs.openshift.com/container-platform/latest/authentication/ldap-syncing.html) feature and makes use of the libraries from the [OpenShift Command Line](https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html) tool to streamline the migration to this operator based implementation.\n\nThe configurations of the three primary schemas (`rfc2307`, `activeDirectory` and `augmentedActiveDirectory`) can be directly migrated as is without any modification.\n\n| Name | Description | Defaults | Required |\n| ----- | ---------- | -------- | ----- |\n| `ca` | Reference to a resource containing a SSL certificate to use for communication (See below) | | No |\n| `caSecret` | **DEPRECATED** Reference to a secret containing a SSL certificate to use for communication (See below) | | No |\n| `credentialsSecret` | Reference to a secret containing authentication details (See below) | | No |\n| `insecure` | Ignore SSL verification | `false` | No |\n| `groupUIDNameMapping` | User defined name mapping | | No |\n| `rfc2307` | Configuration using the [rfc2307](https://docs.openshift.com/container-platform/latest/authentication/ldap-syncing.html#ldap-syncing-rfc2307_ldap-syncing-groups) schema | | No |\n| `activeDirectory` | Configuration using the [activeDirectory](https://docs.openshift.com/container-platform/4.5/authentication/ldap-syncing.html#ldap-syncing-activedir_ldap-syncing-groups) schema | | No |\n| `augmentedActiveDirectory` | Configuration using the [activeDirectory](https://docs.openshift.com/container-platform/4.5/authentication/ldap-syncing.html#ldap-syncing-augmented-activedir_ldap-syncing-groups) schema | | No |\n| `url` | Connection URL for the LDAP server | `ldap://ldapserver:389` | No |\n| `whitelist` | Explicit list of groups to synchronize |  | No |\n| `blacklist` | Explicit list of groups to not synchronize |  | No |\n| `prune` | Prune Whether to prune groups that are no longer in LDAP | `false` | No |\n\nThe following is an example using the `rfc2307` schema:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: ldap-groupsync\nspec:\n  providers:\n  - ldap:\n      credentialsSecret:\n        name: ldap-group-sync\n        namespace: group-sync-operator\n      insecure: true\n      rfc2307:\n        groupMembershipAttributes:\n        - member\n        groupNameAttributes:\n        - cn\n        groupUIDAttribute: dn\n        groupsQuery:\n          baseDN: ou=Groups,dc=example,dc=com\n          derefAliases: never\n          filter: (objectClass=groupofnames)\n          scope: sub\n        tolerateMemberNotFoundErrors: true\n        tolerateMemberOutOfScopeErrors: true\n        userNameAttributes:\n        - cn\n        userUIDAttribute: dn\n        usersQuery:\n          baseDN: ou=Users,dc=example,dc=com\n          derefAliases: never\n          scope: sub\n      url: ldap://ldapserver:389\n    name: ldap\n```\n\nThe examples provided in the OpenShift documented referenced previously can be used to construct the schemas for the other LDAP synchronization types.\n\n#### Authenticating to LDAP\n\nIf authentication is required in order to communicate with the LDAP server, a secret should be created in the same namespace that contains the `GroupSync` resource. The following keys can be defined:\n\n* `username` - Username (Bind DN) for authenticating with the LDAP server\n* `password` - Password for authenticating with the LDAP server\n\nThe secret can be created by executing the following command:\n\n```shell\noc create secret generic ldap-group-sync --from-literal=username=\u003cusername\u003e --from-literal=password=\u003cpassword\u003e\n```\n\n#### Whitelists and Blacklists\n\nGroups can be explicitly whitelisted or blacklisted in order to control the groups that are eligible to be synchronized into OpenShift. When running LDAP group synchronization using the command line, this configuration is referenced via separate files, but these are instead specified in the `blacklist` and `whitelist` properties as shown below:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: ldap-groupsync\nspec:\n  providers:\n  - ldap:\n...\n      whitelist:\n      - cn=Online Corporate Banking,ou=Groups,dc=example,dc=com\n...\n    name: ldap\n```\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: ldap-groupsync\nspec:\n  providers:\n  - ldap:\n...\n      blacklist:\n      - cn=Finance,ou=Groups,dc=example,dc=com\n...\n    name: ldap\n```\n\n### Keycloak\n\nGroups stored within Keycloak can be synchronized into OpenShift. The following table describes the set of configuration options for the Keycloak provider:\n\n| Name | Description | Defaults | Required |\n| ----- | ---------- | -------- | ----- |\n| `ca` | Reference to a resource containing a SSL certificate to use for communication (See below) | | No |\n| `caSecret` | **DEPRECATED** Reference to a secret containing a SSL certificate to use for communication (See below) | | No |\n| `credentialsSecret` | Reference to a secret containing authentication details (See below) | | Yes |\n| `groups` | List of groups to filter against | | No |\n| `insecure` | Ignore SSL verification | `false` | No |\n| `loginRealm` | Realm to authenticate against | `master` | No |\n| `realm` | Realm to synchronize | | Yes |\n| `scope` | Scope for group synchronization. Options are `one` for one level or `sub` to include subgroups | `sub` | No |\n| `url` | Base URL for the Keycloak server. Older versions (\u003c17.0.0) including Red Hat SSO should include the context path `/auth` appended to the hostname  | | Yes |\n| `prune` | Prune Whether to prune groups that are no longer in Keycloak | `false` | No |\n\nThe following is an example of a minimal configuration that can be applied to integrate with a Keycloak provider:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: keycloak-groupsync\nspec:\n  providers:\n  - name: keycloak\n    keycloak:\n      realm: ocp\n      credentialsSecret:\n        name: keycloak-group-sync\n        namespace: group-sync-operator\n      url: https://keycloak-keycloak-operator.apps.openshift.com/auth\n```\n\n#### Authenticating to Keycloak\n\nA user with rights to query for Keycloak groups must be available. The following permissions must be associated to the user:\n\n* Password must be set (Temporary option unselected) on the _Credentials_ tab\n* On the _Role Mappings_ tab, select _master-realm_ or _realm-management_ next to the _Client Roles_ dropdown and then select **query-groups**, **query-users**, and **view-users**.\n\nA secret must be created in the same namespace that contains the `GroupSync` resource. It must contain the following keys for the user previously created:\n\n* `username` - Username for authenticating with Keycloak\n* `password` - Password for authenticating with Keycloak\n\nThe secret can be created by executing the following command:\n\n```shell\noc create secret generic keycloak-group-sync --from-literal=username=\u003cusername\u003e --from-literal=password=\u003cpassword\u003e\n```\n\n### Okta\n\n[Okta Groups](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-main.htm) assigned to [Okta Applications](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_Apps.htm) can be synchronized into OpenShift. The developer docs for the Okta API that the Okta Syncer uses can be found [here](https://developer.okta.com/docs/reference/api/apps/#list-groups-assigned-to-application).\nThe following table describes the set of configuration options for the Okta provider:\n\n| Name | Description | Defaults | Required |\n| ----- | ---------- | -------- | ----- |\n| `credentialsSecret` | Reference to a secret containing authentication details (See below) | `''`  | Yes |\n| `groups` | List of groups to filter against | `nil`  | No |\n| `url` | Okta URL which can be found under the \"Okta Domain\" in your application settings (must contain the scheme and a trailing slash) | `''`  | Yes |\n| `appId` | Okta Application (Client) ID that is attached to the application groups you wish to sync | `''`  | Yes |\n| `extractLoginUsername` | Bool to determine if you should extract username from okta login | `false`  | No |\n| `profileKey` | Attribute field on Okta User Profile you would like to use as identity | `'login'` | No |\n| `groupLimit` | Integer to set the maximum number of groups to retrieve from OKTA per request. | `1000` | No |\n| `prune` | Prune Whether to prune groups that are no longer in OKTA | `false` | No |\n\nThe following is an example of a minimal configuration that can be applied to integrate with an Okta provider:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: okta-sync\nspec:\n  providers:\n    - name: okta\n      okta:\n        credentialsSecret:\n          name: okta-api-token\n          namespace: group-sync-operator\n        url: \"https://example.okta.com/\"\n        appId: xxxxxxxxxxxxxxxxxxxx\n```\n\n#### Authenticating to Okta\n\nA secret must be created in the same namespace as the group-sync-operator pod. It must contain the following key:\n\n* `okta-api-token` - Okta API Token for interacting with Okta\n\nThe secret can be created by executing the following command:\n\n```shell\noc create secret generic okta-api-token --from-literal=okta-api-token=\u003cOKTA_API_TOKEN\u003e -n group-sync-operator\n```\n\n### IBM Security Verify\n\nGroups defined in [IBM Security Verify](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-main.htm) (ISV) can be synchronized into OpenShift. Currently only the `userName` field from ISV will be synchronized. The developer docs for the ISV API can be found [here](https://docs.verify.ibm.com/verify/page/api-documentation).\nThe following table describes the set of configuration options for the provider:\n\n| Name | Description | Defaults | Required |\n| ----- | ---------- | -------- | ----- |\n| `credentialsSecret` | Reference to a secret containing authentication details (see below) | `''`  | Yes |\n| `groups` | List of groups to synchronize (see below) | `nil`  | Yes |\n| `tenantUrl` | The ISV tenant URL, for example `https://my-isv.verify.ibm.com`) | `''`  | Yes |\n\nThe following is an example of a minimal configuration that can be applied to integrate with an Okta provider:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: ibmsecurityverify-sync\nspec:\n    providers:\n    - name: ibmsecurityverify\n      ibmsecurityverify:\n        credentialsSecret:\n          name: isv-group-sync\n          namespace: group-sync-operator\n        tenantUrl: https://my-isv.verify.ibm.com\n        groups:\n          - name: 'application owners'\n            id: 645001V3V9\n          - name: developer\n            id: 645001V3VA\n```\n\n#### Group Objects\nEach group object in the `groups` array must contain an `id` field. The group ID can be retrieved by pulling the group information from the ISV API. Optionally, the object may also contain a `name` which corresponds to the group's display name. When defined, the operator will confirm that the name defined in the YAML matches that received from the API when synchronization occurs; as the group IDs are not human-friendly, using the name can confirm the correct groups are configured. If the names do not match an error will be logged.\n\n#### Group Names\nThe name of each groups created in OpenShift will match the group name in ISV. Any whitespace in the ISV group name will be replaced with a hyphen.\n\n#### Authenticating to IBM Security Verify\n\nA secret must be created in the same namespace as the group-sync-operator pod. It must contain the following keys:\n\n* `clientId` - The API client ID.\n* `clientSecret`- The API client secret.\n\nSee the IBM Security Verify [API documentation](https://docs.verify.ibm.com/verify/docs/api-access) for setting up authentication.\n\n### Support for Additional Metadata (Beta)\n\nAdditional metadata based on Keycloak group are also added to the OpenShift groups as Annotations including:\n\n* Parent/child relationship between groups and their subgroups\n* Group attributes\n\n## CA Certificates\n\nSeveral providers allow for certificates to be provided in either a _ConfigMap_ or _Secret_ to communicate securely to the target host through the use of a property called `ca`.\n\nThe certificate can be added to a Secret called _keycloak-certs_ using the key `ca.crt` representing the certificate using the following command.\n\n```\noc create secret generic keycloak-certs --from-file=ca.crt=\u003cfile\u003e\n```\n\nAn example of how the CA certificate can be added to the Keycloak provider is shown below:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: keycloak-groupsync\nspec:\n  providers:\n  - name: keycloak\n    keycloak:\n      realm: ocp\n      credentialsSecret:\n        name: keycloak-group-sync\n        namespace: group-sync-operator\n      ca:\n        kind: Secret\n        name: keycloak-certs\n        namespace: group-sync-operator\n        key: ca.crt\n      url: https://keycloak-keycloak-operator.apps.openshift.com\n```\n\nAlteratively, a _ConfigMap_ can be used instead instead of a _Secret_. This is useful when using the [Certificate injection using Operators](https://docs.openshift.com/container-platform/latest/networking/configuring-a-custom-pki.html#certificate-injection-using-operators_configuring-a-custom-pki) feature.\n\nThe following command can be used to create a _ConfigMap_ containing the certificate:\n\n```shell\noc create configmap keycloak-certs --from-file=ca.crt=\u003cfile\u003e\n```\n\nAn example of how the CA certificate can be added to the Keycloak provider is shown below:\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: keycloak-groupsync\nspec:\n  providers:\n  - name: keycloak\n    keycloak:\n      realm: ocp\n      credentialsSecret:\n        name: keycloak-group-sync\n        namespace: group-sync-operator\n      ca:\n        kind: ConfigMap\n        name: keycloak-certs\n        namespace: group-sync-operator\n        key: ca.crt\n      url: https://keycloak-keycloak-operator.apps.openshift.com\n```\n\n## Scheduled Execution\n\nA cron style expression can be specified for which a synchronization event will occur. The following specifies that a synchronization should occur nightly at 3AM\n\n```yaml\napiVersion: redhatcop.redhat.io/v1alpha1\nkind: GroupSync\nmetadata:\n  name: keycloak-groupsync\nspec:\n  schedule: \"0 3 * * *\"\n  providers:\n  - ...\n```\n\nIf a schedule is not provided, synchronization will occur only when the object is reconciled by the platform.\n\n## Accessing Secrets and ConfigMaps in Other Namespaces\n\nBy default, the operator monitors resources in the namespace that it has been deployed within. This is defined by setting the `WATCH_NAMESPACE` environment variable. Support is available for accessing ConfigMaps and Secrets in other namespaces so that existing resources may be utilized as desired.\n\nTo enable the operator to access resources across multiple, set the environment variable with a comma separate list of namespaces that include the namespace the operator is deployed within and any additional namespaces that are desired.\n\nTo make use of this feature when deploying through the Operator Lifecycle Manager, set the following configuration on the `Subscription` resource:\n\n```yaml\napiVersion: operators.coreos.com/v1alpha1\nkind: Subscription\nmetadata:\n  name: group-sync-operator\n  namespace: group-sync-operator\nspec:\n  channel: alpha\n  installPlanApproval: Automatic\n  name: group-sync-operator\n  source: community-operators\n  sourceNamespace: openshift-marketplace\n  config:\n    env:\n      - name: WATCH_NAMESPACE\n        value: \"\u003ccomma separated list of namespaces\u003e\"\n```\n\n## Deploying the Operator\n\nThis is a namespace level operator that you can deploy in any namespace. However, `group-sync-operator` is recommended.\n\nIt is recommended to deploy this operator via [`OperatorHub`](https://operatorhub.io/), but you can also deploy it using [`Helm`](https://helm.sh/).\n\n### Deploying from OperatorHub\n\nIf you want to utilize the Operator Lifecycle Manager (OLM) to install this operator, you can do so in two ways: from the UI or the CLI.\n\n### Multiarch Support\n\n| Arch  | Support  |\n|:-:|:-:|\n| amd64  | ✅ |\n| arm64  | ✅  |\n| ppc64le  | ✅  |\n| s390x  | ✅  |\n\n#### Deploying from OperatorHub UI\n\n* If you would like to launch this operator from the UI, you'll need to navigate to the OperatorHub tab in the console.\n* Search for this operator by name: `group sync operator`. This will then return an item for our operator and you can select it to get started. Once you've arrived here, you'll be presented with an option to install, which will begin the process.\n* After clicking the install button, you are presented with the namespace that the operator will be installed in. A suggested name of `group-sync-operator` is presented and can be created automatically at installation time.\n* Select the installation strategy you would like to proceed with (`Automatic` or `Manual`).\n* Once you've made your selection, you can select `Subscribe` and the installation will begin. After a few moments you can go ahead and check your namespace and you should see the operator running.\n\n#### Deploying from OperatorHub using CLI\n\nIf you'd like to launch this operator from the command line, you can use the manifests contained in this repository by running the following:\n\n```shell\noc new-project group-sync-operator\noc apply -f config/operatorhub -n group-sync-operator\n```\n\nThis will create the appropriate OperatorGroup and Subscription and will trigger OLM to launch the operator in the specified namespace.\n\n### Deploying with Helm\n\nHere are the instructions to install the latest release with Helm.\n\n```shell\noc new-project group-sync-operator\nhelm repo add group-sync-operator https://redhat-cop.github.io/group-sync-operator\nhelm repo update\nhelm install group-sync-operator group-sync-operator/group-sync-operator\n```\n\nThis can later be updated with the following commands:\n\n```shell\nhelm repo update\nhelm upgrade group-sync-operator group-sync-operator/group-sync-operator\n```\n\n## Metrics\n\nPrometheus compatible metrics are exposed by the Operator and can be integrated into OpenShift's default cluster monitoring. To enable OpenShift cluster monitoring, label the namespace the operator is deployed in with the label `openshift.io/cluster-monitoring=\"true\"`.\n\n```shell\noc label namespace \u003cnamespace\u003e openshift.io/cluster-monitoring=\"true\"\n```\n\n### Test metrics\n\n```sh\nexport operatorNamespace=group-sync-operator-local # or group-sync-operator\noc label namespace ${operatorNamespace} openshift.io/cluster-monitoring=\"true\"\noc rsh -n openshift-monitoring -c prometheus prometheus-k8s-0 /bin/bash\nexport operatorNamespace=group-sync-operator-local # or group-sync-operator\ncurl -v -s -k -H \"Authorization: Bearer $(cat /var/run/secrets/kubernetes.io/serviceaccount/token)\" https://group-sync-operator-controller-manager-metrics-service.${operatorNamespace}.svc.cluster.local:8443/metrics\nexit\n```\n\n## Development\n\n### Running the operator locally\n\n```shell\nmake install\nexport repo=redhatcopuser #replace with yours\ndocker login quay.io/$repo/group-sync-operator\nmake docker-build IMG=quay.io/$repo/group-sync-operator:latest\nmake docker-push IMG=quay.io/$repo/group-sync-operator:latest\noc new-project group-sync-operator-local\nkustomize build ./config/local-development | oc apply -f - -n group-sync-operator-local\nexport token=$(oc serviceaccounts get-token 'group-sync-operator-controller-manager' -n group-sync-operator-local)\noc login --token ${token}\nmake run ENABLE_WEBHOOKS=false\n```\n\n### Test helm chart locally\n\nDefine an image and tag. For example...\n\n```shell\nexport imageRepository=\"quay.io/redhat-cop/group-sync-operator\"\nexport imageTag=\"$(git -c 'versionsort.suffix=-' ls-remote --exit-code --refs --sort='version:refname' --tags https://github.com/redhat-cop/group-sync-operator.git '*.*.*' | tail --lines=1 | cut --delimiter='/' --fields=3)\"\n```\n\nDeploy chart...\n\n```shell\nmake helmchart IMG=${imageRepository} VERSION=${imageTag}\nhelm upgrade -i group-sync-operator-local charts/group-sync-operator -n group-sync-operator-local --create-namespace\n```\n\nDelete...\n\n```shell\nhelm delete group-sync-operator-local -n group-sync-operator-local\nkubectl delete -f charts/group-sync-operator/crds/crds.yaml\n```\n\n### Building/Pushing the operator image\n\n```shell\nexport repo=redhatcopuser #replace with yours\ndocker login quay.io/$repo/group-sync-operator\nmake docker-build IMG=quay.io/$repo/group-sync-operator:latest\nmake docker-push IMG=quay.io/$repo/group-sync-operator:latest\n```\n\n### Deploy to OLM via bundle\n\n```shell\nmake manifests\nmake bundle IMG=quay.io/$repo/group-sync-operator:latest\noperator-sdk bundle validate ./bundle --select-optional name=operatorhub\nmake bundle-build BUNDLE_IMG=quay.io/$repo/group-sync-operator-bundle:latest\ndocker login quay.io/$repo/group-sync-operator-bundle\ndocker push quay.io/$repo/group-sync-operator-bundle:latest\noperator-sdk bundle validate quay.io/$repo/group-sync-operator-bundle:latest --select-optional name=operatorhub\noc new-project group-sync-operator\noc label namespace group-sync-operator openshift.io/cluster-monitoring=\"true\"\noperator-sdk cleanup group-sync-operator -n group-sync-operator\noperator-sdk run bundle -n group-sync-operator quay.io/$repo/group-sync-operator-bundle:latest\n```\n\n### Releasing\n\n```shell\ngit tag -a \"\u003ctagname\u003e\" -m \"\u003ccommit message\u003e\"\ngit push upstream \u003ctagname\u003e\n```\n\nIf you need to remove a release:\n\n```shell\ngit tag -d \u003ctagname\u003e\ngit push upstream --delete \u003ctagname\u003e\n```\n\nIf you need to \"move\" a release to the current master\n\n```shell\ngit tag -f \u003ctagname\u003e\ngit push upstream -f \u003ctagname\u003e\n```\n\n### Cleaning up\n\n```shell\noperator-sdk cleanup group-sync-operator -n group-sync-operator\noc delete operatorgroup operator-sdk-og\noc delete catalogsource group-sync-operator-catalog\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-cop%2Fgroup-sync-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredhat-cop%2Fgroup-sync-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-cop%2Fgroup-sync-operator/lists"}