Skip to content
GitRiverGitRiver
RU
Navigation

Authentication

Configuring sign-in methods: OAuth2, SAML, SCIM, LDAP, 2FA, access tokens

GitRiver supports several authentication methods: from simple login/password to corporate single sign-on via SAML. This section covers how to configure each of them.

Login and Password

The basic method. Works out of the box, no configuration needed. Users register themselves (unless disabled) or are created by an administrator.

To disable open registration: Administration -> System -> uncheck “Allow registration”.

Two-Factor Authentication (2FA)

2FA adds a second factor at login - a code from an app. Even if the password is compromised, access is impossible without the code.

Enabling for a User

  1. Open Settings (avatar -> gear icon) -> Security
  2. Click “Enable 2FA”
  3. Scan the QR code with an app (Google Authenticator, Authy, FreeOTP)
  4. Enter the 6-digit code from the app to confirm
  5. Save the 10 recovery codes - each can be used once if the phone is unavailable

How Login with 2FA Works

  1. The user enters their login and password
  2. If 2FA is enabled - a code field appears
  3. The user enters the code from the app (or a recovery code)
  4. Login is complete

Disabling

Settings -> Security -> “Disable 2FA” (password required).

OAuth2 Providers

OAuth2 allows users to sign in with external accounts: GitHub, GitLab, Google, or any OAuth2/OIDC-compatible provider.

When You Need It

  • Users already have accounts on GitHub/Google
  • You don’t want to manage separate passwords
  • You need automatic registration on first login

Configuration

  1. Open Administration -> OAuth
  2. Click “Add provider”
  3. Select the type: GitHub, GitLab, Google, or Generic (for any OIDC)
  4. Specify:
    • Client ID and Client Secret - obtain from the OAuth application settings at the provider
    • Scopes (optional) - permissions (defaults are standard for the provider)
  5. Save

A “Sign in with [provider]” button will appear on the login page.

For GitHub: create an OAuth App in Settings -> Developer settings -> OAuth Apps. Redirect URL: https://git.example.com/api/v1/auth/oauth/{provider_id}/callback.

SAML 2.0 (Max)

SAML provides corporate single sign-on through an Identity Provider: Okta, Azure AD, Keycloak, OneLogin, and others.

When You Need It

  • Your company has a centralized IdP
  • You need single sign-on (SSO) - one account for all services
  • You need automatic group synchronization from the IdP

Configuration in GitRiver

  1. Open Administration -> SAML SSO
  2. Click “Add provider”
  3. Fill in:
    • Name - how the button will appear on the login page
    • Provider Entity ID (IdP) - your IdP identifier
    • Login URL (SSO URL) - where to redirect the user for login
    • Logout URL (SLO URL) - for single logout (optional)
    • IdP Certificate - public certificate for signature verification
  4. Configure attribute mapping:
    • Username, email, display name, groups
  5. Optional: automatic registration and group synchronization
  6. Save

Configuration in the IdP

On the created provider page, you will find a link to the SP metadata (XML). Download it and upload it to your IdP, or specify manually:

  • ACS URL - https://git.example.com/api/v1/auth/saml/{id}/acs
  • Entity ID - from the SP metadata

SCIM 2.0 (Max)

SCIM automatically synchronizes users and groups from the IdP (Okta, Azure AD). When an employee is added in the IdP, they automatically appear in GitRiver. When removed, they are deactivated.

Configuration

  1. Open Administration -> SCIM
  2. Click “Create token”
  3. Save the token - it is shown only once
  4. In the IdP settings (Okta, Azure AD):
    • SCIM Base URL: https://git.example.com/scim/v2/
    • Bearer Token: the token from step 3
  5. Enable provisioning in the IdP

LDAP (Max)

LDAP allows signing in with credentials from a corporate directory (Active Directory, OpenLDAP). The user does not need to create a separate account in GitRiver.

