{"id":28535215,"url":"https://github.com/gerritcodereview/plugins_saml","last_synced_at":"2026-02-18T10:35:10.114Z","repository":{"id":84111878,"uuid":"221341804","full_name":"GerritCodeReview/plugins_saml","owner":"GerritCodeReview","description":"Plugin for Gerrit authentication with a SAML provider  - (mirror of https://gerrit.googlesource.com/plugins/saml)","archived":false,"fork":false,"pushed_at":"2025-10-01T23:50:08.000Z","size":1532,"stargazers_count":0,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-10-19T17:40:12.580Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://gerrit.googlesource.com/plugins/saml","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GerritCodeReview.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-13T00:54:17.000Z","updated_at":"2025-01-13T11:22:52.000Z","dependencies_parsed_at":"2024-02-26T10:49:41.540Z","dependency_job_id":"898a27d7-3606-408c-8ee7-54b0194c9be7","html_url":"https://github.com/GerritCodeReview/plugins_saml","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GerritCodeReview/plugins_saml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GerritCodeReview%2Fplugins_saml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GerritCodeReview%2Fplugins_saml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GerritCodeReview%2Fplugins_saml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GerritCodeReview%2Fplugins_saml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GerritCodeReview","download_url":"https://codeload.github.com/GerritCodeReview/plugins_saml/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GerritCodeReview%2Fplugins_saml/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29576633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T08:38:15.585Z","status":"ssl_error","status_checked_at":"2026-02-18T08:38:14.917Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-09T17:14:23.477Z","updated_at":"2026-02-18T10:35:05.102Z","avatar_url":"https://github.com/GerritCodeReview.png","language":"Java","readme":"# Gerrit SAML Authentication Filter\n\nThis filter allows you to authenticate to Gerrit using a SAML identity\nprovider.\n\n## Installation\n\nGerrit looks for 3 attributes (which are configurable) in the AttributeStatement:\n\n- **DisplayName:** the full name of the user.\n- **EmailAddress:** email address of the user.\n- **UserName:** username (used for ssh).\n\nIf any of these attributes is not found in the assertion, their value is\ntaken from the NameId field of the SAML assertion.\n\n### Setting Gerrit in your IdP\n\n- [Okta](okta/README.md)\n- [Keycloak](keycloak/README.md)\n- [ADFS](adfs/README.md)\n- [SimpleSamlPHP](simplesamlphp/README.md)\n\n### Download the plugin\n\nDownload Gerrit SAML plugin for the appropriate version of gerrit from the [Gerrit-CI](https://gerrit-ci.gerritforge.com/search/?q=saml)\ninto $gerrit_site/lib/.\n\n### Building the SAML filter\n\nThis authentication filter is built with Bazel.\n\n## Build in Gerrit tree\n\nClone or link this filter to the plugins directory of Gerrit's\nsource tree. Put the external dependency Bazel build file into\nthe Gerrit /plugins directory, replacing the existing empty one.\n\n```\n  cd gerrit/plugins\n  rm external_plugin_deps.bzl\n  ln -s @PLUGIN@/external_plugin_deps.bzl .\n```\n\nThen issue\n\n```\n  bazel build plugins/@PLUGIN@\n```\n\nThe output is created in\n\n```\n  bazel-bin/plugins/@PLUGIN@/@PLUGIN@.jar\n```\n\nThe @PLUGIN@.jar should be deployed to `gerrit_site/lib` directory:\n\n```\n cp bazel-bin/plugins/@PLUGIN@/@PLUGIN@.jar `$gerrit_site/lib`\n```\n\n__NOTE__: Even though the project is built as a Gerrit plugin, it must be loaded\nas a Servlet filter by Gerrit and thus needs to be located with the libraries and\ncannot be dynamically loaded like other plugins.\n\nThis project can be imported into the Eclipse IDE.\nAdd the plugin name to the `CUSTOM_PLUGINS` set in\nGerrit core in `tools/bzl/plugins.bzl`, and execute:\n\n```\n  ./tools/eclipse/project.py\n```\n\nHow to build the Gerrit Plugin API is described in the [Gerrit documentation](../../../Documentation/dev-bazel.html#_extension_and_plugin_api_jar_files).\n\n### Configure Gerrit to use the SAML filter:\nIn `$site_path/etc/gerrit.config` file, the `[httpd]` and `[gerrit]` sections should\ncontain:\n\n```\n[gerrit]\n    installModule = com.googlesource.gerrit.plugins.saml.Module\n[httpd]\n    filterClass = com.googlesource.gerrit.plugins.saml.SamlWebFilter\n```\n\n### Configure HTTP authentication for Gerrit:\n\nPlease make sure you are using Gerrit 2.11.5 or later.\n\nIn `$site_path/etc/gerrit.config` file, the `[auth]` section should include\nthe following lines:\n\n```\n[auth]\n\ttype = HTTP\n    logoutUrl = https://mysso.example.com/logout\n    httpHeader = X-SAML-UserName\n    httpEmailHeader = X-SAML-EmailHeader\n    httpExternalIdHeader = X-SAML-ExternalId\n```\n\nThe header names are used internally between the SAML plugin and Gerrit to\ncommunicate the user's identity.  You can use other names (as long as it will\nnot conflict with any other HTTP header Gerrit might expect).\n\n### Create a local keystore\n\nIn `$gerrit_site/etc` create a local keystore:\n\n```\nkeytool -genkeypair -alias pac4j -keypass pac4j-demo-password \\\n  -keystore samlKeystore.jks \\\n  -storepass pac4j-demo-password -keyalg RSA -keysize 2048 -validity 3650\n```\n\n### Configure SAML\n\nAdd a new `[saml]` section to `$site_path/etc/gerrit.config`:\n\n```\n[saml]\n    keystorePath = /path/to/samlKeystore.jks\n    keystorePassword = pac4j-demo-password\n    privateKeyPassword = pac4j-demo-password\n    metadataPath = https://mycompany.okta.com/app/hashash/sso/saml/metadata\n```\n\n**saml.metadataPath**: Location of IdP Metadata from your SAML identity provider.\nThe value can be a URL, or a local file (prefix with `file://`)\n\n**saml.keystorePath**: Path to the keystore created above. If not absolute,\nthe path is resolved relative to `$site_path`.\n\n**saml.privateKeyPassword**: Password protecting the private key of the generated\nkey pair (needs to be the same as the password provided throguh the `keypass`\nflag above.)\n\n**saml.keystorePassword**: Password that is used to protect the integrity of the\nkeystore (needs to be the same as the password provided throguh the `keystore`\nflag above.)\n\n**saml.maxAuthLifetime**: (Optional) Max Authentication Lifetime (secs) configuration.\n\nDefault is `86400`\n\n**saml.forceAuth**: (Optional) Whether to force authentication with the IdP, when\nthe session in Gerrit expires.\n\nDefault is `false`\n\n**saml.displayNameAttr**: Gerrit will look for an attribute with this name in\nthe assertion to find a display name for the user. If the attribute is not\nfound, the NameId from the SAML assertion is used instead.\n\nDefault is `DisplayName`\n\n**saml.computedDisplayName**: Set to compute display name attribute from first\nand last names.\n\nDefault is false.\n\n**saml.firstNameAttr**: Gerrit will look for an attribute with this name in\nthe assertion to find the first name of the user. Only used, when `computedDisplayName`\nis set to true. If the attribute is not found, the NameId from the SAML assertion\nis used instead.\n\nDefault is `FirstName`\n\n**saml.lastNameAttr**: Gerrit will look for an attribute with this name in\nthe assertion to find the last name of the user. Only used, when `computedDisplayName`\nis set to true. If the attribute is not found, the NameId from the SAML assertion\nis used instead.\n\nDefault is `LastName`\n\n**saml.emailAddressAttr**: Gerrit will look for an attribute with this name in\nthe assertion to find a the email address of the user. If the attribute is not\nfound, the NameId from the SAML assertion is used instead.\n\nDefault is `EmailAddress`\n\n**saml.userNameAttr**: Gerrit will look for an attribute with this name in the\nassertion to find a the email address of the user. If the attribute is not\nfound, the NameId from the SAML assertion is used instead.\n\nDefault is `UserName`\n\n**saml.serviceProviderEntityId**: SAML service provider entity id.\n\nDefault is not set.\n\n**saml.identityProviderEntityId**: SAML identity provider entity id.  When present\na `IDPSSODescriptor` is expected in the SAML metadata document.  When absent a\nsaml service provider with its `SPSSODescriptor` is assumed.\nThis value takes precedence over the value in **saml.serviceProviderEntityId**.\n\nDefault is not set.\n\n**saml.memberOfAttr**: Gerrit will look for an attribute with this name in the\nassertion to find the groups the user is member of.\n\nThe user will receive these groups prefixed with `saml/` in gerrit.  When the\ngroups do not exist, they will be created.  When a user its membership is removed\nthis group will also be removed from this user on his next login.\n\nAs group membership is only updated when a user logs in on the UI, so when a\nuser loses membership to a group in SAML, he will still be able to execute his\nrights as if he is part of that group as long as he does not log in to the UI.\nSo enabling this feature can be seen as a security risk in certain environments.\n\nWhen this attribute is not set or empty, SAML membership synchronization is disabled.\n\nDefault is not set.\n\n**saml.useNameQualifier**: By SAML specification, the authentication request must not contain a NameQualifier, if the SP entity is in the format nameid-format:entity. However, some IdP require that information to be present. You can force a NameQualifier in the request with the useNameQualifier parameter. For ADFS 3.0 support, set this to `false`.\n\nDefault is true.\n\n### Create SAML metadata offline\n\nThe SAML metadata file (`$SITE/data/saml/sp-metadata.xml`) will be created on the\nfirst login attempt, when the plugin has been installed. However, at that point\nauthentication would fail until the identity provider was configured using the\nmetadata file of Gerrit.\n\nTo avoid this period in which authentication is not possible, the metadata can\nbe created offline. To do so, a separate java binary has to be built:\n\n```sh\nbazelisk build //plugins/saml:SamlMetadataCreator_deploy.jar\n```\n\nThe resulting jar-file can then be used to create the metadata file based on the\nexisting gerrit.config:\n\n```sh\nbazel-bin/plugins/saml/SamlMetaDataCreator \\\n  -d $SITE \\    # Path to the Gerrit site\n  --overwrite   # Whether to overwrite any existing metadata file\n```\n\nThe resulting metadata will be printed to standard out and stored at\n`$SITE/data/saml/sp-metadata.xml`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerritcodereview%2Fplugins_saml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgerritcodereview%2Fplugins_saml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerritcodereview%2Fplugins_saml/lists"}