Identity providers#

The Identity providers service supports external Identity Provider (IdP) for users to log in to K2 Cloud. The identity provider connects to the cloud using OpenID Connect (OIDC), an OAuth 2.0 protocol implementation. The identity provider can be any OIDC compliant provider, such as AD FS, Azure, and Keycloak.

Integration of the identity provider with the IAM cloud service enables centralized user management in the cloud. If the provider is properly configured, groups are synchronized between the provider and K2 Cloud using the token mechanism. Adding/removing user to/from an group automatically grants/revokes the rights granted to the respective identity provider group in the cloud. Thus, cloud access is controlled without need to set privileges for each user individually.

Note

Users who use IdP to log in to K2 Cloud, are treated as temporary users. Therefore, we recommend these users to work via web interface only and avoid using their local accounts in automation tools. For these purposes, creating standard cloud users would be still a better option.

Note

Integration with IdP allows you to control access to all cloud resources. In one of the upcoming releases, we are going to enable logging in to the object storage using IdP.

For Active Directory, Azure or Keycloak users to access K2 Cloud, preconfigure the identity provider, configure K2 Cloud integration point, and create groups with the required privileges.

Attention

When a user connects to the cloud, the identity provider must pass the following claims:

  • upn or preferred_username with a unique user ID (login, email address, etc.);

  • group or groups with a list of groups (in the cloud, you must specify the group names exactly as they are passed in id_token).

Note

To log in to the cloud, users should use a link in the following format: https://<name>.idp.k2.cloud, where <name> is the provider name in K2 Cloud.

Writing to the activity log#

The activity log stores the events of web interface session creation/deletion. If a session is created after authorization through an identity provider, the following events are logged:

  • An ADOpenSession event when a user logs in.

  • An AutoCloseSession event when a session is automatically closed on timeout. Access is terminated on the identity provider side, so this event occurs only some time after the user logs out.

IdP and cloud synchronization#

Access right are synchronized using tokens. The cloud regularly polls IdP server and makes necessary changes to the user’s privileges. For example, if a user is removed from a group, he/she is automatically deprived of project and global grants assigned to the identity provider group of the same name in the cloud.

Upon the first logging in, OpenId Connect sends three keys, or tokens, such as id_token, access_token and optionally refresh_token. The first token contains information required for logging in (user login and group name), the second one provides the key to access resources, while the third token refreshes keys. The access_token and refresh_token have their own predetermined lifetimes.

For synchronization, the cloud requests tokens every 15 minutes using refresh_token. If IdP is not configured for sending refresh_token, synchronization does not function and the account will be locked after access_token lifetime expires.

If refresh_token is sent, then tokens, including id_token, are requested every 15 minutes. If authorization-related (i.e. group membership) information in the token is changed, user rights in the cloud will be updated.

The user access is locked after refresh_token lifetime expires. To regain access to cloud resources, the user should log into the cloud again.

Cloud integration point setup#

To set up the integration point in the cloud, create a provider. If your company uses several Active Directory or Azure Active Directory services or Realms in Keycloak, then you can create a separate provider for each of them.

Create a provider#

To set up the provider:

  1. Go to IAM Identity providers Providers section in K2 Cloud web interface.

  2. Click Create.

  3. Specify the provider name.

    Note

    Its name should be unique within K2 Cloud. It may contain low-case Latin letters, digits, and hyphens and should have 4-10 characters in total.

    When your enter the name, a generated link to the cloud console entry point is displayed in the lower part of the dialog window. This link should be specified as Redirect URI when configuring OpenID Connect in IdP.

  4. In the Client ID field, paste the Client Identifier that you specified when configuring IdP.

  5. In the Client secret field, paste the client secret that was generated when configuring IdP.

  6. Specify URLs of endpoints for authentication, tokens, and session termination. Below are the examples of URLs for AD FS, Azure, and Keycloak (specific URL format may vary).

    By default, the full address to the OAuth endpoint is https://<server_address>/adfs/oauth2/, where server_address is the AD FS server address. Accordingly, you need to specify the following addresses:

    How to obtain endpoint URLs in case of Azure is described in in the instruction. You need to copy URLs for authorization_endpoint, token_endpoint and end_session_endpoint. Below are examples of possible URLs that you should enter in the appropriate fields:

    Endpoints for Keycloak can be found in the configuration file for OpenID Connect endpoints (for details, see the instruction for connecting Keycloack). You need to copy URLs for authorization_endpoint, token_endpoint and end_session_endpoint. Below are examples of possible URLs that you should enter in the appropriate fields:

  7. Click Create.