Configuration via the Interface

  1. Open Administration -> LDAP
  2. Click “Configure” (or “Edit” if already configured)
  3. Fill in:
    • Server URL - ldap://host:389 or ldaps://host:636 (with TLS)
    • Bind DN - DN of the service account for searching (optional)
    • Password - service account password
    • Search Base - where to search for users (ou=users,dc=example,dc=com)
    • User Filter - how to find a user ((uid={login}) - {login} is replaced with the entered username)
    • Email Attribute - usually mail
  4. Click “Test connection” - GitRiver will try to connect and find users
  5. If the test succeeds - “Save”

How Login Works

  1. The user enters their login and password on the GitRiver login page
  2. GitRiver searches for the user in LDAP using the filter
  3. Attempts a bind with the found DN and the entered password
  4. If successful - creates (or updates) a local account and authorizes the user

Local passwords work as a fallback: if LDAP is unavailable, the user can sign in with a local password (if one was set).

Configuration via Config File

Alternatively, LDAP can be configured in gitriver.toml - see Configuration -> LDAP.

Corporate Sign-in and Max Seats

SAML, SCIM and LDAP are Max edition capabilities; Community does not have them. Two rules follow, and both are worth knowing before you buy.

Whoever signs in only through the directory needs a seat. An account with neither a password nor a linked OAuth sign-in, that is, one that signs in only through SAML or LDAP (which is what accounts created through SCIM or on first sign-in from the directory usually look like) works only with an assigned Max seat. Without a seat the sign-in goes through but no work is possible - not in the interface, not through the API, not over git - and GitRiver says that seats are assigned by the administrator. A seat is assigned on the user’s page (Administration -> Users); none is handed out on first sign-in. An account that has a password or a linked OAuth sign-in works as in Community without a seat - whichever way the person signed in this time.

Once the grace period ends, corporate sign-in closes. During the grace period everything works, and every signed-in user sees the warning with the date, not only the administrator. When it is over, sign-in through SAML and LDAP stops letting anyone in. Password and OAuth sign-in keep working, data stays where it is, and the installation runs as Community. The administrator can set a password for any account on its page, and GitRiver will not let the last administrator who signs in with a password be removed - so there is always someone to move people to passwords and to load a new licence.

The length of the grace period is recorded in the licence and depends on the subscription term - see Grace Period After Expiry and Pricing.

GitRiver as an OAuth2/OIDC provider

The instance can not only accept sign-in through external providers but also act as a provider for other services:

  • GET /.well-known/openid-configuration - the configuration;
  • GET /.well-known/jwks.json - the public keys.

id_token signing is RS256. The key is created on first start: the private part is stored encrypted in the database, the public one is served in JWKS. It needs no separate configuration and goes into a database backup together with the rest of the data.

Two operational rules follow:

  • jwt_secret cannot be changed without losing the signing key. It is decrypted with a key derived from it; after the secret changes the old signing key cannot be read, the instance creates a new one, and previously issued id_tokens stop verifying. Relying parties experience this as a one-off re-login.
  • Restoring the database from a backup restores the key too, so relying parties do not need to re-read JWKS after a restore.

A relying party must take the keys from jwks_uri and pick the one whose kid is named in the token header (rather than memorising a single key forever), verify the signature, iss, aud and exp, and then check nonce against the one sent in the authorisation request. An id_token issued on token refresh carries no nonce: the user does not take part in that exchange.

Access Tokens

Personal Access Tokens (PAT)

For automation: scripts, external CI/CD systems, docker login. More details in Quick Start -> Access Tokens.

Deploy Tokens

Tied to a specific repository. Used for Docker pull from production servers or external CI/CD systems.

  1. Open the repository -> Settings -> Deploy Tokens
  2. Click “Create”
  3. Specify the name, username for docker login, scopes, and expiration date

Session Management

Users can view their active sessions and terminate any of them.

Settings -> Security -> Active Sessions -> click “Terminate” next to a session.

The administrator can terminate any user’s session through user management.