Commit 43d8dbae authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'update_doc' into 'master'

Update OAuth doc



See merge request !2589
parents 2e056d5e cbd550cf
## GitLab as OAuth2 authentication service provider
# GitLab as OAuth2 authentication service provider
This document is about using GitLab as an OAuth authentication service provider to sign into other services.
If you want to use other OAuth authentication service providers to sign into GitLab please see the [OAuth2 client documentation](../api/oauth2.md)
This document is about using GitLab as an OAuth authentication service provider
to sign in to other services.
OAuth2 provides client applications a 'secure delegated access' to server resources on behalf of a resource owner. Or you can allow users to sign in to your application with their GitLab.com account.
In fact OAuth allows to issue access token to third-party clients by an authorization server,
with the approval of the resource owner, or end-user.
Mostly, OAuth2 is using for SSO (Single sign-on). But you can find a lot of different usages for this functionality.
For example, our feature 'GitLab Importer' is using OAuth protocol to give an access to repositories without sharing user credentials to GitLab.com account.
Also GitLab.com application can be used for authentication to your GitLab instance if needed [GitLab OmniAuth](gitlab.md).
If you want to use other OAuth authentication service providers to sign in to
GitLab, please see the [OAuth2 client documentation](../api/oauth2.md).
GitLab has two ways to add new OAuth2 application to an instance, you can add application as regular user and through admin area. So GitLab actually can have an instance-wide and a user-wide applications. There is no defferences between them except the different permission levels.
## Introduction to OAuth
### Adding application through profile
Go to your profile section 'Application' and press button 'New Application'
[OAuth] provides to client applications a 'secure delegated access' to server
resources on behalf of a resource owner. In fact, OAuth allows an authorization
server to issue access tokens to third-party clients with the approval of the
resource owner, or the end-user.
![applications](img/oauth_provider_user_wide_applications.png)
OAuth is mostly used as a Single Sign-On service (SSO), but you can find a
lot of different uses for this functionality. For example, you can allow users
to sign in to your application with their GitLab.com account, or GitLab.com
can be used for authentication to your GitLab instance
(see [GitLab OmniAuth](gitlab.md)).
After this you will see application form, where "Name" is arbitrary name, "Redirect URI" is URL in your app where users will be sent after authorization on GitLab.com.
The 'GitLab Importer' feature is also using the OAuth protocol to give access
to repositories without sharing user credentials to your GitLab.com account.
![application_form](img/oauth_provider_application_form.png)
---
### Authorized application
Every application you authorized will be shown in your "Authorized application" sections.
GitLab supports two ways of adding a new OAuth2 application to an instance. You
can either add an application as a regular user or add it in the admin area.
What this means is that GitLab can actually have instance-wide and a user-wide
applications. There is no difference between them except for the different
permission levels they are set (user/admin).
![authorized_application](img/oauth_provider_authorized_application.png)
## Adding an application through the profile
At any time you can revoke access just clicking button "Revoke"
In order to add a new application via your profile, navigate to
**Profile Settings > Applications** and select **New Application**.
### OAuth applications in admin area
![New OAuth application](img/oauth_provider_user_wide_applications.png)
If you want to create application that does not belong to certain user you can create it from admin area
---
![admin_application](img/oauth_provider_admin_application.png)
In the application form, enter a **Name** (arbitrary), and make sure to set up
correctly the **Redirect URI** which is the URL where users will be sent after
they authorize with GitLab.
![New OAuth application form](img/oauth_provider_application_form.png)
---
When you hit **Submit** you will be provided with the application ID and
the application secret which you can then use with your application that
connects to GitLab.
![OAuth application ID and secret](img/oauth_provider_application_id_secret.png)
---
## OAuth applications in the admin area
To create an application that does not belong to a certain user, you can create
it from the admin area.
![OAuth admin_applications](img/oauth_provider_admin_application.png)
---
## Authorized applications
Every application you authorized to use your GitLab credentials will be shown
in the **Authorized applications** section under **Profile Settings > Applications**.
![Authorized_applications](img/oauth_provider_authorized_application.png)
---
As you can see, the default scope `api` is used, which is the only scope that
GitLab supports so far. At any time you can revoke any access by just clicking
**Revoke**.
[oauth]: http://oauth.net/2/ "OAuth website"
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment