Group Sync Operator

Synchronizes groups from external providers into OpenShift

Overview

The OpenShift Container Platform contains functionality to synchronize groups found in external identity providers into the platform. Currently, this functionality is limited to LDAP only. This operator is designed to integrate with external providers in order to provide new solutions.

Group Synchronization is facilitated by creating a GroupSync resource. The following describes the high level schema for this resource:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: example-groupsync
spec:
  providers:
    - <One or more providers to synchronize>

Deploying the Operator

Use the following steps to deploy the operator to an OpenShift cluster

Assuming that you are authenticated to the cluster, create a new project called group-sync-operator .

oc new-project group-sync-operator

. 2. Clone the project locally and changed into the project . .

git clone https://github.com/redhat-cop/group-sync-operator.git
cd group-sync-operator
oc apply -f deploy/crds/redhatcop.redhat.io_groupsyncs_crd.yaml
oc apply -n group-sync-operator -f deploy/service_account.yaml
oc apply -n group-sync-operator -f deploy/clusterrole.yaml
oc apply -n group-sync-operator -f deploy/clusterrole_binding.yaml
oc apply -n group-sync-operator -f deploy/role.yaml
oc apply -n group-sync-operator -f deploy/role_binding.yaml
oc apply -n group-sync-operator -f deploy/operator.yaml

Authentication

In 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:

credentialsSecret:
  name: <secret_name>
  namespace: <secret_namespace>

Providers

Integration with external systems is made possible through a set of pluggable external providers. The following providers are currently supported:

The following sections describe the configuration options available for each provider

Azure

Groups contained within Azure Active Directory can be synchronized into OpenShift. The following table describes the set of configuration options for the Azure provider:

Name	Description	Defaults	Required
`credentialsSecret`	Name of the secret containing authentication details (See below)		Yes
`groups`	List of groups to filter against		No

The following is an example of a minimal configuration that can be applied to integrate with a Azure provider:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: azure-groupsync
spec:
  providers:
  - name: azure
    azure:
      credentialsSecret:
        name: azure-group-sync
        namespace: group-sync-operator

Authenticating to Azure

Authentication to Azure can be performed using Service Principal with access to query group information in Azure Active Directory. A secret must be created in the same namespace that contains the GroupSync resource:

The following keys must be defined in the secret

AZURE_SUBSCRIPTION_ID - Subscription ID
AZURE_TENANT_ID - Tenant ID
AZURE_CLIENT_ID - Client ID
AZURE_CLIENT_SECRET - Client Secret

The secret can be created by executing the following command:

oc create secret generic azure-group-sync --from-literal=AZURE_SUBSCRIPTION_ID=<AZURE_SUBSCRIPTION_ID> --from-literal=AZURE_TENANT_ID=<AZURE_TENANT_ID> --from-literal=AZURE_CLIENT_ID=<AZURE_CLIENT_ID> --from-literal=AZURE_CLIENT_SECRET=<AZURE_CLIENT_SECRET>

GitHub

Teams stored within a GitHub organization can be synchronized into OpenShift. The following table describes the set of configuration options for the GitHub provider:

Name	Description	Defaults	Required
`caSecret`	Reference to a secret containing a SSL certificate to use for communication (See below)		No
`credentialsSecret`	Reference to a secret containing authentication details (See below)		Yes
`insecure`	Ignore SSL verification	`false`	No
`organization`	Organization to synchronize against		Yes
`teams`	List of teams to filter against		No
`url`	Base URL for the GitHub or GitHub Enterprise host (Must contain a trailing slash)		No

The following is an example of a minimal configuration that can be applied to integrate with a Github provider:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: github-groupsync
spec:
  providers:
  - name: github
    github:
      organization: ocp
      credentialsSecret: 
        name: github-group-sync
        namespace: group-sync-operator

Authenticating to GitHub

Authentication to GitHub can be performed using an OAuth Personal Access Token or a Username and Password (Note: 2FA not supported). A secret must be created in the same namespace that contains the GroupSync resource:

When using an OAuth token, the following key is required:

token - OAuth token

The secret can be created by executing the following command:

oc create secret generic github-group-sync --from-literal=token=<token>

The following keys are required for username and password:

username - Username for authenticating with GitHub
password - Password for authenticating with GitHub

The secret can be created by executing the following command:

oc create secret generic github-group-sync --from-literal=username=<username> --from-literal=password=<password>

GitLab

Groups stored within a GitLab can be synchronized into OpenShift. The following table describes the set of configuration options for the GitLab provider:

Name	Description	Defaults	Required
`caSecret`	Reference to a secret containing a SSL certificate to use for communication (See below)		No
`credentialsSecret`	Reference to a secret containing authentication details (See below)		Yes
`insecure`	Ignore SSL verification	'false'	No
`groups`	List of groups to filter against		No
`url`	Base URL for the GitLab instance	`https://gitlab.com`	No

The following is an example of a minimal configuration that can be applied to integrate with a Github provider:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: gitlab-groupsync
spec:
  providers:
  - name: gitlab
    gitlab:
      credentialsSecret:
        name: gitlab-group-sync
        namespace: group-sync-operator

Authenticating to GitLab

Authentication to GitLab can be performed using an OAuth Personal Access Token or a Username and Password (Note: 2FA not supported). A secret must be created in the same namespace that contains the GroupSync resource:

When using an OAuth token, the following key is required:

token - OAuth token

The secret can be created by executing the following command:

oc create secret generic gitlab-group-sync --from-literal=token=<token>

The following keys are required for username and password:

username - Username for authenticating with GitLab
password - Password for authenticating with GitLab

The secret can be created by executing the following command:

oc create secret generic gitlab-group-sync --from-literal=username=<username> --from-literal=password=<password>

LDAP

Groups stored within an LDAP server can be synchronized into OpenShift. The LDAP provider implements the included features of the Syncing LDAP groups feature and makes use of the libraries from the OpenShift Command Line tool to streamline the migration to this operator based implementation.

The configurations of the three primary schemas (rfc2307, activeDirectory and augmentedActiveDirectory) can be directly migrated as is without any modification.

Name	Description	Defaults	Required
`caSecret`	Reference to a secret containing a SSL certificate to use for communication (See below)		No
`credentialsSecret`	Reference to a secret containing authentication details (See below)		Yes
`insecure`	Ignore SSL verification	'false'	No
`groupUIDNameMapping`	User defined name mapping		No
`rfc2307`	Configuration using the rfc2307 schema		No
`activeDirectory`	Configuration using the activeDirectory schema		No
`augmentedActiveDirectory`	Configuration using the activeDirectory schema		No
`url`	Connection URL for the LDAP server	`https://gitlab.cldap://ldapserver:389om`	No
`whitelist`	Explicit list of groups to synchronize		No
`blacklist`	Explicit list of groups to not synchronize		No

The following is an example using the rfc2307 schema:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: ldap-groupsync
spec:
  providers:
  - ldap:
      credentialsSecret:
        name: ldap-group-sync
        namespace: group-sync-operator
      insecure: true
      rfc2307:
        groupMembershipAttributes:
        - member
        groupNameAttributes:
        - cn
        groupUIDAttribute: dn
        groupsQuery:
          baseDN: ou=Groups,dc=example,dc=com
          derefAliases: never
          filter: (objectClass=groupofnames)
          scope: sub
        tolerateMemberNotFoundErrors: true
        tolerateMemberOutOfScopeErrors: true
        userNameAttributes:
        - cn
        userUIDAttribute: dn
        usersQuery:
          baseDN: ou=Users,dc=example,dc=com
          derefAliases: never
          scope: sub
      url: ldap://ldapserver:389
    name: ldap

The examples provided in the OpenShift documented referenced previously can be used to construct the schemas for the other LDAP synchronization types.

Authenticating to LDAP

A secret must be created in the same namespace that contains the GroupSync resource. It must contain the following keys:

username - Username (Bind DN) for authenticating with the LDAP server
password - Password for authenticating with the LDAP server

The secret can be created by executing the following command:

oc create secret generic ldap-group-sync --from-literal=username=<username> --from-literal=password=<password>

Whitelists and Blacklists

Groups 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:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: ldap-groupsync
spec:
  providers:
  - ldap:
...
      whitelist:
      - cn=Online Corporate Banking,ou=Groups,dc=example,dc=com
...
    name: ldap

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: ldap-groupsync
spec:
  providers:
  - ldap:
...
      blacklist:
      - cn=Finance,ou=Groups,dc=example,dc=com
...
    name: ldap

Keycloak

Groups stored within Keycloak can be synchronized into OpenShift. The following table describes the set of configuration options for the Keycloak provider:

Name	Description	Defaults	Required
`caSecret`	Reference to a secret containing a SSL certificate to use for communication (See below)		No
`credentialsSecret`	Reference to a secret containing authentication details (See below)		Yes
`groups`	List of groups to filter against		No
`insecure`	Ignore SSL verification	'false'	No
`loginRealm`	Realm to authenticate against	`master`	No
`realm`	Realm to synchronize		Yes
`scope`	Scope for group synchronization. Options are `one` for one level or `sub` to include subgroups	`sub`	No
`url`	URL Location for Keycloak		Yes

The following is an example of a minimal configuration that can be applied to integrate with a Keycloak provider:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: keycloak-groupsync
spec:
  providers:
  - name: keycloak
    keycloak:
      realm: ocp
      credentialsSecret:
        name: keycloak-group-sync
        namespace: group-sync-operator
      url: https://keycloak-keycloak-operator.apps.openshift.com

Authenticating to Keycloak

A secret must be created in the same namespace that contains the GroupSync resource. It must contain the following keys:

username - Username for authenticating with Keycloak
password - Password for authenticating with Keycloak

The secret can be created by executing the following command:

oc create secret generic keycloak-group-sync --from-literal=username=<username> --from-literal=password=<password>

Support for Additional Metadata (Beta)

Additional metadata based on Keycloak group are also added to the OpenShift groups as Annotations including:

Parent/child relationship between groups and their subgroups
Group attributes

CA Certificates

Each provider allows for certificates to be provided in a secret to communicate securely to the target host through the use of a property called caSecret.

The certificate can be added to a secret called keycloak-certs using the key ca.crt representing the certificate using the following command.

$ oc create secret generic keycloak-certs --from-file=ca.crt=<file>

An example of how the CA certificate can be added to the Keycloak provider is shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: keycloak-groupsync
spec:
  providers:
  - keycloak:
      realm: ocp
      credentialsSecret:
        name: keycloak-group-sync
        namespace: group-sync-operator
      caSecret:
        name: keycloak-certs
        namespace: group-sync-operator
        key: tls.crt
      url: https://keycloak-keycloak-operator.apps.openshift.com

Scheduled Execution

A cron style expression can be specified for which a synchronization event will occur. The following specifies that a synchronization should occur nightly at 3AM

apiVersion: redhatcop.redhat.io/v1alpha1
kind: GroupSync
metadata:
  name: keycloak-groupsync
spec:
  schedule: "0 3 * * *"
  providers:
  - ...

If a schedule is not provided, synchronization will occur only when the object is reconciled by the platform.

Local Development

Execute the following steps to develop the functionality locally. It is recommended that development be done using a cluster with cluster-admin permissions.

go mod download

optionally:

go mod vendor

Using the operator-sdk, run the operator locally:

oc apply -f deploy/crds/redhatcop.redhat.io_groupsyncs_crd.yaml
OPERATOR_NAME='group-sync-operator' operator-sdk run --local --watch-namespace ""

piggyvenus/group-sync-operator

Group Sync Operator

Overview

Deploying the Operator

Authentication

Providers

Azure

Authenticating to Azure

GitHub

Authenticating to GitHub

GitLab

Authenticating to GitLab

LDAP

Authenticating to LDAP

Whitelists and Blacklists

Keycloak

Authenticating to Keycloak

Support for Additional Metadata (Beta)

CA Certificates

Scheduled Execution

Local Development