Skip to content
Try Gitea Cloud ☁️ for 30 days → Accelerate your Development & Deploys!
Support

SAML

Configuring Gitea as a SAML 2.0 Service Provider

Section titled “Configuring Gitea as a SAML 2.0 Service Provider”
  • Navigate to Site Administration > Identity & Access > Authentication Sources.
  • Click the Add Authentication Source button.
  • Select SAML as the authentication type.

SAML Auth Interface

  • Authentication Name (required)

    • The name of this authentication source (appears in the Gitea ACS and metadata URLs)
  • SAML NameID Format (required)

    • This specifies how Identity Provider (IdP) users are mapped to Gitea users. This option will be provider specific.
  • SAML Binding (required)

    • The type of SAML binding you want to use. Right now only HTTP-Redirect and HTTP-Post are supported.
    • It only selects how the AuthnRequest is sent to the IdP. It does not change the assertion consumer service, which is always advertised with the HTTP-POST binding.
  • Icon URL (optional)

    • URL of an icon to display on the Sign-In page for this authentication source.
  • Identity Provider Metadata URL (optional if XML set)

    • The URL of the IdP metadata endpoint.
    • This field must be set if Identity Provider Metadata XML is left blank.
  • Identity Provider Metadata XML (optional if URL set)

    • The XML returned by the IdP metadata endpoint.
    • This field must be set if Identity Provider Metadata URL is left blank.
  • [Insecure] Skip Assertion Signature Validation (optional)

    • This option is not recommended and disables integrity verification of IdP SAML assertions.
  • Service Provider Certificate (optional)

    • X.509-formatted certificate (with Service Provider Private Key) used for signing SAML requests.
    • A certificate will be generated if this field is left blank.
  • Service Provider Private Key (optional)

    • DSA/RSA private key (with Service Provider Certificate) used for signing SAML requests.
    • A private key will be generated if this field is left blank.
  • Email Assertion Key (optional)

    • The SAML assertion key used for the IdP user’s email (depends on provider configuration).
  • Name Assertion Key (optional)

    • The SAML assertion key used for the IdP user’s nickname (depends on provider configuration).
  • Username Assertion Key (optional)

    • The SAML assertion key used for the IdP user’s username (depends on provider configuration).
  • Group Assertion Key (optional)

    • The SAML assertion key used for the IdP user’s group names (depends on provider configuration).
  • Group assertion value for administrator users (optional - requires group assertion key above)

    • If not empty, users with the same group assertion value will be administrator users.
  • Group assertion value for restricted users (optional - requires group assertion key above)

    • If not empty, users with the same group assertion value will be restricted users.
  • Map assertion groups to Organization teams (optional - requires group assertion key above)

    • A JSON map. Should be like:
    {
    "GroupAssertionValue": {
    "GiteaOrgName": ["GiteaOrgTeamName1", "GiteaOrgTeamName2"]
    }
    }
  • Enable Auto Registration (optional)

    • If checked, the corresponding user will be automatically created in Gitea after first sign in. The user’s username and email come from the assertion.

Configuring a SAML 2.0 Identity Provider to use Gitea

Section titled “Configuring a SAML 2.0 Identity Provider to use Gitea”
  • The service provider assertion consumer service url will look like: http(s)://[mydomain]/user/saml/[Authentication Name]/acs.
  • The ACS is advertised in the service provider metadata with the HTTP-POST binding, whatever SAML Binding is set to. The SAML profiles do not allow the response to be sent with the HTTP-Redirect binding, so an IdP that follows the metadata posts the assertion to the ACS.

SAML sign-in works like OAuth2 sign-in:

  • Account linking: with ACCOUNT_LINKING set to auto or login in the [oauth2_client] section, a SAML identity can be linked to an existing account, and a new account can be registered from the link page. The group settings of the source (administrator, restricted, team mapping) are applied when the identity is linked.
  • Primary sign-in method: a SAML source can be set as the Primary sign-in method in its settings. The sign-in page shows it first and highlighted as the recommended method. Only one source can be primary, and deactivating it unsets the setting.
  • Automatic redirect: when a single SAML source is the only way to sign in (no password form, no OAuth2, OpenID, passkey or SSPI), the sign-in page redirects to the IdP directly. It does not redirect after a failed sign-in, so a rejected sign-in cannot loop with the IdP. If another sign-in method is also available, for example a second provider, the sign-in page is shown so that every option stays visible.
  • Local sign-in for administrators only: with LOCAL_LOGIN_MODE = admin_only in the [service] section, a non-administrator who enters a correct password is rejected before the account is activated, so it does not take a license seat.
  • Security settings: the accounts a user has linked through SAML are listed on Settings > Security, with the icon of the source or a default lock icon.
  • The service provider metadata url will look like: http(s)://[mydomain]/user/saml/[Authentication Name]/metadata.