Author: Sheng Jiang/shengjiang3, Eric Liu/LiuShuaiyi
Date: Oct 30, 2023
Proposes an approach to delegate Authentication decisions to external authentication authority in Harbor.
Currently, Harbor supports the OIDC protocol for authentication. An organization can configure Harbor to use an OIDC identity provider to provider authentication. However, there are some scenarios where additional support is needed, for example:
- If SAML or LDAP is used for the identity provider.
- If more than one OIDC provider needs to be used.
- Integrating Harbor with Single Sign-On (SSO) within an organization. For example, if the organization runs Harbor behind a reverse proxy (e.g- Istio) that federates identity providers (e.g- Dex).
Add another authentication option, letting the identity provider authenticate and issue an identity token while Harbor assumes the role of an application that consumes the identity token. Harbor would act as an OIDC token verifier. The goal is to allow Harbor to plug in to an upstream OIDC identity proxy allowing an SSO credential to authenticate with Harbor.
This opens up the use case where an identity proxy (such as Dex) can be configured to support multiple identity providers and pass on an identity token that is used by Harbor.
Alternatively, Harbor could be integrated as a proxied application running behind NGINX. NGINX can be configured to provide SSO by acting as the relying party to an OIDC identity provider. As a result, the identity token passed by NGINX could also be used as the identity of the user inside of Harbor.
Identity Aware proxy (IAP) - A reverse proxy that provides authentication. Also known as auth proxy. Identity token (ID token) - Artifact that proves that the user has been authenticated (source).
The new authentication option allows Harbor to trust the identity tokens issued by an identity aware proxy (such as Dex). The identity aware proxy is OIDC compatible. As such, Harbor is to be configured to fetch the JWKS from the identity aware proxy and to use the JWKS to verify the ID tokens issued by the identity aware proxy. Once the token is verified and validated, Harbor can use the identity inside the ID token as the user identity.
This is a slight deviation from the existing OIDC authentication mode where Harbor is directly configured to authenticate with the identity provider.
Since the new authentication mode in Harbor plays the role as an OIDC verifier, the following OIDC attributes are needed:
- Name: The name of the OIDC provider.
- Issuer URL: The identity provider's URL. This is used to locate the OIDC discovery document typically found at /.well-known/openid-configuration.
- Expected Audiences (optional): A comma separated list of identifiers that Harbor is recognized by. The audience claim in the JWT should contain one of the audiences configured in the list.
- User claim: The claim in the JWT to use as the user name. The default is the
subclaim in the OIDC specification. - Groups claim: The claim in the JWT to locate the user’s groups.
- Certificate authority data: base64 encoded PEM encoded certificate for the identity proxy.
- Header name: HTTP header to get the ID token.
enable_session_cookie[Optional]: When set totrue, after successful identity aware proxy authentication, Harbor will assign the user a cookie. As a result, the identity aware proxy will only have to provide the header to the login endpoint. The cookie will be used for authenticating all other routes.
The identity aware proxy should be able to be configured using the portal and/or the API.
In the Identity Aware Proxy authentication mode, Harbor will look for the ID token in the Authorization header (Authorization: Bearer ).
- The token will be a JWT Bearer token.
- The token will be issued by the IAP after the user has authenticated through the IAP.
- The token will be signed using the private key corresponding to the public keys available in the JWKS endpoint.
The user contained in the ID token should only be used after verifying and validating the ID token:
- Verify the signature of the JWT using the JWKS.
- Harbor can periodically refresh the JWKS.
- Fetch the JWKS if a JWT with an unknown key ID is received.
- Back off if the JWKS was fetched recently to prevent too many requests to the proxy.
- Ensure that alg cannot be none.
- Validate that the token is not expired or not valid yet.
- Check the exp and nbf claims.
- Validate that the token is intended for Harbor.
- Check the aud claim for any of the expected audiences.
- The validated token can be used for authorization enforcement and user identification.
The ID token is a short lived token so each token should be verified and validated independently. The ID token cannot be refreshed by Harbor to get a new token.
The identity is obtained from the token by looking for the user and groups claim specified in the Identity Aware Proxy configuration.
The user claim specifies the claim in the JWT to obtain the user name from. The value in this claim is to be used to identify the user within Harbor (for example authorization policies). The user name in the user claim needs to be unique across the IAP.
The groups claim specifies the claim in the JWT to obtain the groups from. The groups claim value is in the form of a list.
The first time Harbor sees a token for a given user claim, Harbor can on-board the user into the Harbor database (is this necessary?). The user name in the user claim is the username to onboard with.
If the request has a valid bearer token, then the user should not be shown the Harbor login page and instead should be taken directly to the portal.
The user flow for CLI can follow the same flow as OIDC CLI flow. The user gets the CLI secret from the UI and uses the CLI secret in the docker CLI which means that the OIDC CLI flow should also support IAP.
The IAP issues ID tokens after authenticating the user credentials. The limitation is that the user must refresh the ID token in Harbor in order for the secret to remain valid since the IAP does not send the refresh token.
Once the user is authenticated and accessing the UI, the user can obtain the CLI secret and use the CLI secret.
-
Support for non-OIDC protocols such as SAML or LDAP.
-
Support for authorization by the identity provider.
-
Using access tokens from the OIDC provider.
Harbor auth proxy (link) uses Kubernetes token review to validate the token. However, Harbor auth proxy also relies on an endpoint that isn’t well documented. Since Harbor auth proxy already makes use of Kubernetes TokenReview to authenticate a token, an alternative to the Identity Aware Proxy would be support authentication via Kubernetes TokenReview as a first order option. Kubernetes TokenReview would operate as a webhook that Harbor can delegate authentication decisions to.
Required configurations:
- Host name: This is the Kubernetes API server evaluating the TokenReview.
- Certificate: Certificate establishing the TLS connection.
- Audiences (recommended): The audiences for tokens intended for Harbor.
- The token to authenticate is sent in the Authorization header as a bearer token.
- The TokenReview ensures that the token is intended for Harbor by checking the audience in the token if it is provided.
- The username and groups are provided in the TokenReview status upon successful authentication.
- Automatically onboard the user using the username if this is the first time the user has signed in.
- Skip the sign in page if the user is authenticated.
- The docker CLI sends the token to the Token Service in the authorization basic header.
- The username in the Authorization basic header is a filler string. The secret
contains the token.
- AWS uses a filler string for the user name: https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-cli.html
- Azure also uses a filler string for the user name: https://learn.microsoft.com/en-us/azure/container-registry/container-registry-authentication?tabs=azure-cli#az-acr-login-with---expose-token
Harbor lives behind an auth proxy that authenticates access to Harbor. The mechanism authenticating access through the auth proxy is not important. However, after authenticating access, the auth proxy passes the identity of the user as a string in a configurable header (e.g- X-AuthProxy-UserName).
Harbor would trust and use the user name passed in from the configurable header as the user name within Harbor. When Harbor gets a username that it has not seen before, Harbor should auto-onboard the user into the user database.
Configuration options:
- Header name (Required): This is the header where the username can be found.
- Allowed sources (Optional): List of hosts or IPs the auth proxy requests can be forwarded from.
Pros of IAP:
- Delegates authentication to an external identity authority. The external identity authority can manage the authentication logic so that Harbor only needs to verify and use the credentials.
- Harbor explicitly verifies the identity token against the published public keys.
Disadvantages of IAP:
- The Harbor issued access token depends on the ID token. Short lived ID token means that the user has to authenticate often.
This adds a new authentication method that doesn’t conflict with any existing ones.
- Create configuration items for auth proxy configuration, and update UI to enable the configuration via Portal.
- Create a table (separate from the OIDC table) for sub, username, CLI secret.
- Add security context to handle the id token.