Merge pull request #7818 from reasonerjt/oidc-user-guide

Update user guide for OIDC authentication
This commit is contained in:
Wenkai Yin 2019-05-16 12:48:20 +08:00 committed by GitHub
commit 76e0b40b71
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 70 additions and 1 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 97 KiB

BIN
docs/img/oidc_login.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/img/profile_dlg.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 125 KiB

BIN
docs/img/user_profile.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 79 KiB

View File

@ -29,6 +29,7 @@ This guide walks you through the fundamentals of using Harbor. You'll learn how
* [Working with Helm CLI](#working-with-helm-cli)
* [Online Garbage Collection.](#online-garbage-collection)
* [View build history.](#build-history)
* [Using CLI after login via OIDC based SSO](#using-oidc-cli-secret)
* [Manage robot account of a project.](#robot-account)
* [Using API Explorer](#api-explorer)
@ -48,7 +49,7 @@ Besides the above three roles, there are two system-wide roles:
* **Anonymous**: When a user is not logged in, the user is considered as an "Anonymous" user. An anonymous user has no access to private projects and has read-only access to public projects.
## User account
Harbor supports two authentication modes:
Harbor supports different authentication modes:
* **Database(db_auth)**
@ -73,6 +74,30 @@ Harbor supports two authentication modes:
Self-registration, deleting user, changing password and resetting password are not supported under LDAP/AD authentication mode because the users are managed by LDAP or AD.
* **OIDC Provider (oidc_auth)**
With this authentication mode, regular user will login to Harbor Portal via SSO flow.
After the system administrator configure Harbor to authenticate via OIDC (more details refer to [this section](#managing-authentication)),
a button `LOGIN VIA OIDC PROVIDER` will appear on the login page.
![oidc_login](img/oidc_login.png)
By clicking this button user will kick off the SSO flow and be redirected to the OIDC Provider for authentication. After a successful
authentication at the remote site, user will be redirected to Harbor. There will be an "onboard" step if it's the first time the user
authenticate using his account, in which there will be a dialog popped up for him to set his user name in Harbor:
![oidc_onboar](img/oidc_onboard_dlg.png)
This user name will be the identifier for this user in Harbor, which will be used in the cases such as adding member to a project, assigning roles, etc.
This has to be a unique user name, if another user has used this user name to onboard, user will be prompted to choose another one.
Regarding this user to use docker CLI, please refer to [Using CLI after login via OIDC based SSO](#using-oidc-cli-secret)
**NOTE:**
1. After the onboard process, you still have to login to Harbor via SSO flow, the `Username` and `Password` fields are only for
local admin to login when Harbor is configured authentication via OIDC.
2. Similar to LDAP authentication mode, self-registration, updating profile, deleting user, changing password and
resetting password are not supported.
## Managing projects
A project in Harbor contains all repositories of an application. No images can be pushed to Harbor before the project is created. RBAC is applied to a project. There are two types of projects in Harbor:
@ -249,6 +274,21 @@ You can change authentication mode between **Database**(default) and **LDAP** be
When using LDAP mode, user's self-registration is disabled. The parameters of LDAP server must be filled in. For more information, refer to [User account](#user-account).
![browse project](img/ldap_auth.png)
When using OIDC mode, user will login Harbor via OIDC based SSO. A client has to be registered on the OIDC provider and Harbor's callback URI needs to be associated to that client as a redirectURI.
![OIDC settings](img/oidc_auth_setting.png)
The settings of this auth mode:
* OIDC Provider Name: The name of the OIDC Provider.
* OIDC Provider Endpoint: The URL of the endpoint of the OIDC provider(a.k.a the Authorization Server in OAuth's terminology),
which must service the "well-known" URI for its configuration, more details please refer to https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest
* OIDC Client ID: The ID of client configured on OIDC Provider.
* OIDC Client Secret: The secret for this client.
* OIDC Scope: The scope values to be used during the authentication. It is the comma separated string, which must contain `openid`.
Normally it should also contain `profile` and `email`. For getting the refresh token it should also contain `offline_access`. Please check with the administrator of the OIDC Provider.
* Verify Certificate: Whether to check the certificate when accessing the OIDC Provider. if you are running the OIDC Provider with self-signed
certificate, make sure this value is set to false.
### Managing project creation
Use the **Project Creation** drop-down menu to set which users can create projects. Select **Everyone** to allow all users to create projects. Select **Admin Only** to allow only users with the Administrator role to create projects.
![browse project](img/new_proj_create.png)
@ -612,6 +652,35 @@ In Harbor portal, enter your project, select the repository, click on the link o
![build_ history](img/build_history.png)
## Using OIDC CLI secret
Having authenticated via OIDC SSO and onboarded to Harbor, you can use Docker/Helm CLI to access Harbor to read/write the artifacts.
As the CLI cannot handle redirection for SSO, we introduced `CLI secret`, which is only available when Harbor's authentication mode
is configured to OIDC based.
After logging into Harbor, click the drop down list to view user's profile:
![user_profile](img/user_profile.png)
You can copy your CLI secret via the dialog of profile:
![profile_dlg](img/profile_dlg.png)
After that you can authenticate using your user name in Harbor that you set during onboard process, and CLI secret as the password
with Docker/Helm CLI, for example:
```sh
docker login -u testuser -p xxxxxx jt-test.local.goharbor.io
```
When you click the "..." icon in the profile dialog, a button for generating new CLI secret will appear, and you can generate a new
CLI secret by clicking this button. Please be reminded one user can only have one CLI secret, so when a new secret is generated, the
old one becomes invalid at once.
**NOTE**:
Under the hood the CLI secret is associated with the ID token, and Harbor will try to refresh the token, so the CLI secret will
be valid after th ID token expires. However, if the OIDC Provider does not provide refresh token or the refresh fails for some
reason, the CLI secret will become invalid. In that case you can logout and login Harbor via SSO flow again so Harbor can get a
new ID token and the CLI secret will work again.
## Robot Account
Robot Accounts are accounts created by project admins that are intended for automated operations. They have the following limitations: