OAuth2 Authorisation Enhancement using scopes

Problem to solve

We are in the process of implementing our own OAuth2 provider and we want to be able to integrate GitLab more closely with the available features of the OAuth2 protocol. We also believe that these enhancements could be beneficial for other Giltab users.

Intended users

Administrators, users

Further details

We would find it useful if we could use OAauth2 from our auth application for the following purposes:

• Identify users as internal/external - our use case would prefer for the user to be external by default and optionally internal, so if the scope is not present, then the user would be external and if present then s/he would become internal - equivalent.
• Identify users as administrator

Proposal

This could be achieved by - OAuth2 scopes, parameters in returned JWTs and parameters in the USERINFO API returned values.

Using OAuth2 SCOPEs

1. Add support for the SCOPE parameter in client_options for generic OmniAuth configuration.

OmniAuth configuration:

      client_options: {
        'site' => 'https://our.authorisation.application',
        'authorize_url' => '/dialog/authorise',
        'token_url' => '/oauth/token',
        'user_info_url' => '/api/userinfo',
	'scope' => 'gitlab gitlab-internal gitLab-administrator'
      }

2. The auth application would return at least one of the scopes based on the user settings within the OAuth2 request/response (https://tools.ietf.org/html/rfc6749#section-3.3).

3. Add specific configuration options:

   • gitlab_rails['omniauth_scope_internal'] - user is identified as internal. The logic would be that external is default and internal is opt-in.
   • gitlab_rails['omniauth_scope_admin'] - user is identified as administrator

Using JWTs

Optionally this could also be implemented using the JWT authorisation flow, where certain variables in the JWT would be configured to delimit the above-described functionality.

This would require more changes to our auth application but would be also viable. Then the new configuration could look like this:

• gitlab_rails['omniauth_jwt_internal'] - if present, the user is identified as internal. The logic would be that external is default and internal is opt-in.
• gitlab_rails['omniauth_jwt_admin'] - if present, the user is identified as administrator

Using USERINFO API parameters

If the OAuth2 scopes are not viable, then the same functionality could be achieved by predefined parameters in the userinfo API endpoint.

• gitlab_rails['omniauth_userinfo_internal'] - if present, the user is identified as internal. The logic would be that external is default and internal is opt-in.
• gitlab_rails['omniauth_userinfo_admin'] - if present, the user is identified as administrator

Permissions and Security

The proposal enhances the current security model and integrates it with OAuth2 world.

Documentation

This doc should be updated:

• https://docs.gitlab.com/ee/integration/omniauth.html
• https://docs.gitlab.com/ee/integration/oauth2_generic.html
• https://docs.gitlab.com/ee/administration/auth/jwt.html

Testing

To the best of my knowledge this change would not impose any security challenges.

Links / references

https://tools.ietf.org/html/rfc6749#section-3.3