Once Devtron is installed, it has a built-in admin user with super admin privileges with unrestricted access to all Devtron resources. We recommended to use a user with super admin privileges for initial and global configurations only and then switch to local users or configure SSO integration.

Only users with super-admin privileges can create SSO configuration. Devtron uses Dex for authenticating a user against the identity provider.

To add/edit SSO configuration, go to the SSO Login Services section of Global Configurations.

Supported SSO Providers

Below are the SSO providers which are available in Devtron. Select one of the SSO providers (e.g., GitHub) to configure SSO:

Google GitHub GitLab Microsoft LDAP OpenID Connect OpenShift

Dex implements connectors that target specific identity providers for each connector configuration. You must have a created account for the corresponding identity provider and registered an app for client key and secret.

Refer the following documents for more detail.

• https://dexidp.io/docs/connectors/

• https://dexidp.io/docs/connectors/google/

1. Create new SSO Configuration

Make sure that you have a super admin access.

• Go to the Global Configurations → SSO Login Services and click any SSO Provider of your choice.

• In the URL field, enter the valid Devtron application URL where it is hosted.

• For providing redirectURI or callbackURI registered with the SSO provider, you can either select Configuration or Sample Script.

• Provide the client ID and client Secret of your SSO provider (e.g. If you select Google as SSO provider, then you must enter $GOOGLE_CLIENT_ID and $GOOGLE_CLIENT_SECRET in the client ID and client Secret respectively.)

• Select Save to create and activate SSO Login Service.

Note:

• Only single SSO login configuration can be active at one time. Whenever you create or update any SSO configuration, it will be activated and used by Devtron and previous configurations will be deleted.

• Except for the domain substring, URL and redirectURI remains same.

2. Update SSO Configuration

You can change SSO configuration anytime by updating the configuration and click Update. Note: In case of configuration change, all users will be logged out of Devtron and will have to login again.

3. Configuration Payload

• type : Any platform name such as (Google, GitLab, GitHub etc.)

• name : Identity provider platform name

• id : Identity provider platform which is a unique ID in string. (Refer to dexidp.io

• config : User can put connector details for this key. Platforms may not have same structure but common configurations are clientID, clientSecret, redirectURI.

• hostedDomains : Domains authorized for SSO login.

Next Steps

After configuring an SSO for authentication, you need to add users in Devtron, else your users won't be able to log in via SSO.

In case you have enabled auto-assign permissions in Microsoft or LDAP, relevant permission groups must also exist in Devtron for a successful login.

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

• View GitHub Documentation

• View Dex IdP Documentation

Authorization section describes how to authenticate and authorize access to resources, also managing role-based access levels in Devtron.

Access can be granted to a user via:

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• tenantID (required only if you want to use Azure AD for auto-assigning permissions)
• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

• View GitLab Documentation

• View Dex IdP Documentation

Prerequisites

• Install and configure Keycloak on your server or cloud environment.

• Create a new realm in Keycloak for your application.

Steps on Keycloak Admin Console

Creating a Client

Here, we will add Devtron as a client for using Keycloak SSO.

1. In the Admin Console, go to Clients and click Create client.
2. Within General Settings:

   • Enter devtron in the Client ID field. We will use this ID while configuring SSO later in Devtron.

   • Enter Devtron in the Name field.
3. Within Capability config, turn on Client Authentication.
4. Within Login settings, enter https://<DEVTRON_BASE_URL>/orchestrator/api/dex/callback in the following fields.

   • Valid redirect URIs

   • Valid post logout redirect URIs

   • Web origins

   Click here to know where to find DEVTRON_BASE_URL.
5. Click Save.

Getting Client Secret

Here, we will obtain the secret we need while configuring SSO in Devtron.

1. Go to the Credentials tab of the client you created.
2. Use the copy button next to the Client Secret field and paste it somewhere for future reference.

Creating Users

Here, we will create a user that can log in to Devtron via SSO. We will assign a username and password that the user can enter while logging in to Devtron via Keycloak SSO.

1. In the Admin Console, go to Users and click Add user.

2. Give a username (e.g., usertest) in the Username field and enter the user's email address (e.g., usertest@example.com) in the Email field.
3. Click Create. Your user creation will be successful.

4. Go to the Credentials tab of the user you created.
5. Click Set password.

6. Enter the password and confirm it.

7. Click Save.

Retrieving Issuer URL

Here, we will obtain the Issuer URL we need while configuring SSO in Devtron.

1. In the Admin Console, go to Realm settings.

2. In the General tab, scroll down to the Endpoints field, and click the OpenID Endpoint Configuration link.
3. This will open a new page, copy the value of the key named issuer, and paste it somewhere for future reference.

Steps on Devtron

Configuring OIDC SSO

Here, we will set up an OIDC SSO and enter the values we obtained in the previous section.

1. Go to Global Configurations → SSO Login Services → OIDC.
2. Below the URL field, take the help of the Click to use option to populate the exact URL if the displayed one is incorrect.
3. In the Configuration editor, do the following:

   • In the issuer field, paste the URL you got while retrieving issuer URL.

   • In the clientID field, paste the ID you entered while creating the client.

   • In the clientSecret field, paste the secret you got under client credentials tab.

   • In the redirectURI field, make sure to enter the same redirect URI you gave in step 4 of client creation.
4. Click Save or Update to activate Keycloak SSO login.

Adding Users

Here, we will add the user we created in the Keycloak Admin Console. If this step is skipped, the user might not be able to log in to Devtron via Keycloak.

1. Go to Global Configurations → Authorization → User Permissions.

2. Click + Add Users.
3. In the Email addresses field, enter the email address of the user you created in Keycloak.
4. Assign necessary permissions to this new user. Refer user permissions to know more.

5. Click Save.

Now, you may log out and test the Keycloak OIDC login method using the user credentials. Clicking the Login with Oidc button will land you on Keycloak's login page.

Sample Configuration

Values to fetch from LDAP

Devtron provides a sample configuration out of the box. Here are some values you need to fetch from your LDAP.

• bindDN

• bindPW

• baseDN

Reference

What is LDAP

Since LDAP supports creation of User Groups, this feature simplifies the onboarding process of organizations having a large headcount of users. It also eliminates repetitive permission assignment by automatically mapping your LDAP User groups to Devtron's Permission Groups during single sign-on (SSO) login.

If you've created user groups in LDAP, you can create corresponding permission groups in Devtron with the same names. When members of those user groups first log in to Devtron, they'll automatically inherit the permissions from their Devtron permission group. This means you can't manually adjust or add individual permissions for users mapped to a permission group.

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID
• clientSecret

Values to Provide

• redirectURI (already provided in SSO Login Services by Devtron)

Reference

• View Openshift Documentation

• View Dex IdP Documentation

API tokens are the access tokens for authentication. Instead of using username and password, it can be used for programmatic access to API. It allows users to generate API tokens with the desired access. Only super admin users can generate API tokens and see the generated tokens.

Generate API Token

To generate API tokens, go to Global Configurations -> Authorization -> API tokens and click Generate New Token.

• Enter a name for the token.

• Add Description.

• Select an expiration date for the token (7 days, 30 days, 60 days, 90 days, custom and no expiration).

• To select a custom expiration date, select Custom from the drop-down list. In the adjacent field, you can select your custom expiration date for the API token.

• You can assign permission to the token either with:

  • Super admin permission: To generate a token with super admin permission, select Super admin permission.

  • Specific permissions: Selecting Specific permissions option allows you to generate a token with a specific role for:

    • Devtron Apps

    • Helm Apps

    • Kubernetes Resources

    • Chart Groups

• Click Generate Token.

A pop-up window will appear on the screen from where you can copy the API token.

Use API Token

Once Devtron API token has been generated, you can use this token to request Devtron APIs using any API testing tool like Jmeter, Postman, Citrus. Using Postman here as an example.

Open Postman. Enter the request URL with POST method and under HEADERS, enter the API token as shown in the image below.

In the Body section, provide the API payload as shown below and click Send.

As soon as you click Send, the created application API will be triggered and a new Devtron app will be created as provided in the payload.

Update API Token

To set a new expiration date or to make changes in permissions assigned to the token, we need to update the API token in Devtron. To update the API token, click the token name or click on the edit icon.

To set a new expiration date, you can regenerate the API token. Any scripts or applications using this token must be updated. To regenerate a token, click Regenerate token.

A pop-up window will appear on the screen from where you can select a new expiration date.

Select a new expiration date and click Regenerate token.

This will generate a new token with a new expiration date.

To update API token permissions, give the permissions as you want to and click Update Token.

Delete API Token

To delete an API token, click delete icon. Any applications or scripts using this token will no longer be able to access the Devtron API.

Using the Permission groups, you can assign a user to a particular group and a user inherits all the permissions granted to the group.

The advantage of the Permission groups is to define a set of privileges like create, edit, or delete for the given set of resources that can be shared among the users within the group.

Add Group

Go to Global Configurations → Authorization → Permissions groups → Add group.

Enter the Group Name and Description.

Devtron Apps Permissions

In Devtron Apps option, you can provide access to a group to manage permission for custom apps created using Devtron.

Provide the information in the following fields:

You can add multiple rows for Devtron Apps permission.

Once you have finished assigning the appropriate permissions for the groups, Click Save.

Helm Apps Permissions

In Helm Apps option, you can provide access to a group to manage permission for Helm apps deployed from Devtron or outside Devtron.

Provide the information in the following fields:

You can add multiple rows for Devtron app permission.

Once you have finished assigning the appropriate permissions for the groups, Click Save.

Jobs

In Jobs option, you can provide access to a group to manage permission for jobs created using Devtron.

Provide the information in the following fields:

You can add multiple rows for Jobs permission.

Once you have finished assigning the appropriate permissions for the groups, Click Save.

Kubernetes Resources Permissions

To provide Kubernetes resource permission, click Add permission.

On the Kubernetes resource permission, provide the information in the following fields:

You can add multiple rows for Kubernetes resource permission.

Once you have finished assigning the appropriate permissions for the groups, Click Save.

Chart Group Permissions

In Chart group permission option, you can manage the access of groups for Chart Groups in your project.

Click Save once you have configured all the required permissions for the groups.

Edit Permissions Groups

You can edit the permission groups by clicking the downward arrow.

Edit the permission group.

Once you are done editing the permission group, click Save.

If you want to delete the groups with particular permission group, click Delete.

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

Like any enterprise product, Devtron supports fine grained access control to the resources based on:

1. Type of action allowed on Devtron resources (Create Vs View)

2. Sensitivity of the data (Editing image Vs Editing memory)

Role-based Access Levels

Devtron supports the following levels of access:

1. View only: User with View only access has the least privilege. This user can only view combination of environments, applications and helm charts on which access has been granted to the user. This user cannot view sensitive data like secrets used in applications or charts.

2. Build and Deploy: In addition to View only access, user with Build and deploy permission can build and deploy the image of the permitted applications and helm charts to the permitted environments.

3. Admin: User with Admin access can create, edit, delete and view permitted applications in the permitted projects.

4. Manager: User with Manager access can do everything that an Admin type user can do, in addition, they can also give and revoke access of users for the applications and environments of which they are Manager.

5. Super Admin: User with Super admin privilege has unrestricted access to all Devtron resources. Super admin can create, modify, delete and view any Devtron resource without any restriction; its like Superman without the weakness of Kryptonite. Super Admin can also add and delete user access across any Devtron resource, add delete git repository credentials, container registry credentials, cluster and environment.

User Roles And Permissions

1. Custom Applications

2. Helm Charts

3. User Access

4. Global Configurations

Add User

To add a user, go to the Authorization > User Permissions section of Global Configurations. Click Add user.

There are two types of permissions in Devtron:

Assign Super admin permission

To assign a super admin access, go to the Authorization > User Permissions section of Global Configurations.

• Click Add user.

• Provide the email address of a user. You can add more than one email address. Please note that email address must be same as that in the email field in the JWT token returned by OIDC provider.

• Select Super admin permission and click Save.

Note:

• Only users with Super admin permission can assign super admin permissions to a user.

• We suggest that super admin access must be given to the selected users only.

Assign Specific permissions

To assign a specific permission, go to the Authorization > User Permissions section of Global Configurations.

• Click Add user.

• Provide the email address of a user. You can add more than one email address. Please note that email address must be same as that in the email field in the JWT token returned by OIDC provider.

• Select Specific permissions.

• Select the group permission from the drop-down list, if required.

Devtron Apps Permissions

In Devtron Apps option, you can provide access to a user to manage permission for custom apps created using Devtron.

Provide the information in the following fields:

You can add multiple rows for Devtron app permission.

Once you have finished assigning the appropriate permissions for the users, Click Save.

Helm Apps Permissions

In Helm Apps option, you can provide access to a user to manage permission for Helm apps deployed from Devtron or outside Devtron.

Provide the information in the following fields:

You can add multiple rows for Devtron app permission.

Once you have finished assigning the appropriate permissions for the users, Click Save.

Kubernetes Resources Permissions

Note: Only super admin users will be able to see Kubernetes Resources tab and provide permission to other users to access Resource Browser.

To provide Kubernetes resource permission, click Add permission.

On the Kubernetes resource permission, provide the information in the following fields:

You can add multiple rows for Kubernetes resource permission.

Once you have finished assigning the appropriate permissions for the users, Click Save.

Chart Group Permissions

In Chart group permission option, you can manage the access of users for Chart Groups in your project.

NOTE: You can only give users the ability to create or edit, not both.

Click Saveonce you have configured all the required permissions for the users.

Edit User Permissions

You can edit the user permissions by clicking on the downward arrow.

Edit the user permissions.

After you have done editing the user permissions, click Save.

If you want to delete the user/users with particular permissions, click Delete.

Prerequisites

A verified account on . Okta activates your account only if email verification is successful.

Here's a reference guide to set up your Okta org and application:

Tutorial

Steps on Okta Admin Console

Once your Okta org is set up, create an app integration on Okta to get a Client ID and Client Secret.

1. In the Admin Console, go to Applications → Applications.

2. Click Create App Integration.

3. Select OIDC - OpenID Connect as the Sign-in method.

1. Select Web as the application type and click Next.

2. On the App Integration page:

   • Give a name to your application.

   • Select the Interaction Code and Refresh Token checkbox.

   • Now go to Devtron's Global Configurations → SSO Login Services → OIDC.

   • Copy the redirect URI given in the helper text (might look like: https://xxx.xxx.xxx/xxx/callback).

   • Return to the Okta screen, and remove the prefilled value in Sign-in redirect URIs.

   • Paste the copied URI in Sign-in redirect URIs.

   • Click Save.

3. On the General tab:

   • Note the Client ID value.

   • Click the Edit option.

   • In Client Authentication, choose Client Secret.

   • Click Save.

   • Click Generate new secret.

   • Note the Client Secret value.

Steps on Devtron

1. Go to the Global Configurations → SSO Login Services → OIDC.

2. In the URL field, enter the Devtron application URL (a valid https link) where it is hosted.

3. Under Configuration tab, locate the config object, and provide the clientID and clientSecret of the app integration you created on Okta.

5. Provide issuer value as https://${yourOktaDomain}. Replace ${yourOktaDomain} with your domain on Okta as shown in the video.

6. For providing redirectURI or callbackURI registered with the SSO provider, you can either select Configuration or Sample Script. Note that the redirect URI is already given in the helper text (as seen in the previous section).

7. Click Save to create and activate Okta SSO login.

Now your users will be able to log in to Devtron using the Okta authentication method. Note that existing signed-in users will be logged out and they have to log in again using their OIDC account.

Sample Configuration