OpenID Connect Settings

GitBucket supports the OpenID Connect authentication since 4.21.0.

Prerequisite

Check if your IdP (OpenID Provider) satisfies the followings:

• A client ID and client secret must be given by the IdP.
• The IdP must provide its metadata on ISSUER_URL/.well-known/openid-configuration.
• The IdP must provide an email address by the email claim.
• The IdP should provide full name of a user by the name claim.
• The IdP may provide a username by the preferred_username claim.

Getting Started

Google Identity Provider (Google Apps)

Setup the Google Identity Provider:

1. Open https://console.developers.google.com/apis/credentials
2. Create an OAuth client ID.
   • Application type: web application
   • Authorized redirect URIs: http://localhost:8080/signin/oidc
3. Check the client ID and client secret of the OAuth client.

Setup your GitBucket:

1. Sign in as an administrator.
2. Open the system settings.
3. Turn on OpenID Connect and enter the followings:
   • Issuer: https://accounts.google.com
   • Client ID: See Google Identity Provider
   • Client secret: See Google Identity Provider
   • Expected signature algorithm: RS256
4. Sign out.
5. Sign in with OpenID Connect.

Note that any Google users can sign in to your GitBucket. Make sure restricted people can access to your GitBucket.

See also https://developers.google.com/identity/protocols/OpenIDConnect.

Azure AD

Set up the Azure AD identity provider:

1. In the Azure Active Directory admin center, go to Overview and copy the Tenant ID for later use below
2. From the App registrations pane, click New registration
3. Enter the following info:
   • Name: (e.g. "GitBucket")
   • Supported account types: single tenant, all tenants, or global
   • Redirect URI: http://localhost:8080/signin/oidc
4. Click Register
5. From the Overview pane, copy the Application (client) ID and save it for use below
6. From the Certificates & secrets pane, click New client secret and enter the following info:
   • Description: (e.g. "WebApp Server")
   • Expires: 1 year, 2 years, or never
7. Copy the automatically-generated key under the Value column for later use below
8. From the Token configuration pane, click Add optional claim, and select the following:
   • Token type: ID
   • Claim: email
9. Click the Add button

Set up GitBucket:

1. Sign in as an administrator
2. Open System settings and click the Authentication tab
3. Check OpenID Connect and enter the following:
   • Issuer: https://sts.windows.net/[tenant-id-from-the-first-step]/ (make sure to include the trailing slash)
   • Client ID: use the client ID copied from step 5
   • Client secret: use the generated key from step 7
   • Expected signature algorithm: RS256
4. Sign out.
5. Sign in with OpenID Connect.

Keycloak

Setup your Keycloak:

1. Create a new Client on your Keycloak.
   • Client ID: gitbucket
   • Client Protocol: OpenID Connect
   • Valid redirect URIs: http://localhost:8080/signin/oidc
   • Valid post logout redirect URIs: http://localhost:8080
   • Client authentication: On

Setup your GitBucket:

1. Sign in as an administrator.
2. Open the system settings.
3. Turn on OpenID Connect and enter the followings:
   • Issuer: https://keycloak.example.com/realms/YOUR_REALM (replace keycloak.example.com with your host name and YOUR_REALM with your realm)
   • Client ID: gitbucket
   • Client secret: See Credetials tab in Keycloak
   • Expected signature algorithm: RS256
4. Sign out.
5. Sign in with OpenID Connect.

How it works

GitBucket does the followings on the OpenID Connect authentication:

1. Try to extract the username for the identity from:
   • If the preferred_username claim is given, use it.
   • If the email claim is given, use first part of it (before @).
2. Check if the username already exists:
   • If the username already exists, raise an error.
   • If the username does not exist, create a user.
3. Federate the user and the identity (i.e. the pair of iss and sub claim).
4. Sign in as the user.

To migrate existing users from password login to federated login, entries must be added to the ACCOUNT_FEDERATION table that map the issuer and subject (sub) to the account in the ACCOUNT table.