Change provider parameters#

You can view the current settings of the integration point (provider) in the Information tab on the provider page:

  • provider name;

  • client ID used by IdP to recognize the client application;

  • client secret;

  • addresses of endpoints for authentication, tokens, and session termination;

  • address of the entry point to the cloud console for users.

To change their values, do the following:

  1. Go to IAM Identity providers Providers section.

  2. Click the provider name in the resource table to go to its page.

  3. To edit a certain parameter, open Information tab and click the symbol next to it.

Note

The entry point address changes automatically if the name of the provider changes.

Delete a provider#

Attention

When the provider is deleted, its users will lose access to K2 Cloud.

You can delete a provider using one of the following methods.

To delete several providers at a time:

  1. Go to IAM Identity providers Providers section.

  2. choose one or more providers to be deleted in the resource table.

  3. Click Delete.

  4. In the dialog window, confirm the action.

Using this method, you can delete only the selected provider:

  1. Go to IAM Identity providers Providers section.

  2. Click the provider name in the resource table to go to its page.

  3. Click :Delete in the Information tab.

  4. In the dialog window, confirm the action.

IdP group management#

Groups help you manage user access to K2 Cloud resources. When logging into the cloud, users gain the rights automatically depending on the group they belong to. If a user does not belong to a group or no cloud privileges are assigned to his/her group, the user can only view his/her profile.

The same user can be a member of more than one group at a time. He/she gets a set of privileges granted to these groups in the cloud. Groups can have overlapping privileges.

Create an IdP group#

To create an identity provider group in the cloud:

  1. Go to IAM Identity providers Groups section.

  2. Click Create.

  3. Choose a provider from the drop-down list in the dialog window.

  4. Specify the group name.

    Note

    The IdP group name must be exactly the same as the group name passed in the Claims named group.

  5. Click Create.

If you need to create more than one group, repeat the above steps.

Add a group to the project#

To allow identity provider group members to use resources of the particular project, add the identity provider group to the project and assign project privileges to it. The project privileges can be set either when adding the project or later. To set the privileges, add the identity provider group to an IAM group or assign an IAM policy to it (for privilege details, see IAM documentation). We recommend using IAM groups rather than policies to grant privileges.

  1. Go to IAM Identity providers Groups section.

  2. Choose the necessary provider in the drop-down list.

  3. Find the group in the resource table and click the group ID to go to its page.

  4. Open the Projects tab and click Add.

  5. To make the project resources accessible by group members, choose the respective project in the dialog window. Click Next to go to the next step.

  6. Select the IAM groups to be used to grant privileges in the project and click Select. For details about IAM groups and relevant privileges, see the IAM documentation.

    You can skip this step and use policies to grant privileges. Click Next to proceed to the next step.

  7. Select the IAM policies to be used to grant privileges in the project and click Select. For more details about the IAM policies and relevant privileges, see the IAM documentation. If you have added the groups, you may omit adding the policies, otherwise select at least one policy. Click Add to save the group’s privileges in the selected project.

If you have to provide an IdP group with access to several projects, repeat the above steps.

Exclude a group from the project#

When an identity provider group is removed from a project, the group members may lose access to some of the project resources. Which resources will remain available to a particular user depends on what other groups he/she belongs to are still associated with the project and what privileges they give.

To remove a group from the project:

  1. Go to IAM Identity providers Groups section.

  2. Choose the necessary provider in the drop-down list.

  3. Find the group in the resource table and click the group ID to go to its page.

  4. Open the Projects tab.

  5. Choose the project from the resource table and click Remove. Note, that the project itself will not be deleted.

  6. In the dialog window, confirm the action.

Attention

Deleting a project on the project page deletes the project with all the resources.

Delete an IdP group#

When an IdP group is removed, users may lose access to projects to which the group was previously added. Which projects will remain available to a particular user depends on what other groups he/she belongs to and what projects these groups are added to.

To delete a group:

  1. Go to IAM Identity providers Groups section.

  2. Choose the necessary provider in the drop-down list.

  3. In the resource table, choose a group to be deleted. You can delete several groups at the same time.

  4. Click Delete.

  5. In the dialog window, confirm the action.

A group can also be deleted in the Information tab on the group page.

Group privilege setup#

You can provide an IdP group with access to resources (i.e. services, as per the cloud terminology) of any project and set global grants. These privileges are granted to all users that are members of this group. Project and global grants for the group are set up in a similar way as those for cloud users.

Add project privileges#

To provide an IdP group with access to project resources, do the following:

  1. Go to IAM Identity providers Groups section.

  2. Choose the necessary provider in the drop-down list.

  3. Find the group in the resource table and click the group ID to go to its page.

  4. Open the Project tab and click Set up near the desired project.

  5. Open the Groups or Policies tab depending on how you want to grant privileges to the identity provider group. Click Add.

  6. In the window that opens, select the groups/IAM policies you need and click Select to include them in the selection list.

  7. To save the selected privileges, click Add.

Add global grants#

You can provide the IdP group with global grants for IAM and billing services. These privileges will be granted to all users that are members of this group. Therefore, be cautious when providing them. For details about administrative privileges see IAM documentation.

  1. Go to IAM Identity providers Groups section.

  2. Choose the necessary provider in the drop-down list.

  3. Find the group in the resource table and click the group ID to go to its page.

  4. Open the Global grants tab and click Set up.

  5. Open the Groups or Policies tab depending on how you want to grant privileges to the identity provider group. Click Add.

  6. In the window that opens, select the groups/IAM policies you need and click Select to include them in the selection list.

  7. To save the selected privileges, click Add.

Limit project privileges#

To restrict the access of members of the identity provider group to project resources, follow this steps:

  1. Go to IAM Identity providers Groups section.

  2. Choose the necessary provider in the drop-down list.

  3. Find the group in the resource table and click the group ID to go to its page.

  4. Open the Project tab and click Set up near the desired project.

  5. Open the Groups or Policies tab depending on what privileges you want to revoke.

  6. In the resource table, select the groups/IAM policies to be deleted and click Delete.

  7. In the dialog window, confirm the action.

Note

Users can still have access to project resources if similar privileges are granted to them in other groups.

Limit project grants#

To restrict the global grants for members of the identity provider group, follow the steps:

  1. Go to IAM Identity providers Groups section.

  2. Choose the necessary provider in the drop-down list.

  3. Find the group in the resource table and click the group ID to go to its page.

  4. Open the Global grants tab and click Set up.

  5. Open the Groups or Policies tab depending on what privileges you want to revoke.

  6. In the resource table, select the groups/IAM policies to be deleted and click Delete.

  7. In the dialog window, confirm the action.

Configuring an integration point for IdP#

Configure integration point in AD FS#

To be able to use Active Directory Federation Service (AD FS) as an identity provider for K2 Cloud, you should set up an AD FS integration point.

With proper settings, users can use their local accounts to log in to the cloud. If a user has already logged in to his/her local account, the Single Sign-On (SSO) feature enables automatic logging in to the cloud.

Note

You should have an AD FS server farm installed and set up.. The step-by-step instruction describes how to set up AD FS for Windows Server 2016.

Configure OpenID Connect in AD FS#

