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
- 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'
}
-
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).
-
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.