SAML

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.

Settings

• 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.

• 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

• The service provider assertion consumer service url will look like: http(s)://[mydomain]/user/saml/[Authentication Name]/acs.
• The service provider metadata url will look like: http(s)://[mydomain]/user/saml/[Authentication Name]/metadata.