diff --git a/docs/img/oidc_auth_setting.png b/docs/img/oidc_auth_setting.png new file mode 100644 index 000000000..1e4eb54b0 Binary files /dev/null and b/docs/img/oidc_auth_setting.png differ diff --git a/docs/img/oidc_login.png b/docs/img/oidc_login.png new file mode 100644 index 000000000..1bf77656a Binary files /dev/null and b/docs/img/oidc_login.png differ diff --git a/docs/img/oidc_onboard_dlg.png b/docs/img/oidc_onboard_dlg.png new file mode 100644 index 000000000..6537ec0ae Binary files /dev/null and b/docs/img/oidc_onboard_dlg.png differ diff --git a/docs/img/profile_dlg.png b/docs/img/profile_dlg.png new file mode 100644 index 000000000..dc4408907 Binary files /dev/null and b/docs/img/profile_dlg.png differ diff --git a/docs/img/user_profile.png b/docs/img/user_profile.png new file mode 100644 index 000000000..38abeb5ab Binary files /dev/null and b/docs/img/user_profile.png differ diff --git a/docs/user_guide.md b/docs/user_guide.md index 0fe5c768e..a3d3cb889 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -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: