Skip to content

Latest commit

 

History

History
242 lines (188 loc) · 7.61 KB

README.md

File metadata and controls

242 lines (188 loc) · 7.61 KB
Raw

Apricot

Apricot is a proxy for delegating LDAP requests to an OpenID Connect backend. The name is a slightly tortured acronym for: LDAP proxy for OpenID Connect.

Usage

Start the Apricot server on port 1389 by running:

python run.py --client-id "<your client ID>" --client-secret "<your client secret>" --backend "<your backend>" --port 1389 --domain "<your domain name>" --redis-host "<your Redis server>"

If you prefer to use Docker, you can edit docker/docker-compose.yaml and run:

docker compose up

from the docker directory.

Using Redis [Optional]

You can use a Redis server to store generated uidNumber and gidNumber values in a more persistent way. To do this, you will need to provide the --redis-host and --redis-port arguments to run.py.

Configure background refresh [Optional]

By default Apricot will refresh the LDAP tree whenever it is accessed and it contains data older than 60 seconds. If it takes a long time to fetch all users and groups, or you want to ensure that each request gets a prompt response, you may want to configure background refresh to have it periodically be refreshed in the background.

This is enabled with the --background-refresh flag, which uses the --refresh-interval parameter as the interval to refresh the ldap database.

Using TLS [Optional]

You can set up a TLS listener to communicate with encryption enabled over the configured port. To enable it you need to configure the tls port ex. --tls-port=1636, and provide a path to the pem files for the certificate --tls-certificate=<path> and the private key --tls-private-key=<path>.

Outputs

This will create an LDAP tree that looks like this:

dn: DC=<your domain>
objectClass: dcObject

dn: OU=users,DC=<your domain>
objectClass: organizationalUnit
ou: users

dn: OU=groups,DC=<your domain>
objectClass: organizationalUnit
ou: groups

Each user will have an entry like

dn: CN=<user name>,OU=users,DC=<your domain>
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: posixAccount
objectClass: top
<user data fields here>
memberOf: <DN for each group that this user belongs to>

Each group will have an entry like

dn: CN=<group name>,OU=groups,DC=<your domain>
objectClass: groupOfNames
objectClass: posixGroup
objectClass: top
<group data fields here>
member: <DN for each user belonging to this group>

Primary groups

❗ You can disable the creation of mirrored groups with the --disable-primary-groups command line option ❗

Apricot creates an associated group for each user, which acts as its POSIX user primary group.

For example:

dn: CN=sherlock.holmes,OU=users,DC=<your domain>
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: posixAccount
objectClass: top
...
memberOf: CN=sherlock.holmes,OU=groups,DC=<your domain>
...

will have an associated group

dn: CN=sherlock.holmes,OU=groups,DC=<your domain>
objectClass: groupOfNames
objectClass: posixGroup
objectClass: top
...
member: CN=sherlock.holmes,OU=users,DC=<your domain>
...

Mirrored groups

❗ You can disable the creation of mirrored groups with the --disable-mirrored-groups command line option ❗

Each group of users will have an associated group-of-groups where each user in the group will have its user primary group in the group-of-groups. Note that these groups-of-groups are not posixGroups as POSIX does not allow nested groups.

For example:

dn:CN=Detectives,OU=groups,DC=<your domain>
objectClass: groupOfNames
objectClass: posixGroup
objectClass: top
...
member: CN=sherlock.holmes,OU=users,DC=<your domain>
...

will have an associated group-of-groups

dn: CN=Primary user groups for Detectives,OU=groups,DC=<your domain>
objectClass: groupOfNames
objectClass: top
...
member: CN=sherlock.holmes,OU=groups,DC=<your domain>
...

This allows a user to make a request for "all primary user groups needed by members of group X" without getting a large number of primary user groups for unrelated users. To do this, you will need an LDAP request that looks like:

(&(objectClass=posixGroup)(|(CN=Detectives)(memberOf=Primary user groups for Detectives)))

which will return:

dn:CN=Detectives,OU=groups,DC=<your domain>
objectClass: groupOfNames
objectClass: posixGroup
objectClass: top
...
member: CN=sherlock.holmes,OU=users,DC=<your domain>
...

dn: CN=sherlock.holmes,OU=groups,DC=<your domain>
objectClass: groupOfNames
objectClass: posixGroup
objectClass: top
...
member: CN=sherlock.holmes,OU=users,DC=<your domain>
...

OpenID Connect

Instructions for specific OpenID Connect backends below.

Microsoft Entra

You will need to use the following command line arguments:

--backend MicrosoftEntra \
--entra-tenant-id "<your tenant ID>"

You will need to register an application to interact with Microsoft Entra. Do this as follows:

  • Create a new App Registration in your Microsoft Entra.
    • Set the name to whatever you choose (e.g. apricot)
    • Set access to Accounts in this organizational directory only.
    • Set Redirect URI to Public client/native (mobile & desktop) with a value of urn:ietf:wg:oauth:2.0:oob
  • Under Certificates & secrets add a New client secret
    • Set the description to whatever you choose (e.g. Apricot Authentication Secret)
    • Set the expiry time to whatever is relevant for your use-case
    • You must record the value of this secret at creation time, as it will not be visible later.
  • Under API permissions:
    • Enable the following permissions:
      • Microsoft Graph > User.Read.All (application)
      • Microsoft Graph > GroupMember.Read.All (application)
      • Microsoft Graph > User.Read.All (delegated)
    • Select this and click the Grant admin consent button (otherwise each user will need to manually consent)

Keycloak

You will need to use the following command line arguments:

--backend Keycloak \
--keycloak-base-url "<your hostname>/<path to keycloak>" \
--keycloak-domain-attribute "<the attribute used as your domain>" \
--keycloak-realm "<your realm>"

You will need to register an application to interact with Keycloak. Do this as follows:

  • Under the realm option Client scopes create a new scope, e.g. domainScope with:
    • Type: Default
    • Include in token scope: true
    • Save
  • In the created scope click Mappers > Configure new mapper and now create either
    • Hardcoded claim
      • => Every user gets the same domain
      • name: domain
      • token claim name: domain
      • claim value: <your domain>
    • User attribute
      • => Every user has an attribute for the domain
      • name: domain
      • user attribute: <the attribute used as your domain>
      • token claim name: domain
  • Create a new Client in your Keycloak instance.
    • Set the name to whatever you choose (e.g. apricot)
    • Enable Client authentication
    • Enable the following authentication flows and disable the rest:
      • Direct access grants
      • Service account roles
  • Under Credentials copy client secret
  • Under Service account roles:
    • Click on Assign role then Filter by clients
    • Assign the following roles:
      • realm-management > view-users
      • realm-management > manage-users
      • realm-management > query-groups
      • realm-management > query-users
  • Under Client scopes click Add client scope > domainScope. Make sure to select type Default