To connect to K2 Cloud via OpenID Connect protocol, you need to configure Application Groups.

  1. Open AD FS Management control panel in Tools menu in the right upper corner of Server Manager of AD FS server.

  2. Select Application Groups in the left menu.

  3. Click Add Application Group… in the right menu or right-click Application Groups and select Add Application Group….

  4. Specify an arbitrary name for Application Group, select Server application accessing a web API in Client-Server Applications box, and click Next.

    ../../_images/idp_access_web_API-step-4.png

  5. Copy and save Client Identifier; you will use it in the next steps and when setting up an integration point in K2 Cloud. AD FS employs client identifier to detect a client application.

  6. Insert https://<name>.idp.k2.cloud in the Redirect URI field. Here <name> is the name of the provider in K2 Cloud. Click Add and then click Next to advance to the next step.

    ../../_images/idp_redirect-step-5.png

  7. Generate a client secret by selecting Generate a shared secret. Save the secret — it is required to configure the integration point in the cloud. If you lose the secret, you will have to generate it again. Click Next to advance to the next step.

    ../../_images/idp_shared_secret-step-6.png

  8. In the Identifier field, specify the saved Client Identifier and click Add. Click Next to advance to the next step.

    ../../_images/idp_identifier-step-7.png

  9. Select the access control policy in compliance with the accepted company rules.

  10. Set access permissions for client applications. Enable allatclaims and openid options.

    ../../_images/idp_permissions.png

  11. Check the specified parameters and complete the creation of the Application Group.

Configure Claims for Active Directory#

Note

In case of AD FS, you do not need to manually set the upn claim because it is generated automatically.

You should set up Claims for user groups so that information about user membership in groups could be transferred to the cloud.

  1. Open AD FS Management control panel in Tools menu in the right upper corner of Server Manager of AD FS server.

  2. Select Application Groups in the left menu.

  3. Double-click the name of the Application Group created earlier, select Web API, and click Edit.

    ../../_images/idp_claims_edit-step-3.png

  4. Open the Issuance transform rule tab and click Add rule….

    ../../_images/idp_claims_add_rule-step-4.png

  5. Select Send LDAP Attributes as Claims as Claim rule template and click Next.

    ../../_images/idp_claims_template_step-5.png

  6. Specify the rule name and choose Active Directory as Attribute Store.

  7. In the table below, select Token-Groups Unqualified Names as LDAP Attribute and select Group as Outgoing Claim Type.

    Note

    Using Unqualified Name is not mandatory and is provided just as an example.

    ../../_images/idp_claims_type-step-6.png

  8. Click Finish to create the rule and close the property editing windows.

Configure integration point in Azure#

To use Azure as an IdP for K2 Cloud, first register and configure an application in Azure Active Directory.

Application registration in Azure Active Directory#

  1. In Azure cloud management console, go to Azure Directory Services and, in Manage menu, select App registrations.

    ../../_images/azure-step-1.png

  2. Click New registration and on the page that opens, specify the application name and select the required account type. You may skip Redirect URI for now.

    ../../_images/azure-step-2.png

  3. Click Register.

Obtain settings for an integration point in K2 Cloud#

After registering the application, save the necessary parameters for configuring the integration point in K2 Cloud.

  1. Open the page of the created application (it opens automatically after registration) and, in the Overview section, copy and save Application (client) ID. It must be entered as Client ID when configuring a provider in K2 Cloud.

    ../../_images/azure-step-3-cut.png

  2. In addition, you will need URLs for authentication, tokens, and end-of-session endpoints. To find them, in the Overview section, click Endpoints and copy the link to OpenID Connect metadata document.

    ../../_images/azure-step-4_1.png

    Follow this link and in the document that opens, find and save links to authorization_endpoint, token_endpoint and end_session_endpoint.

    ../../_images/azure-step-4_2.png

  3. To generate a client secret, in the Manage menu, go to the Certificates & secrets section and, in the Client secrets tab, click New client secret. On the page that opens, enter the secret description and its expiry date and click Add. Copy and save the secret value.

    Attention

    Save the secret right away. When you re-open the Client secrets tab, the secret will be hidden and you will have to generate it again.

    ../../_images/azure-step-5.png

