Introduction
ZEDEDA supports OIDC (https://auth0.com/docs/protocols/oidc), a wrapper over Open Authorization (OAuth), a third-party authentication along with local user authentication.
Authentication is used as the basis for authorization. An authentication server provides a network service that ZEDEDA Cloud uses to authenticate the credentials.
We will use ZEDEDA Cloud as the Service Provider and the Authentication server as the Identity Provider for better understanding. The following illustration gives the authentication process flow, which is self-explanatory.
Setting up ZEDEDA Cloud as a client on authentication servers can be done using many identity providers. The client registration process must be completed by the user or resource owner. Following are a couple of identity providers examples:
- https://support.google.com/cloud/answer/6158849?hl=en (Google as an authentication server)
- https://developer.okta.com/docs/guides/implement-oauth-for-okta/create-oauth-app/ (Create an OAuth 2.0 app in Okta)
- https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-protect-backend-with-aad (Protect an API by using OAuth 2.0 with Azure Active Directory and API Management)
The callback URL for ZEDEDA (to be configured at the Identity provider) is <cluster>/oauth/callback. For example, zedcontrol.zededa.net/oauth/callback.
The user or resource owner must have the following attribute values to continue with this document:
- Client ID
- Client Secret
- OpenID Connect Endpoint
Once the user or resource owner has the required attributes (as mentioned above), which is a one time exercise, the following sections walk you through setting up OAuth for your ZEDEDA Enterprise, role management in ZEDEDA, toggle with OAuth and local authentications, and user logout mechanism in OAuth.
Enable OAuth for your ZEDEDA Enterprise
ZEDEDA onboards the Enterprise with local admin authentication. The user or resource owner can enable third-party authentication on a need basis. The local user login can be a fail-safe if there are configuration issues with your identity provider/s. This approach is helpful for any big organization where the auth server sets up a team, and the ZEDEDA Enterprise user team is separate.
Let's look at how to enable OAuth through ZEDEDA Cloud, by using local user authentication:
Step 1 > Log in to the ZEDEDA GUI (ZEDEDA Cloud)
Step 2 > Navigate to the Administration (
) icon of the top navigation.
Step 3 > Click on the Edit (
) icon.
Note: OpenID Connect Endpoint can be sourced from the open ID configuration link. For Google, click
https://accounts.google.com/.well-known/openid-configuration. For Okta, click https://xxx.okta.com
-replace xxx with your respective endpoint server, where Okta is hosted, as every company will have its okta instances.
- Step 4 > Enable the External Authentication Profile by checking the box.
-
Step 5 > Select 'OAuth' as the Profile Type. Fill in all the required and optional attribute details. Along with Client ID, Client Secret, and OpenID Connect Endpoint, the following attributes are also required to be updated:
- Profile Name
- Default Role for New Users
Some authentication servers allow role management via additional custom scopes for the Scope attribute. If your Identity Provider supports it, you can enter the scope name here to perform ZEDEDA role management from the authentication server. The value needs to map to a valid ZEDEDA role. The default role is assigned to all OAuth users in the absence of a role scope.
Role Management
ZEDEDA role management in OAuth is typically done using custom claims (key-value pair attributes). A custom claim can be configured on the authorization server, containing the ZEDEDA role name assigned to the user. By default, ZEDEDA looks for the 'roles' claim in the identity token. A custom claim for role management can also be configured in the authorization profile.
Some authorization servers like Okta allow role management to configure the users. The following example of how to enable custom groups to claim on Okta:
- Create a user group in Okta (This user group will be matched to a role in ZEDEDA, e.g., zededa-admin and zededa-users).
- Assign the groups to the application (in this example, vikas-test is the application).
- Next, go to the authorization server settings and add custom groups claim.
- The groups should now be part of the id_token sent to the client (ZEDEDA). ZEDEDA will use this information to assign roles to the user.
- The assumption here is that these roles are created during Enterprise onboard or later by an admin. This process cannot be automatic. The auth server drives only the assignment of roles.
Toggle with OAuth and Local Authentications
Enabling OAuth will disable the creation of the local users (Local users can still log in and use ZEDEDA even when an external profile is configured). However, the local user entries added before enabling OAuth are still present. When the OAuth is disabled, you can create local users as usual.
User Logout Mechanism with OAuth
When the user is logged out from ZEDEDA Enterprise, only the local session is deleted. They continue to be logged into their authentication server.