Gerrit must be registered as client with the CloudFoundry User Account and Authentication (UAA) Server that acts as OAuth 2 authentication and authorization backend.
The following sequence assumes that the UAA client application (uaac) is installed. It will create a client with name gerrit.
uaac target <URL of the UAA server>
uaac token client get admin
uaac client add gerrit
--authorities uaa.resource
--authorized_grant_type authorization_code,refresh_token,password
--scope openid
--autoapprove openid
--access_token_validity <time in seconds>
--redirect_uri <URL of the Gerrit server>/oauth
--secret <secret>
Make sure to choose a reasonable access token validity if you want to use access tokens to authenticate Git over HTTP communication. If tokens expire frequently using them with a native Git client might be cumbersome. On the other side, acccess tokens should be treated like passwords and should be changed from time to time for security reasons.
Make sure to choose a strong password for secret.
The configuration of the @PLUGIN@ plugin is done in the gerrit.config file.
[auth] type = OAUTH gitBacicAuth = true gitOAuthProvider = cfoauth:cfoauth [plugin "@PLUGIN@"] serverUrl = <URL of the UAA server> clientId = "<client id>" clientSecret = "<client secret>" verifySignatures = true
The type must be set to OAUTH.
When the gitBasicAuth parameter is set to true, the UAA will be used to also authenticate Git over HTTP communication. If there are multiple OAuth providers installed that are capable of authenticating Git over HTTP traffic, add the parameter gitOAuthProvider = cfoauth:cfoauth to select the @PLUGIN@ plugin as default OAuth provider.
For Git over HTTP communication the plugin accepts passwords and OAuth2 access tokens sent in an Authorization header following the BASIC authentication scheme (RFC 2617 section 2). The plugin will pass credentials directly to UAA for verification.
The serverUrl must point to the UAA server and include the context path, e.g http(s)://example.org/uaa.
The parameters clientId and clientSecret must match the name and password of the Gerrit client as registered with the UAA server.
UAA issues so-called JSON Web Tokens, which include a signature. By default, the @PLUGIN@ plugin will verify signatures of access tokens it received from UAA. Both HMACSHA256 and SHA256withRSA signatures are supported given that the underlying Java runtime provides the necessary ciphers. If that is not the case you might switch off the verification by setting the parameter verifySignatures to false. Note that this is strongly discouraged for security reasons.
The @PLUGIN@ plugin can also be configured during setting up Gerrit with the init command:
java -jar gerrit.war init -d <site>
[...]
*** Cloud Foundry UAA OAuth 2.0 Authentication Provider
***
UAA server URL [http://localhost:8080/uaa]: <serverUrl>
Client id [gerrit]: <clientId>
Client secret : <clientSecret>
confirm password : <clientSecret>
Verify token signatures [Y/n]? <verifySignatures>