Running Fettlecode

Sign-in and single sign-on

Who can make an account, and how to connect OpenID Connect, SAML, LDAP or Active Directory, and GitHub sign-in.

Who can make an account

The first account is made with the setup code and becomes the instance admin. After that, sign-up is closed, and people get in by:

an invitation from an organisation owner;
single sign-on, LDAP or GitHub, set up below (each can make accounts for new people, or only let existing ones in);
an account an admin makes on the command line (see Settings);
or, for an open instance, ALLOW_SIGNUP=true.

Everyone can add two-step sign-in and passkeys to their own account (see Your account).

OpenID Connect

For Keycloak, Authentik, Okta, Entra ID, Google and other OpenID Connect providers. In the provider, make a client with this redirect address (using the OIDC_ID you choose):

https://code.example.com/api/auth/oauth2/callback/keycloak

Then set:

OIDC_ID=keycloak
OIDC_NAME=Keycloak
OIDC_ISSUER=https://sso.example.com/realms/main
OIDC_CLIENT_ID=fettlecode
OIDC_CLIENT_SECRET=the-client-secret

The sign-in page then offers Sign in with Keycloak. For several providers, set OIDC_PROVIDERS instead, a JSON list: [{"id":"keycloak","name":"Keycloak","issuer":"…","clientId":"…","clientSecret":"…"}]. OIDC_ALLOW_SIGNUP=false † lets only people with an account sign in this way.

SAML

For Okta, Entra ID, Google Workspace, ADFS and other SAML identity providers.

Give your identity provider Fettlecode's metadata: https://code.example.com/api/auth/sso/saml2/sp/metadata?providerId=saml.
Download the identity provider's metadata XML, put it where the container can read it, and set SAML_IDP_METADATA to its path.

Setting	Default	What it does
`SAML_IDP_METADATA`	(off)	The identity provider's metadata file. Or set `SAML_ENTRY_POINT`, `SAML_IDP_ENTITY_ID` and `SAML_IDP_CERT` † together instead.
`SAML_NAME` †	`Single sign-on`	The button's name on the sign-in page.
`SAML_DOMAIN` †	(none)	Email domains (comma-separated) whose existing accounts SAML may sign in to.
`SAML_EMAIL_ATTR`, `SAML_NAME_ATTR` †	`email`, `displayName`	Which attributes hold the email and name.
`SAML_ALLOW_SIGNUP` †	`true`	Make accounts for new people.
`SAML_WANT_ASSERTIONS_SIGNED` †	`false`	Refuse assertions that aren't signed.

LDAP and Active Directory

People sign in with their directory username and password.

Setting	Default	What it does
`LDAP_URL`	(off)	Such as `ldaps://directory.example.com`.
`LDAP_BASE_DN`	(none)	Where to look for people, such as `dc=example,dc=com`.
`LDAP_BIND_DN`, `LDAP_BIND_PASSWORD`	(none)	An account to search with, if the directory needs one.
`LDAP_NAME` †	`Directory`	What the sign-in page calls it.
`LDAP_USER_FILTER` †	`uid`, `sAMAccountName` or `mail`	How to find someone, with `{username}` for what they typed.
`LDAP_NAME_ATTR`, `LDAP_MAIL_ATTR` †	`displayName`, `mail`	Which attributes hold the name and email.
`LDAP_ALLOW_SIGNUP` †	`true`	Make accounts for new people.
`LDAP_VERIFY_TLS` †	`true`	Check the directory's certificate. Turn off only for testing.

GitHub

Make an OAuth app on GitHub with the callback https://code.example.com/api/auth/callback/github, then set:

Setting	Default	What it does
`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`	(off)	The OAuth app's ID and secret.
`GITHUB_ALLOWED_ORGS` †	(none)	Members of these GitHub organisations (comma-separated) may make accounts.
`GITHUB_ALLOW_SIGNUP` †	`false`	Anyone with a GitHub account may make one.

With neither, GitHub sign-in works only for people who already have an account and connect GitHub in their settings.

† Add these to compose.yaml's environment: list too: see Settings.

Provisioning

To have your identity provider add and remove members of an organisation and keep its teams in step, use SCIM.