Now, you have everything you need to configure an integration point in K2 Cloud. Upon configuring this point, you can complete the application configuration in Azure Active Directory.

Configure the application in Azure Active Directory#

  1. The application needs to “know” a K2 Cloud console entry point. To set it, go to the Authentication section and click Add platform. In the window that opens, select the Web card and, in the Redirect URI field, enter the link to the entry point that was generated when creating the provider in K2 Cloud (https://<name>.idp.k2.cloud). Click Configure.

    ../../_images/azure-step-6.png

  2. Set API permissions. To do this, go to the API Permissions section and click Add a permission. Go to the Microsoft Graph card and then open the Delegated permissions card. Enable the following permissions for OpenId: offline_access, openid, and profile. Click Add permissions to save them.

    ../../_images/azure-step-7.png

  3. Then, configure Claims. To do this, go to the Token Configuration section and click Add group claims. On the page that opens, in the Select group types to include in Access, ID, and SAML tokens block, select Security Groups. In the Customize token properties by type block, select sAMAccountName as the ID type.

    Note

    The sAMAccountName ID is only available to synchronized Windows Server Active Directory users, otherwise a Group ID will be sent. For details about configuring group properties, see Microsoft documentation.

    Click Add to save parameters.

    ../../_images/azure-step-8.png

Configure integration point in Keycloak#

To use Keycloak as an identity provider for K2 Cloud, configure the respective client connection.

Configure OpenID Connect client in Keycloak#

Create a client with the OpenID Connect type first.

  1. In Keycloak admin console, select necessary Realm.

  2. In the menu section Manage, select Clients and click Create client.

  3. In the General Settings step, select OpenID Connect as Client Type and specify the client name in the Client ID field. To advance to the next step, click Next.

    ../../_images/keycloak_add_client_step-3.png

  4. In the Configuration Options step, enable Client Authentication and check that Authentication flow is set to Standard flow.

    ../../_images/keycloak_auth_step-4.png

  5. To create a client, click Save.

Next, specify the cloud entry point for the client you created:

  1. In the Clients List of the Clients section, select the created client and open its Client details.

  2. In the Settings tab, find the Valid Redirect URI field and enter the https://<name>.idp.k2.cloud address, where <name> is the name of the provider in K2 Cloud.

    ../../_images/keycloak_redirect.png

In addition, you will need the following information to set up an integration point in the cloud:

  • Client secret. You can find it in the Credentials tab on the Client Details page.

  • Endpoint addresses. You can view the endpoint configuration by clicking the OpenID Endpoint Configuration link in the General tab on the used Realm page in the Realm settings section.

Set up Claims#

Claims in Keycloak can be configured in many ways, one of which is briefly described below.

  1. In the Client scopes section, create a new or select an existing context that you want to use for the client.

  2. After selecting the desired context, go to the Mappers tab and click Configure a new mapper for a new client or Add mapper and By configuration for an existing one.

  3. To set the upn claim, select, for example, User Attribute. In the Name field, specify an arbitrary name for mapper, and in the User Attribute field, the name of the attribute from which the user ID will be retrieved, for example, login. In the Token Claim Name field, enter upn.

    ../../_images/keycloak_upn_claim.png

  4. To set the group claim, select Group Membership. In the Name field, enter an arbitrary name for mapper, and in the Token Claim Name field, enter group.

    ../../_images/keycloak_group_claim.png

  5. Assign the created context to your client if it has not been assigned to it yet. To apply the context, select the Default option when adding it.

    ../../_images/keycloak_add_scope.png

To check which user claims will be passed to the cloud:

  1. Open Client scopes on the Clients details page of your client.

  2. Go to the Evaluate tab and enter your username in the User field.

  3. Click Generated ID token in the right menu to view the generated token.

Attention

When creating groups in the cloud, their names must be specified exactly as they are passed in the token, i.e. in this example /developers and /test_group.

../../_images/keycloak_token_check.png